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 * http://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. The class is also {@code final}, so a subclass 028 * can not add undesirable behavior.</p> 029 * 030 * <p>#ThreadSafe# if both paired objects are thread-safe</p> 031 * 032 * @param <L> the left element type 033 * @param <R> the right element type 034 * 035 * @since 3.0 036 */ 037public class ImmutablePair<L, R> extends Pair<L, R> { 038 039 /** 040 * An empty array. 041 * <p> 042 * Consider using {@link #emptyArray()} to avoid generics warnings. 043 * </p> 044 * 045 * @since 3.10. 046 */ 047 public static final ImmutablePair<?, ?>[] EMPTY_ARRAY = {}; 048 049 /** 050 * An immutable pair of nulls. 051 */ 052 // This is not defined with generics to avoid warnings in call sites. 053 @SuppressWarnings("rawtypes") 054 private static final ImmutablePair NULL = new ImmutablePair<>(null, null); 055 056 /** Serialization version */ 057 private static final long serialVersionUID = 4954918890077093841L; 058 059 /** 060 * Returns the empty array singleton that can be assigned without compiler warning. 061 * 062 * @param <L> the left element type 063 * @param <R> the right element type 064 * @return the empty array singleton that can be assigned without compiler warning. 065 * 066 * @since 3.10. 067 */ 068 @SuppressWarnings("unchecked") 069 public static <L, R> ImmutablePair<L, R>[] emptyArray() { 070 return (ImmutablePair<L, R>[]) EMPTY_ARRAY; 071 } 072 073 /** 074 * Creates an immutable pair of two objects inferring the generic types. 075 * 076 * <p>This factory allows the pair to be created using inference to 077 * obtain the generic types.</p> 078 * 079 * @param <L> the left element type 080 * @param <R> the right element type 081 * @param left the left element, may be null 082 * @return a pair formed from the two parameters, not null 083 * @since 3.11 084 */ 085 public static <L, R> Pair<L, R> left(final L left) { 086 return ImmutablePair.of(left, null); 087 } 088 089 /** 090 * Returns an immutable pair of nulls. 091 * 092 * @param <L> the left element of this pair. Value is {@code null}. 093 * @param <R> the right element of this pair. Value is {@code null}. 094 * @return an immutable pair of nulls. 095 * @since 3.6 096 */ 097 @SuppressWarnings("unchecked") 098 public static <L, R> ImmutablePair<L, R> nullPair() { 099 return NULL; 100 } 101 102 /** 103 * Creates an immutable pair of two objects inferring the generic types. 104 * 105 * <p>This factory allows the pair to be created using inference to 106 * obtain the generic types.</p> 107 * 108 * @param <L> the left element type 109 * @param <R> the right element type 110 * @param left the left element, may be null 111 * @param right the right element, may be null 112 * @return a pair formed from the two parameters, not null 113 */ 114 public static <L, R> ImmutablePair<L, R> of(final L left, final R right) { 115 return left != null || right != null ? new ImmutablePair<>(left, right) : nullPair(); 116 } 117 118 /** 119 * Creates an immutable pair from a map entry. 120 * 121 * <p>This factory allows the pair to be created using inference to 122 * obtain the generic types.</p> 123 * 124 * @param <L> the left element type 125 * @param <R> the right element type 126 * @param pair the existing map entry. 127 * @return a pair formed from the map entry 128 * @since 3.10 129 */ 130 public static <L, R> ImmutablePair<L, R> of(final Map.Entry<L, R> pair) { 131 return pair != null ? new ImmutablePair<>(pair.getKey(), pair.getValue()) : nullPair(); 132 } 133 134 /** 135 * Creates an immutable pair of two non-null objects inferring the generic types. 136 * 137 * <p>This factory allows the pair to be created using inference to 138 * obtain the generic types.</p> 139 * 140 * @param <L> the left element type 141 * @param <R> the right element type 142 * @param left the left element, may not be null 143 * @param right the right element, may not be null 144 * @return a pair formed from the two parameters, not null 145 * @throws NullPointerException if any input is null 146 * @since 3.13.0 147 */ 148 public static <L, R> ImmutablePair<L, R> ofNonNull(final L left, final R right) { 149 return of(Objects.requireNonNull(left, "left"), Objects.requireNonNull(right, "right")); 150 } 151 152 /** 153 * Creates an immutable pair of two objects inferring the generic types. 154 * 155 * <p>This factory allows the pair to be created using inference to 156 * obtain the generic types.</p> 157 * 158 * @param <L> the left element type 159 * @param <R> the right element type 160 * @param right the right element, may be null 161 * @return a pair formed from the two parameters, not null 162 * @since 3.11 163 */ 164 public static <L, R> Pair<L, R> right(final R right) { 165 return ImmutablePair.of(null, right); 166 } 167 168 /** Left object */ 169 public final L left; 170 171 /** Right object */ 172 public final R right; 173 174 /** 175 * Create a new pair instance. 176 * 177 * @param left the left value, may be null 178 * @param right the right value, may be null 179 */ 180 public ImmutablePair(final L left, final R right) { 181 this.left = left; 182 this.right = right; 183 } 184 185 /** 186 * {@inheritDoc} 187 */ 188 @Override 189 public L getLeft() { 190 return left; 191 } 192 193 /** 194 * {@inheritDoc} 195 */ 196 @Override 197 public R getRight() { 198 return right; 199 } 200 201 /** 202 * Throws {@link UnsupportedOperationException}. 203 * 204 * <p>This pair is immutable, so this operation is not supported.</p> 205 * 206 * @param value the value to set 207 * @return never 208 * @throws UnsupportedOperationException as this operation is not supported 209 */ 210 @Override 211 public R setValue(final R value) { 212 throw new UnsupportedOperationException(); 213 } 214 215}