001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.commons.lang3.tuple; 018 019import java.util.Objects; 020 021/** 022 * An immutable triple consisting of three {@link Object} elements. 023 * 024 * <p>Although the implementation is immutable, there is no restriction on the objects 025 * that may be stored. If mutable objects are stored in the triple, then the triple 026 * itself effectively becomes mutable. The class is also {@code final}, so a subclass 027 * can not add undesirable behavior.</p> 028 * 029 * <p>#ThreadSafe# if all three objects are thread-safe</p> 030 * 031 * @param <L> the left element type 032 * @param <M> the middle element type 033 * @param <R> the right element type 034 * 035 * @since 3.2 036 */ 037public class ImmutableTriple<L, M, R> extends Triple<L, M, R> { 038 039 /** 040 * An empty array. 041 * <p> 042 * Consider using {@link #emptyArray()} to avoid generics warnings. 043 * </p> 044 * 045 * @since 3.10. 046 */ 047 public static final ImmutableTriple<?, ?, ?>[] EMPTY_ARRAY = {}; 048 049 /** 050 * An immutable triple of nulls. 051 */ 052 // This is not defined with generics to avoid warnings in call sites. 053 @SuppressWarnings("rawtypes") 054 private static final ImmutableTriple NULL = new ImmutableTriple<>(null, null, null); 055 056 /** Serialization version */ 057 private static final long serialVersionUID = 1L; 058 059 /** 060 * Returns the empty array singleton that can be assigned without compiler warning. 061 * 062 * @param <L> the left element type 063 * @param <M> the middle element type 064 * @param <R> the right element type 065 * @return the empty array singleton that can be assigned without compiler warning. 066 * 067 * @since 3.10. 068 */ 069 @SuppressWarnings("unchecked") 070 public static <L, M, R> ImmutableTriple<L, M, R>[] emptyArray() { 071 return (ImmutableTriple<L, M, R>[]) EMPTY_ARRAY; 072 } 073 074 /** 075 * Returns an immutable triple of nulls. 076 * 077 * @param <L> the left element of this triple. Value is {@code null}. 078 * @param <M> the middle element of this triple. Value is {@code null}. 079 * @param <R> the right element of this triple. Value is {@code null}. 080 * @return an immutable triple of nulls. 081 * @since 3.6 082 */ 083 @SuppressWarnings("unchecked") 084 public static <L, M, R> ImmutableTriple<L, M, R> nullTriple() { 085 return NULL; 086 } 087 088 /** 089 * Obtains an immutable triple of three objects inferring the generic types. 090 * 091 * <p>This factory allows the triple to be created using inference to 092 * obtain the generic types.</p> 093 * 094 * @param <L> the left element type 095 * @param <M> the middle element type 096 * @param <R> the right element type 097 * @param left the left element, may be null 098 * @param middle the middle element, may be null 099 * @param right the right element, may be null 100 * @return a triple formed from the three parameters, not null 101 */ 102 public static <L, M, R> ImmutableTriple<L, M, R> of(final L left, final M middle, final R right) { 103 return left != null | middle != null || right != null ? new ImmutableTriple<>(left, middle, right) : nullTriple(); 104 } 105 106 /** 107 * Obtains an immutable triple of three non-null objects inferring the generic types. 108 * 109 * <p>This factory allows the triple to be created using inference to 110 * obtain the generic types.</p> 111 * 112 * @param <L> the left element type 113 * @param <M> the middle element type 114 * @param <R> the right element type 115 * @param left the left element, may not be null 116 * @param middle the middle element, may not be null 117 * @param right the right element, may not be null 118 * @return a triple formed from the three parameters, not null 119 * @throws NullPointerException if any input is null 120 * @since 3.13.0 121 */ 122 public static <L, M, R> ImmutableTriple<L, M, R> ofNonNull(final L left, final M middle, final R right) { 123 return of(Objects.requireNonNull(left, "left"), Objects.requireNonNull(middle, "middle"), Objects.requireNonNull(right, "right")); 124 } 125 126 /** Left object */ 127 public final L left; 128 /** Middle object */ 129 public final M middle; 130 131 /** Right object */ 132 public final R right; 133 134 /** 135 * Create a new triple instance. 136 * 137 * @param left the left value, may be null 138 * @param middle the middle value, may be null 139 * @param right the right value, may be null 140 */ 141 public ImmutableTriple(final L left, final M middle, final R right) { 142 this.left = left; 143 this.middle = middle; 144 this.right = right; 145 } 146 147 /** 148 * {@inheritDoc} 149 */ 150 @Override 151 public L getLeft() { 152 return left; 153 } 154 155 /** 156 * {@inheritDoc} 157 */ 158 @Override 159 public M getMiddle() { 160 return middle; 161 } 162 163 /** 164 * {@inheritDoc} 165 */ 166 @Override 167 public R getRight() { 168 return right; 169 } 170} 171