As.java

  1. /*
  2.  * *********************************************************************************************************************
  3.  *
  4.  * TheseFoolishThings: Miscellaneous utilities
  5.  * http://tidalwave.it/projects/thesefoolishthings
  6.  *
  7.  * Copyright (C) 2009 - 2021 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.Nonnull;
  29. import javax.annotation.Nullable;
  30. import java.util.Collection;
  31. import java.util.Optional;
  32. import lombok.EqualsAndHashCode;
  33. import lombok.RequiredArgsConstructor;
  34. import lombok.ToString;

  35. /***********************************************************************************************************************
  36.  *
  37.  * Objects implementing this interface can provide am adapter of the required type. The adapter can be found with a
  38.  * variety of approaches that depend on the implementation. This capability can be used to implement a design based
  39.  * on the Data, Context and Interaction pattern (DCI).
  40.  *
  41.  * @author  Fabrizio Giudici
  42.  * @it.tidalwave.javadoc.stable
  43.  *
  44.  **********************************************************************************************************************/
  45. public interface As
  46.   {
  47.     /*******************************************************************************************************************
  48.      *
  49.      * @it.tidalwave.javadoc.stable
  50.      *
  51.      ******************************************************************************************************************/
  52.     public static interface NotFoundBehaviour<T>
  53.       {
  54.         @Nonnull
  55.         public T run (@Nullable final Throwable t);
  56.       }

  57.     /*******************************************************************************************************************
  58.      *
  59.      *
  60.      ******************************************************************************************************************/
  61.     public static final class Defaults
  62.       {
  63.         private Defaults()
  64.           {
  65.           }

  66.         public static <X> NotFoundBehaviour<X> throwAsException (@Nonnull final Class<X> clazz)
  67.           {
  68.             return new NotFoundBehaviour<X>()
  69.               {
  70. //                @Override
  71.                 @Nonnull
  72.                 public X run (@Nonnull final Throwable t)
  73.                   {
  74.                     throw new AsException(clazz, t);
  75.                   }
  76.               };
  77.           }
  78.       }

  79.     /*******************************************************************************************************************
  80.      *
  81.      * @since                       3.2-ALPHA-12
  82.      *
  83.      ******************************************************************************************************************/
  84.     @RequiredArgsConstructor @EqualsAndHashCode @ToString
  85.     public static final class Ref<T>
  86.       {
  87.         @Nonnull
  88.         private final Class<?> type;

  89.         @Nonnull
  90.         public Class<T> getType()
  91.           {
  92.             return (Class<T>)type;
  93.           }
  94.       }

  95.     /*******************************************************************************************************************
  96.      *
  97.      * Returns an adapter to this object of the specified type. If the implementation can find multiple compliant
  98.      * adapters, only one will be returned.
  99.      *
  100.      * @param   <T>     the static type
  101.      * @param   type    the dynamic type
  102.      * @return          the adapter
  103.      * @throws          AsException if no adapter is found
  104.      *
  105.      ******************************************************************************************************************/
  106.     @Nonnull
  107.     public <T> T as (@Nonnull Class<T> type);

  108.     /*******************************************************************************************************************
  109.      *
  110.      * Returns an adapter to this object of the specified type. If the implementation can find multiple compliant
  111.      * adapters, only one will be returned. If no adapter is found, the result provided by the given default
  112.      * behaviour will be returned.
  113.      *
  114.      * @param   <T>                 the static type
  115.      * @param   type                the dynamic type
  116.      * @param   notFoundBehaviour   the behaviour to apply when an adapter is not found
  117.      * @return                      the adapter
  118.      *
  119.      ******************************************************************************************************************/
  120.     @Nonnull
  121.     public <T> T as (@Nonnull Class<T> type, @Nonnull NotFoundBehaviour<T> notFoundBehaviour);

  122.     /*******************************************************************************************************************
  123.      *
  124.      * Returns the requested role or an empty {@link Optional}.
  125.      *
  126.      * @param   <T>                 the static type
  127.      * @param   type                the dynamic type
  128.      * @return                      the optional role
  129.      * @since                       3.2-ALPHA-3
  130.      *
  131.      ******************************************************************************************************************/
  132.     @Nonnull
  133.     default <T> Optional<T> maybeAs (@Nonnull final Class<T> type)
  134.       {
  135.         return Optional.ofNullable(as(type, throwable -> null));
  136.       }

  137.     /*******************************************************************************************************************
  138.      *
  139.      * @param   <T>     the static type
  140.      * @param   type    the dynamic type
  141.      * @return          the optional role
  142.      * @deprecated Use {@link #maybeAs(Class)}.
  143.      *
  144.      ******************************************************************************************************************/
  145.     @Nonnull @Deprecated
  146.     default <T> Optional<T> asOptional (@Nonnull final Class<T> type)
  147.       {
  148.         return maybeAs(type);
  149.       }

  150.     /*******************************************************************************************************************
  151.      *
  152.      * Searches for multiple adapters of the given type and returns them.
  153.      *
  154.      * @param   <T>     the static type
  155.      * @param   type    the dynamic type
  156.      * @return          a collection of adapters, possibly empty
  157.      *
  158.      ******************************************************************************************************************/
  159.     @Nonnull
  160.     public <T> Collection<T> asMany (@Nonnull Class<T> type);

  161.     /*******************************************************************************************************************
  162.      *
  163.      * Creates a role type reference.
  164.      *
  165.      * @param   <T>                 the static type
  166.      * @param   type                the dynamic type
  167.      * @return                      the type reference
  168.      * @since                       3.2-ALPHA-12
  169.      *
  170.      ******************************************************************************************************************/
  171.     @Nonnull
  172.     static <T> Ref<T> ref (@Nonnull final Class<?> type) // FIXME: there's no static check of the argument
  173.       {
  174.         return new Ref<>(type);
  175.       }

  176.     /*******************************************************************************************************************
  177.      *
  178.      * Returns a role for this object of the specified type. If the implementation can find multiple compliant
  179.      * roles, only one will be returned.
  180.      *
  181.      * @param   <T>                 the static type
  182.      * @param   ref                 the type reference
  183.      * @return                      the role
  184.      * @since                       3.2-ALPHA-12
  185.      *
  186.      ******************************************************************************************************************/
  187.     @Nonnull
  188.     default <T> T as (@Nonnull final Ref<T> ref)
  189.       {
  190.         return as(ref.getType());
  191.       }

  192.     /*******************************************************************************************************************
  193.      *
  194.      * Returns the requested role or an empty {@link Optional}.
  195.      *
  196.      * @param   <T>                 the static type
  197.      * @param   ref                 the type reference
  198.      * @return                      the optional role
  199.      * @since                       3.2-ALPHA-12
  200.      *
  201.      ******************************************************************************************************************/
  202.     @Nonnull
  203.     default <T> Optional<T> maybeAs (@Nonnull final Ref<T> ref)
  204.       {
  205.         return maybeAs(ref.getType());
  206.       }

  207.     /*******************************************************************************************************************
  208.      *
  209.      * Returns the requested role or an empty {@link Optional}.
  210.      *
  211.      * @param   <T>                 the static type
  212.      * @param   ref                 the type reference
  213.      * @return                      the roles
  214.      * @since                       3.2-ALPHA-12
  215.      *
  216.      ******************************************************************************************************************/
  217.     @Nonnull
  218.     default <T> Collection<T> asMany (@Nonnull final Ref<T> ref)
  219.       {
  220.         return asMany(ref.getType());
  221.       }
  222.   }