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 * @param <L> the left element type.
89 * @param <M> the middle element type.
90 * @param <R> the right element type.
91 * @param left the left element, may be null.
92 * @param middle the middle element, may be null.
93 * @param right the right element, may be null.
94 * @return an immutable triple formed from the three parameters, not null.
95 */
96 public static <L, M, R> ImmutableTriple<L, M, R> of(final L left, final M middle, final R right) {
97 return left != null | middle != null || right != null ? new ImmutableTriple<>(left, middle, right) : nullTriple();
98 }
99
100 /**
101 * Creates an immutable triple of three non-null objects inferring the generic types.
102 *
103 * @param <L> the left element type.
104 * @param <M> the middle element type.
105 * @param <R> the right element type.
106 * @param left the left element, may not be null.
107 * @param middle the middle element, may not be null.
108 * @param right the right element, may not be null.
109 * @return an immutable triple formed from the three parameters, not null.
110 * @throws NullPointerException if any input is null.
111 * @since 3.13.0
112 */
113 public static <L, M, R> ImmutableTriple<L, M, R> ofNonNull(final L left, final M middle, final R right) {
114 return of(Objects.requireNonNull(left, "left"), Objects.requireNonNull(middle, "middle"), Objects.requireNonNull(right, "right"));
115 }
116
117 /** Left object. */
118
119 public final L left;
120 /** Middle object. */
121 public final M middle;
122
123 /** Right object. */
124 public final R right;
125
126 /**
127 * Constructs a new triple instance.
128 *
129 * @param left the left value, may be null.
130 * @param middle the middle value, may be null.
131 * @param right the right value, may be null.
132 */
133 public ImmutableTriple(final L left, final M middle, final R right) {
134 this.left = left;
135 this.middle = middle;
136 this.right = right;
137 }
138
139 /**
140 * {@inheritDoc}
141 */
142 @Override
143 public L getLeft() {
144 return left;
145 }
146
147 /**
148 * {@inheritDoc}
149 */
150 @Override
151 public M getMiddle() {
152 return middle;
153 }
154
155 /**
156 * {@inheritDoc}
157 */
158 @Override
159 public R getRight() {
160 return right;
161 }
162 }
163