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; 020 021/** 022 * <p>An immutable pair consisting of two {@code Object} elements.</p> 023 * 024 * <p>Although the implementation is immutable, there is no restriction on the objects 025 * that may be stored. If mutable objects are stored in the pair, then the pair 026 * itself effectively becomes mutable. The class is also {@code final}, so a subclass 027 * can not add undesirable behaviour.</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 * 034 * @since 3.0 035 */ 036public final class ImmutablePair<L, R> extends Pair<L, R> { 037 038 /** 039 * An empty array. 040 * <p> 041 * Consider using {@link #emptyArray()} to avoid generics warnings. 042 * </p> 043 * 044 * @since 3.10. 045 */ 046 public static final ImmutablePair<?, ?>[] EMPTY_ARRAY = new ImmutablePair[0]; 047 048 /** 049 * An immutable pair of nulls. 050 */ 051 // This is not defined with generics to avoid warnings in call sites. 052 @SuppressWarnings("rawtypes") 053 private static final ImmutablePair NULL = of(null, null); 054 055 /** Serialization version */ 056 private static final long serialVersionUID = 4954918890077093841L; 057 058 /** 059 * Returns the empty array singleton that can be assigned without compiler warning. 060 * 061 * @param <L> the left element type 062 * @param <R> the right element type 063 * @return the empty array singleton that can be assigned without compiler warning. 064 * 065 * @since 3.10. 066 */ 067 @SuppressWarnings("unchecked") 068 public static <L, R> ImmutablePair<L, R>[] emptyArray() { 069 return (ImmutablePair<L, R>[]) EMPTY_ARRAY; 070 } 071 072 /** 073 * Returns an immutable pair of nulls. 074 * 075 * @param <L> the left element of this pair. Value is {@code null}. 076 * @param <R> the right element of this pair. Value is {@code null}. 077 * @return an immutable pair of nulls. 078 * @since 3.6 079 */ 080 public static <L, R> ImmutablePair<L, R> nullPair() { 081 return NULL; 082 } 083 084 /** 085 * <p>Creates an immutable pair of two objects inferring the generic types.</p> 086 * 087 * <p>This factory allows the pair to be created using inference to 088 * obtain the generic types.</p> 089 * 090 * @param <L> the left element type 091 * @param <R> the right element type 092 * @param left the left element, may be null 093 * @param right the right element, may be null 094 * @return a pair formed from the two parameters, not null 095 */ 096 public static <L, R> ImmutablePair<L, R> of(final L left, final R right) { 097 return new ImmutablePair<>(left, right); 098 } 099 100 /** 101 * <p>Creates an immutable pair from an existing pair.</p> 102 * 103 * <p>This factory allows the pair to be created using inference to 104 * obtain the generic types.</p> 105 * 106 * @param <L> the left element type 107 * @param <R> the right element type 108 * @param pair the existing pair. 109 * @return a pair formed from the two parameters, not null 110 * @since 3.10 111 */ 112 public static <L, R> ImmutablePair<L, R> of(final Map.Entry<L, R> pair) { 113 final L left; 114 final R right; 115 if (pair != null) { 116 left = pair.getKey(); 117 right = pair.getValue(); 118 } else { 119 left = null; 120 right = null; 121 } 122 return new ImmutablePair<>(left, right); 123 } 124 125 /** Left object */ 126 public final L left; 127 128 /** Right object */ 129 public final R right; 130 131 /** 132 * Create a new pair instance. 133 * 134 * @param left the left value, may be null 135 * @param right the right value, may be null 136 */ 137 public ImmutablePair(final L left, final R right) { 138 super(); 139 this.left = left; 140 this.right = right; 141 } 142 143 /** 144 * {@inheritDoc} 145 */ 146 @Override 147 public L getLeft() { 148 return left; 149 } 150 151 /** 152 * {@inheritDoc} 153 */ 154 @Override 155 public R getRight() { 156 return right; 157 } 158 159 /** 160 * <p>Throws {@code UnsupportedOperationException}.</p> 161 * 162 * <p>This pair is immutable, so this operation is not supported.</p> 163 * 164 * @param value the value to set 165 * @return never 166 * @throws UnsupportedOperationException as this operation is not supported 167 */ 168 @Override 169 public R setValue(final R value) { 170 throw new UnsupportedOperationException(); 171 } 172 173}