Parameters.java

  1. /*
  2.  * *********************************************************************************************************************
  3.  *
  4.  * TheseFoolishThings: Miscellaneous utilities
  5.  * http://tidalwave.it/projects/thesefoolishthings
  6.  *
  7.  * Copyright (C) 2009 - 2023 by Tidalwave s.a.s. (http://tidalwave.it)
  8.  *
  9.  * *********************************************************************************************************************
  10.  *
  11.  * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
  12.  * the License. You may obtain a copy of the License at
  13.  *
  14.  *     http://www.apache.org/licenses/LICENSE-2.0
  15.  *
  16.  * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
  17.  * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the
  18.  * specific language governing permissions and limitations under the License.
  19.  *
  20.  * *********************************************************************************************************************
  21.  *
  22.  * git clone https://bitbucket.org/tidalwave/thesefoolishthings-src
  23.  * git clone https://github.com/tidalwave-it/thesefoolishthings-src
  24.  *
  25.  * *********************************************************************************************************************
  26.  */
  27. package it.tidalwave.util;

  28. import javax.annotation.CheckForNull;
  29. import javax.annotation.Nonnull;
  30. import java.util.ArrayList;
  31. import java.util.Collection;
  32. import java.util.List;
  33. import lombok.AccessLevel;
  34. import lombok.RequiredArgsConstructor;

  35. /***********************************************************************************************************************
  36.  *
  37.  * This class provides a few static utility methods to manipulate arguments to methods.
  38.  *
  39.  * @author  Fabrizio Giudici
  40.  * @it.tidalwave.javadoc.stable
  41.  *
  42.  **********************************************************************************************************************/
  43. @RequiredArgsConstructor(access = AccessLevel.PRIVATE)
  44. public final class Parameters
  45.   {
  46.     /*******************************************************************************************************************
  47.      *
  48.      * A convenience method for transforming a varargs of objects to a {@link Collection}. It supports concatenating
  49.      * collections: that is, each varargs item that is a {@link Collection} is flattened.
  50.      *
  51.      * @param   objects                   the objects as varargs
  52.      * @return                            the objects as collection
  53.      * @since                             3.2-ALPHA-3
  54.      * @it.tidalwave.javadoc.experimental
  55.      *
  56.      ******************************************************************************************************************/
  57.     @Nonnull
  58.     public static Collection<Object> r (@Nonnull final Object... objects)
  59.       {
  60.         // Don't use streams() for performance reasons.
  61.         final List<Object> result = new ArrayList<>();

  62.         for (final var object : objects)
  63.           {
  64.             if (!(object instanceof Collection))
  65.               {
  66.                 result.add(object);
  67.               }
  68.             else
  69.               {
  70.                 result.addAll((Collection<?>)object);
  71.               }
  72.           }

  73.         return result;
  74.       }

  75.     /*******************************************************************************************************************
  76.      *
  77.      * Extracts a singled-value parameter of the given type from an array. If the parameter is not found, the default
  78.      * value is returned. If more than a single parameter is found, an {@link IllegalArgumentException} is thrown.
  79.      *
  80.      * @param   <T>                       the static type of the parameter
  81.      * @param   parameterClass            the dynamic type of the parameter
  82.      * @param   defaultOption             the default value of the parameter
  83.      * @param   parameters                the array of parameters
  84.      * @return                            the value of the parameter
  85.      * @throws IllegalArgumentException   if more than a single value is found
  86.      *
  87.      ******************************************************************************************************************/
  88.     @CheckForNull
  89.     public static <T> T find (@Nonnull final Class<? extends T> parameterClass,
  90.                               @CheckForNull final T defaultOption,
  91.                               @Nonnull final Object... parameters)
  92.             throws IllegalArgumentException
  93.       {
  94.         // Don't use streams() for performance reasons.
  95.         final var c = find(parameterClass, parameters);

  96.         if (c.size() > 1)
  97.           {
  98.             throw new IllegalArgumentException(String.format("Multiple values for %s have been specified",
  99.                                                              parameterClass.getSimpleName()));
  100.           }

  101.         return c.isEmpty() ? defaultOption : c.iterator().next();
  102.       }

  103.     /*******************************************************************************************************************
  104.      *
  105.      * Extracts multiple-value parameters of the given type from an array. If the parameter is not found, an empty
  106.      * collection is returned.
  107.      *
  108.      * @param   <T>                       the static type of the parameter
  109.      * @param   parameterClass            the class of the parameter to retrieve
  110.      * @param   parameters                the array of parameters
  111.      * @return                            the value of the parameter
  112.      *
  113.      ******************************************************************************************************************/
  114.     @Nonnull
  115.     public static <T> Collection<T> find (@Nonnull final Class<? extends T> parameterClass,
  116.                                           @Nonnull final Object... parameters)
  117.       {
  118.         // Don't use streams() for performance reasons.
  119.         final Collection<T> result = new ArrayList<>();

  120.         for (final var parameter : parameters)
  121.           {
  122.             if (parameterClass.isAssignableFrom(parameter.getClass()))
  123.               {
  124.                 result.add(parameterClass.cast(parameter));
  125.               }
  126.           }

  127.         return result;
  128.       }

  129.     /*******************************************************************************************************************
  130.      *
  131.      * <b>This method is for internal implementation only.</b> Ensures that a given object is neither an array nor a
  132.      * collection.
  133.      *
  134.      * @param   object    the object to check
  135.      * @param   message   the message to put in the exception
  136.      * @return            the object itself for calling this method as a function
  137.      *
  138.      ******************************************************************************************************************/
  139.     @Nonnull
  140.     public static Object mustNotBeArrayOrCollection (@Nonnull final Object object, @Nonnull final String message)
  141.       {
  142.         if (object instanceof Collection)
  143.           {
  144.             throw new IllegalArgumentException(message + " can't be a Collection");
  145.           }

  146.         if (object.getClass().isArray())
  147.           {
  148.             throw new IllegalArgumentException(message + " can't be an array");
  149.           }

  150.         return object;
  151.       }
  152.   }