ImmutablePair.java

  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. import java.util.Map;
  19. import java.util.Objects;

  20. /**
  21.  * An immutable pair consisting of two {@link Object} elements.
  22.  *
  23.  * <p>Although the implementation is immutable, there is no restriction on the objects
  24.  * that may be stored. If mutable objects are stored in the pair, then the pair
  25.  * itself effectively becomes mutable.</p>
  26.  *
  27.  * <p>#ThreadSafe# if both paired objects are thread-safe</p>
  28.  *
  29.  * @param <L> the left element type
  30.  * @param <R> the right element type
  31.  *
  32.  * @since 3.0
  33.  */
  34. public class ImmutablePair<L, R> extends Pair<L, R> {

  35.     /**
  36.      * An empty array.
  37.      * <p>
  38.      * Consider using {@link #emptyArray()} to avoid generics warnings.
  39.      * </p>
  40.      *
  41.      * @since 3.10.
  42.      */
  43.     public static final ImmutablePair<?, ?>[] EMPTY_ARRAY = {};

  44.     /**
  45.      * An immutable pair of nulls.
  46.      */
  47.     // This is not defined with generics to avoid warnings in call sites.
  48.     @SuppressWarnings("rawtypes")
  49.     private static final ImmutablePair NULL = new ImmutablePair<>(null, null);

  50.     /** Serialization version */
  51.     private static final long serialVersionUID = 4954918890077093841L;

  52.     /**
  53.      * Returns the empty array singleton that can be assigned without compiler warning.
  54.      *
  55.      * @param <L> the left element type
  56.      * @param <R> the right element type
  57.      * @return the empty array singleton that can be assigned without compiler warning.
  58.      *
  59.      * @since 3.10.
  60.      */
  61.     @SuppressWarnings("unchecked")
  62.     public static <L, R> ImmutablePair<L, R>[] emptyArray() {
  63.         return (ImmutablePair<L, R>[]) EMPTY_ARRAY;
  64.     }

  65.     /**
  66.      * Creates an immutable pair of two objects inferring the generic types.
  67.      *
  68.      * <p>This factory allows the pair to be created using inference to
  69.      * obtain the generic types.</p>
  70.      *
  71.      * @param <L> the left element type
  72.      * @param <R> the right element type
  73.      * @param left  the left element, may be null
  74.      * @return a pair formed from the two parameters, not null
  75.      * @since 3.11
  76.      */
  77.     public static <L, R> Pair<L, R> left(final L left) {
  78.         return of(left, null);
  79.     }

  80.     /**
  81.      * Returns an immutable pair of nulls.
  82.      *
  83.      * @param <L> the left element of this pair. Value is {@code null}.
  84.      * @param <R> the right element of this pair. Value is {@code null}.
  85.      * @return an immutable pair of nulls.
  86.      * @since 3.6
  87.      */
  88.     @SuppressWarnings("unchecked")
  89.     public static <L, R> ImmutablePair<L, R> nullPair() {
  90.         return NULL;
  91.     }

  92.     /**
  93.      * Creates an immutable pair of two objects inferring the generic types.
  94.      *
  95.      * <p>This factory allows the pair to be created using inference to
  96.      * obtain the generic types.</p>
  97.      *
  98.      * @param <L> the left element type
  99.      * @param <R> the right element type
  100.      * @param left  the left element, may be null
  101.      * @param right  the right element, may be null
  102.      * @return a pair formed from the two parameters, not null
  103.      */
  104.     public static <L, R> ImmutablePair<L, R> of(final L left, final R right) {
  105.         return left != null || right != null ? new ImmutablePair<>(left, right) : nullPair();
  106.     }

  107.     /**
  108.      * Creates an immutable pair from a map entry.
  109.      *
  110.      * <p>This factory allows the pair to be created using inference to
  111.      * obtain the generic types.</p>
  112.      *
  113.      * @param <L> the left element type
  114.      * @param <R> the right element type
  115.      * @param pair the existing map entry.
  116.      * @return a pair formed from the map entry
  117.      * @since 3.10
  118.      */
  119.     public static <L, R> ImmutablePair<L, R> of(final Map.Entry<L, R> pair) {
  120.         return pair != null ? new ImmutablePair<>(pair.getKey(), pair.getValue()) : nullPair();
  121.     }

  122.     /**
  123.      * Creates an immutable pair of two non-null objects inferring the generic types.
  124.      *
  125.      * <p>This factory allows the pair to be created using inference to
  126.      * obtain the generic types.</p>
  127.      *
  128.      * @param <L> the left element type
  129.      * @param <R> the right element type
  130.      * @param left  the left element, may not be null
  131.      * @param right  the right element, may not  be null
  132.      * @return a pair formed from the two parameters, not null
  133.      * @throws NullPointerException if any input is null
  134.      * @since 3.13.0
  135.      */
  136.     public static <L, R> ImmutablePair<L, R> ofNonNull(final L left, final R right) {
  137.         return of(Objects.requireNonNull(left, "left"), Objects.requireNonNull(right, "right"));
  138.     }

  139.     /**
  140.      * Creates an immutable pair of two objects inferring the generic types.
  141.      *
  142.      * <p>This factory allows the pair to be created using inference to
  143.      * obtain the generic types.</p>
  144.      *
  145.      * @param <L> the left element type
  146.      * @param <R> the right element type
  147.      * @param right  the right element, may be null
  148.      * @return a pair formed from the two parameters, not null
  149.      * @since 3.11
  150.      */
  151.     public static <L, R> Pair<L, R> right(final R right) {
  152.         return of(null, right);
  153.     }

  154.     /** Left object */
  155.     public final L left;

  156.     /** Right object */
  157.     public final R right;

  158.     /**
  159.      * Create a new pair instance.
  160.      *
  161.      * @param left  the left value, may be null
  162.      * @param right  the right value, may be null
  163.      */
  164.     public ImmutablePair(final L left, final R right) {
  165.         this.left = left;
  166.         this.right = right;
  167.     }

  168.     /**
  169.      * {@inheritDoc}
  170.      */
  171.     @Override
  172.     public L getLeft() {
  173.         return left;
  174.     }

  175.     /**
  176.      * {@inheritDoc}
  177.      */
  178.     @Override
  179.     public R getRight() {
  180.         return right;
  181.     }

  182.     /**
  183.      * Throws {@link UnsupportedOperationException}.
  184.      *
  185.      * <p>This pair is immutable, so this operation is not supported.</p>
  186.      *
  187.      * @param value  the value to set
  188.      * @return never
  189.      * @throws UnsupportedOperationException as this operation is not supported
  190.      */
  191.     @Override
  192.     public R setValue(final R value) {
  193.         throw new UnsupportedOperationException();
  194.     }

  195. }