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    *      https://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  import java.util.Objects;
20  
21  /**
22   * An immutable triple consisting of three {@link Object} elements.
23   *
24   * <p>Although the implementation is immutable, there is no restriction on the objects
25   * that may be stored. If mutable objects are stored in the triple, then the triple
26   * itself effectively becomes mutable.</p>
27   *
28   * <p>#ThreadSafe# if all three objects are thread-safe.</p>
29   *
30   * @param <L> the left element type.
31   * @param <M> the middle element type.
32   * @param <R> the right element type.
33   * @since 3.2
34   */
35  public class ImmutableTriple<L, M, R> extends Triple<L, M, R> {
36  
37      /**
38       * An empty array.
39       * <p>
40       * Consider using {@link #emptyArray()} to avoid generics warnings.
41       * </p>
42       *
43       * @since 3.10
44       */
45      public static final ImmutableTriple<?, ?, ?>[] EMPTY_ARRAY = {};
46  
47      /**
48       * An immutable triple of nulls.
49       */
50      // This is not defined with generics to avoid warnings in call sites.
51      @SuppressWarnings("rawtypes")
52      private static final ImmutableTriple NULL = new ImmutableTriple<>(null, null, null);
53  
54      /** Serialization version. */
55      private static final long serialVersionUID = 1L;
56  
57      /**
58       * Gets the empty array singleton that can be assigned without compiler warning.
59       *
60       * @param <L> the left element type.
61       * @param <M> the middle element type.
62       * @param <R> the right element type.
63       * @return the empty array singleton that can be assigned without compiler warning.
64       * @since 3.10
65       */
66      @SuppressWarnings("unchecked")
67      public static <L, M, R> ImmutableTriple<L, M, R>[] emptyArray() {
68          return (ImmutableTriple<L, M, R>[]) EMPTY_ARRAY;
69      }
70  
71      /**
72       * Gets the immutable triple of nulls singleton.
73       *
74       * @param <L> the left element of this triple. Value is {@code null}.
75       * @param <M> the middle element of this triple. Value is {@code null}.
76       * @param <R> the right element of this triple. Value is {@code null}.
77       * @return an immutable triple of nulls.
78       * @since 3.6
79       */
80      @SuppressWarnings("unchecked")
81      public static <L, M, R> ImmutableTriple<L, M, R> nullTriple() {
82          return NULL;
83      }
84  
85      /**
86       * Creates an immutable triple of three objects inferring the generic types.
87       *
88       * <p>This factory allows the triple to be created using inference to
89       * obtain the generic types.</p>
90       *
91       * @param <L> the left element type.
92       * @param <M> the middle element type.
93       * @param <R> the right element type.
94       * @param left  the left element, may be null.
95       * @param middle  the middle element, may be null.
96       * @param right  the right element, may be null.
97       * @return a triple formed from the three parameters, not null.
98       */
99      public static <L, M, R> ImmutableTriple<L, M, R> of(final L left, final M middle, final R right) {
100         return left != null | middle != null || right != null ? new ImmutableTriple<>(left, middle, right) : nullTriple();
101     }
102 
103     /**
104      * Creates an immutable triple of three non-null objects inferring the generic types.
105      *
106      * <p>This factory allows the triple to be created using inference to
107      * obtain the generic types.</p>
108      *
109      * @param <L> the left element type.
110      * @param <M> the middle element type.
111      * @param <R> the right element type.
112      * @param left  the left element, may not be null.
113      * @param middle  the middle element, may not be null.
114      * @param right  the right element, may not be null.
115      * @return a triple formed from the three parameters, not null.
116      * @throws NullPointerException if any input is null.
117      * @since 3.13.0
118      */
119     public static <L, M, R> ImmutableTriple<L, M, R> ofNonNull(final L left, final M middle, final R right) {
120         return of(Objects.requireNonNull(left, "left"), Objects.requireNonNull(middle, "middle"), Objects.requireNonNull(right, "right"));
121     }
122 
123     /** Left object. */
124 
125     public final L left;
126     /** Middle object. */
127     public final M middle;
128 
129     /** Right object. */
130     public final R right;
131 
132     /**
133      * Constructs a new triple instance.
134      *
135      * @param left  the left value, may be null.
136      * @param middle the middle value, may be null.
137      * @param right  the right value, may be null.
138      */
139     public ImmutableTriple(final L left, final M middle, final R right) {
140         this.left = left;
141         this.middle = middle;
142         this.right = right;
143     }
144 
145     /**
146      * {@inheritDoc}
147      */
148     @Override
149     public L getLeft() {
150         return left;
151     }
152 
153     /**
154      * {@inheritDoc}
155      */
156     @Override
157     public M getMiddle() {
158         return middle;
159     }
160 
161     /**
162      * {@inheritDoc}
163      */
164     @Override
165     public R getRight() {
166         return right;
167     }
168 }
169