001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * https://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.commons.lang3.tuple; 018 019import java.util.Map; 020import java.util.Objects; 021 022/** 023 * An immutable pair consisting of two {@link Object} elements. 024 * 025 * <p>Although the implementation is immutable, there is no restriction on the objects 026 * that may be stored. If mutable objects are stored in the pair, then the pair 027 * itself effectively becomes mutable.</p> 028 * 029 * <p>#ThreadSafe# if both paired objects are thread-safe</p> 030 * 031 * @param <L> the left element type 032 * @param <R> the right element type 033 * @since 3.0 034 */ 035public class ImmutablePair<L, R> extends Pair<L, R> { 036 037 /** 038 * An empty array. 039 * <p> 040 * Consider using {@link #emptyArray()} to avoid generics warnings. 041 * </p> 042 * 043 * @since 3.10 044 */ 045 public static final ImmutablePair<?, ?>[] EMPTY_ARRAY = {}; 046 047 /** 048 * An immutable pair of nulls. 049 */ 050 // This is not defined with generics to avoid warnings in call sites. 051 @SuppressWarnings("rawtypes") 052 private static final ImmutablePair NULL = new ImmutablePair<>(null, null); 053 054 /** Serialization version */ 055 private static final long serialVersionUID = 4954918890077093841L; 056 057 /** 058 * Returns the empty array singleton that can be assigned without compiler warning. 059 * 060 * @param <L> the left element type 061 * @param <R> the right element type 062 * @return the empty array singleton that can be assigned without compiler warning. 063 * @since 3.10 064 */ 065 @SuppressWarnings("unchecked") 066 public static <L, R> ImmutablePair<L, R>[] emptyArray() { 067 return (ImmutablePair<L, R>[]) EMPTY_ARRAY; 068 } 069 070 /** 071 * Creates an immutable pair of two objects inferring the generic types. 072 * 073 * <p>This factory allows the pair to be created using inference to 074 * obtain the generic types.</p> 075 * 076 * @param <L> the left element type 077 * @param <R> the right element type 078 * @param left the left element, may be null 079 * @return a pair formed from the two parameters, not null 080 * @since 3.11 081 */ 082 public static <L, R> Pair<L, R> left(final L left) { 083 return of(left, null); 084 } 085 086 /** 087 * Returns an immutable pair of nulls. 088 * 089 * @param <L> the left element of this pair. Value is {@code null}. 090 * @param <R> the right element of this pair. Value is {@code null}. 091 * @return an immutable pair of nulls. 092 * @since 3.6 093 */ 094 @SuppressWarnings("unchecked") 095 public static <L, R> ImmutablePair<L, R> nullPair() { 096 return NULL; 097 } 098 099 /** 100 * Creates an immutable pair of two objects inferring the generic types. 101 * 102 * <p>This factory allows the pair to be created using inference to 103 * obtain the generic types.</p> 104 * 105 * @param <L> the left element type 106 * @param <R> the right element type 107 * @param left the left element, may be null 108 * @param right the right element, may be null 109 * @return a pair formed from the two parameters, not null 110 */ 111 public static <L, R> ImmutablePair<L, R> of(final L left, final R right) { 112 return left != null || right != null ? new ImmutablePair<>(left, right) : nullPair(); 113 } 114 115 /** 116 * Creates an immutable pair from a map entry. 117 * 118 * <p>This factory allows the pair to be created using inference to 119 * obtain the generic types.</p> 120 * 121 * @param <L> the left element type 122 * @param <R> the right element type 123 * @param pair the existing map entry. 124 * @return a pair formed from the map entry 125 * @since 3.10 126 */ 127 public static <L, R> ImmutablePair<L, R> of(final Map.Entry<L, R> pair) { 128 return pair != null ? new ImmutablePair<>(pair.getKey(), pair.getValue()) : nullPair(); 129 } 130 131 /** 132 * Creates an immutable pair of two non-null objects inferring the generic types. 133 * 134 * <p>This factory allows the pair to be created using inference to 135 * obtain the generic types.</p> 136 * 137 * @param <L> the left element type 138 * @param <R> the right element type 139 * @param left the left element, may not be null 140 * @param right the right element, may not be null 141 * @return a pair formed from the two parameters, not null 142 * @throws NullPointerException if any input is null 143 * @since 3.13.0 144 */ 145 public static <L, R> ImmutablePair<L, R> ofNonNull(final L left, final R right) { 146 return of(Objects.requireNonNull(left, "left"), Objects.requireNonNull(right, "right")); 147 } 148 149 /** 150 * Creates an immutable pair of two objects inferring the generic types. 151 * 152 * <p>This factory allows the pair to be created using inference to 153 * obtain the generic types.</p> 154 * 155 * @param <L> the left element type 156 * @param <R> the right element type 157 * @param right the right element, may be null 158 * @return a pair formed from the two parameters, not null 159 * @since 3.11 160 */ 161 public static <L, R> Pair<L, R> right(final R right) { 162 return of(null, right); 163 } 164 165 /** Left object */ 166 public final L left; 167 168 /** Right object */ 169 public final R right; 170 171 /** 172 * Create a new pair instance. 173 * 174 * @param left the left value, may be null 175 * @param right the right value, may be null 176 */ 177 public ImmutablePair(final L left, final R right) { 178 this.left = left; 179 this.right = right; 180 } 181 182 /** 183 * {@inheritDoc} 184 */ 185 @Override 186 public L getLeft() { 187 return left; 188 } 189 190 /** 191 * {@inheritDoc} 192 */ 193 @Override 194 public R getRight() { 195 return right; 196 } 197 198 /** 199 * Throws {@link UnsupportedOperationException}. 200 * 201 * <p>This pair is immutable, so this operation is not supported.</p> 202 * 203 * @param value the value to set 204 * @return never 205 * @throws UnsupportedOperationException as this operation is not supported 206 */ 207 @Override 208 public R setValue(final R value) { 209 throw new UnsupportedOperationException(); 210 } 211 212}