Parameters.java

  1. /*
  2.  * *************************************************************************************************************************************************************
  3.  *
  4.  * TheseFoolishThings: Miscellaneous utilities
  5.  * http://tidalwave.it/projects/thesefoolishthings
  6.  *
  7.  * Copyright (C) 2009 - 2024 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 the License.
  12.  * 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 an "AS IS" BASIS, WITHOUT WARRANTIES OR
  17.  * CONDITIONS OF ANY KIND, either express or implied.  See the License for the specific language governing permissions and limitations under the License.
  18.  *
  19.  * *************************************************************************************************************************************************************
  20.  *
  21.  * git clone https://bitbucket.org/tidalwave/thesefoolishthings-src
  22.  * git clone https://github.com/tidalwave-it/thesefoolishthings-src
  23.  *
  24.  * *************************************************************************************************************************************************************
  25.  */
  26. package it.tidalwave.util;

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

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

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

  70.         return result;
  71.       }

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

  91.         if (c.size() > 1)
  92.           {
  93.             throw new IllegalArgumentException(String.format("Multiple values for %s have been specified",
  94.                                                              parameterClass.getSimpleName()));
  95.           }

  96.         return c.isEmpty() ? defaultOption : c.iterator().next();
  97.       }

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

  113.         for (final var parameter : parameters)
  114.           {
  115.             if (parameterClass.isAssignableFrom(parameter.getClass()))
  116.               {
  117.                 result.add(parameterClass.cast(parameter));
  118.               }
  119.           }

  120.         return result;
  121.       }

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

  137.         if (object.getClass().isArray())
  138.           {
  139.             throw new IllegalArgumentException(message + " can't be an array");
  140.           }

  141.         return object;
  142.       }
  143.   }