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