View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.lang3.tuple;
18  
19  /**
20   * <p>An immutable pair consisting of two {@code Object} elements.</p>
21   *
22   * <p>Although the implementation is immutable, there is no restriction on the objects
23   * that may be stored. If mutable objects are stored in the pair, then the pair
24   * itself effectively becomes mutable. The class is also {@code final}, so a subclass
25   * can not add undesirable behaviour.</p>
26   *
27   * <p>#ThreadSafe# if both paired objects are thread-safe</p>
28   *
29   * @param <L> the left element type
30   * @param <R> the right element type
31   *
32   * @since Lang 3.0
33   */
34  public final class ImmutablePair<L, R> extends Pair<L, R> {
35  
36      /**
37       * An immutable pair of nulls.
38       */
39      // This is not defined with generics to avoid warnings in call sites.
40      @SuppressWarnings("rawtypes")
41      private static final ImmutablePair NULL = ImmutablePair.of(null, null);
42  
43      /** Serialization version */
44      private static final long serialVersionUID = 4954918890077093841L;
45  
46      /**
47       * Returns an immutable pair of nulls.
48       *
49       * @param <L> the left element of this pair. Value is {@code null}.
50       * @param <R> the right element of this pair. Value is {@code null}.
51       * @return an immutable pair of nulls.
52       * @since 3.6
53       */
54      @SuppressWarnings("unchecked")
55      public static <L, R> ImmutablePair<L, R> nullPair() {
56          return NULL;
57      }
58  
59      /** Left object */
60      public final L left;
61      /** Right object */
62      public final R right;
63  
64      /**
65       * <p>Obtains an immutable pair of from two objects inferring the generic types.</p>
66       *
67       * <p>This factory allows the pair to be created using inference to
68       * obtain the generic types.</p>
69       *
70       * @param <L> the left element type
71       * @param <R> the right element type
72       * @param left  the left element, may be null
73       * @param right  the right element, may be null
74       * @return a pair formed from the two parameters, not null
75       */
76      public static <L, R> ImmutablePair<L, R> of(final L left, final R right) {
77          return new ImmutablePair<>(left, right);
78      }
79  
80      /**
81       * Create a new pair instance.
82       *
83       * @param left  the left value, may be null
84       * @param right  the right value, may be null
85       */
86      public ImmutablePair(final L left, final R right) {
87          super();
88          this.left = left;
89          this.right = right;
90      }
91  
92      //-----------------------------------------------------------------------
93      /**
94       * {@inheritDoc}
95       */
96      @Override
97      public L getLeft() {
98          return left;
99      }
100 
101     /**
102      * {@inheritDoc}
103      */
104     @Override
105     public R getRight() {
106         return right;
107     }
108 
109     /**
110      * <p>Throws {@code UnsupportedOperationException}.</p>
111      *
112      * <p>This pair is immutable, so this operation is not supported.</p>
113      *
114      * @param value  the value to set
115      * @return never
116      * @throws UnsupportedOperationException as this operation is not supported
117      */
118     @Override
119     public R setValue(final R value) {
120         throw new UnsupportedOperationException();
121     }
122 
123 }