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