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 * https://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.</p> 027 * 028 * <p>#ThreadSafe# if all three objects are thread-safe.</p> 029 * 030 * @param <L> the left element type. 031 * @param <M> the middle element type. 032 * @param <R> the right element type. 033 * @since 3.2 034 */ 035public class ImmutableTriple<L, M, R> extends Triple<L, M, R> { 036 037 /** 038 * An empty array. 039 * <p> 040 * Consider using {@link #emptyArray()} to avoid generics warnings. 041 * </p> 042 * 043 * @since 3.10 044 */ 045 public static final ImmutableTriple<?, ?, ?>[] EMPTY_ARRAY = {}; 046 047 /** 048 * An immutable triple of nulls. 049 */ 050 // This is not defined with generics to avoid warnings in call sites. 051 @SuppressWarnings("rawtypes") 052 private static final ImmutableTriple NULL = new ImmutableTriple<>(null, null, null); 053 054 /** Serialization version. */ 055 private static final long serialVersionUID = 1L; 056 057 /** 058 * Gets the empty array singleton that can be assigned without compiler warning. 059 * 060 * @param <L> the left element type. 061 * @param <M> the middle element type. 062 * @param <R> the right element type. 063 * @return the empty array singleton that can be assigned without compiler warning. 064 * @since 3.10 065 */ 066 @SuppressWarnings("unchecked") 067 public static <L, M, R> ImmutableTriple<L, M, R>[] emptyArray() { 068 return (ImmutableTriple<L, M, R>[]) EMPTY_ARRAY; 069 } 070 071 /** 072 * Gets the immutable triple of nulls singleton. 073 * 074 * @param <L> the left element of this triple. Value is {@code null}. 075 * @param <M> the middle element of this triple. Value is {@code null}. 076 * @param <R> the right element of this triple. Value is {@code null}. 077 * @return an immutable triple of nulls. 078 * @since 3.6 079 */ 080 @SuppressWarnings("unchecked") 081 public static <L, M, R> ImmutableTriple<L, M, R> nullTriple() { 082 return NULL; 083 } 084 085 /** 086 * Creates an immutable triple of three objects inferring the generic types. 087 * 088 * <p>This factory allows the triple to be created using inference to 089 * obtain the generic types.</p> 090 * 091 * @param <L> the left element type. 092 * @param <M> the middle element type. 093 * @param <R> the right element type. 094 * @param left the left element, may be null. 095 * @param middle the middle element, may be null. 096 * @param right the right element, may be null. 097 * @return a triple formed from the three parameters, not null. 098 */ 099 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