As.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.Nonnull;
  29. import javax.annotation.Nullable;
  30. import java.util.Collection;
  31. import java.util.Optional;
  32. import it.tidalwave.util.impl.DefaultAs;
  33. import lombok.EqualsAndHashCode;
  34. import lombok.RequiredArgsConstructor;
  35. import lombok.ToString;

  36. /***********************************************************************************************************************
  37.  *
  38.  * Objects implementing this interface can provide am adapter of the required type. The adapter can be found with a
  39.  * variety of approaches that depend on the implementation. This capability can be used to implement a design based
  40.  * on the Data, Context and Interaction pattern (DCI). For further details, please look at the
  41.  * <a href="http://tidalwave.it/projects/thesefoolishthings">project website</a>, where a tutorial is available.
  42.  *
  43.  * @author  Fabrizio Giudici
  44.  * @it.tidalwave.javadoc.stable
  45.  *
  46.  **********************************************************************************************************************/
  47. public interface As
  48.   {
  49.     /*******************************************************************************************************************
  50.      *
  51.      * @it.tidalwave.javadoc.stable
  52.      *
  53.      ******************************************************************************************************************/
  54.     @Deprecated
  55.     public static interface NotFoundBehaviour<T>
  56.       {
  57.         @Nonnull
  58.         public T run (@Nullable final Throwable t);
  59.       }

  60.     /*******************************************************************************************************************
  61.      *
  62.      *
  63.      ******************************************************************************************************************/
  64.     @Deprecated
  65.     public static final class Defaults
  66.       {
  67.         private Defaults()
  68.           {
  69.           }

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

  83.     /*******************************************************************************************************************
  84.      *
  85.      * A type reference for roles that can be used in place of a class literal, especially when roles with generics are
  86.      * used. Example of usage:
  87.      * <pre>
  88.      *
  89.      *     interface DataRetriever&lt;T&gt;
  90.      *       {
  91.      *         public List&lt;T&gt; retrieve();
  92.      *       }
  93.      *
  94.      *     class CodeSample
  95.      *       {
  96.      *         private static final As.Type&lt;DataRetriever&lt;String&gt;&gt; _StringRetriever_ = As.type(DataRetriever.class);
  97.      *
  98.      *         public void method (As object)
  99.      *           {
  100.      *             List&lt;String&gt; f3 = object.as(_StringRetriever_).retrieve();
  101.      *           }
  102.      *       }
  103.      * </pre>
  104.      *
  105.      * @since     3.2-ALPHA-12
  106.      *
  107.      ******************************************************************************************************************/
  108.     @RequiredArgsConstructor @EqualsAndHashCode @ToString
  109.     public static final class Type<T>
  110.       {
  111.         @Nonnull
  112.         private final Class<?> type;

  113.         @Nonnull
  114.         public Class<T> getType()
  115.           {
  116.             return (Class<T>)type;
  117.           }
  118.       }

  119.     /*******************************************************************************************************************
  120.      *
  121.      * Creates an {@code As} implementation delegate for the given object (or returns the object itself if it is the
  122.      * default implementation of {@code As}).
  123.      *
  124.      * @param     object         the object
  125.      * @return                   the implementation
  126.      * @since     3.2-ALPHA-12
  127.      *
  128.      ******************************************************************************************************************/
  129.     @Nonnull
  130.     public static As forObject (@Nonnull final Object object)
  131.       {
  132.         return (object instanceof DefaultAs) ? (As)object : new DefaultAs(object);
  133.       }

  134.     /*******************************************************************************************************************
  135.      *
  136.      * Creates an {@code As} implementation delegate for the given object. It accepts a single pre-instantiated role,
  137.      * or a {@link RoleFactory} that will be invoked to create additional roles.
  138.      *
  139.      * @param     object         the object
  140.      * @param     role           the role or {@link it.tidalwave.util.RoleFactory}
  141.      * @return                   the implementation
  142.      * @since     3.2-ALPHA-13
  143.      *
  144.      ******************************************************************************************************************/
  145.     @Nonnull
  146.     public static As forObject (@Nonnull final Object object, @Nonnull final Object role)
  147.       {
  148.         return new DefaultAs(object, role);
  149.       }

  150.     /*******************************************************************************************************************
  151.      *
  152.      * Creates an {@code As} implementation delegate for the given object. It accepts a collection of pre-instantiated
  153.      * roles, or instances of {@link RoleFactory} that will be invoked to create additional roles.
  154.      *
  155.      * @param     object         the object
  156.      * @param     roles          roles or {@link it.tidalwave.util.RoleFactory} instances
  157.      * @return                   the implementation
  158.      * @since     3.2-ALPHA-13
  159.      *
  160.      ******************************************************************************************************************/
  161.     @Nonnull
  162.     public static As forObject (@Nonnull final Object object, @Nonnull final Collection<Object> roles)
  163.       {
  164.         return new DefaultAs(object, roles);
  165.       }

  166.     /*******************************************************************************************************************
  167.      *
  168.      * Returns an adapter to this object of the specified type. If the implementation can find multiple compliant
  169.      * adapters, only one will be returned.
  170.      *
  171.      * @param   <T>     the static type
  172.      * @param   type    the dynamic type
  173.      * @return          the adapter
  174.      * @throws          AsException if no adapter is found
  175.      *
  176.      ******************************************************************************************************************/
  177.     @Nonnull
  178.     public default <T> T as (@Nonnull final Class<T> type)
  179.       {
  180.         return maybeAs(type).orElseThrow(() -> new AsException(type));
  181.       }

  182.     /*******************************************************************************************************************
  183.      *
  184.      * Returns an adapter to this object of the specified type. If the implementation can find multiple compliant
  185.      * adapters, only one will be returned. If no adapter is found, the result provided by the given default
  186.      * behaviour will be returned.
  187.      *
  188.      * @param   <T>                 the static type
  189.      * @param   type                the dynamic type
  190.      * @param   notFoundBehaviour   the behaviour to apply when an adapter is not found
  191.      * @return                      the adapter
  192.      * @deprecated
  193.      *
  194.      ******************************************************************************************************************/
  195.     @Nonnull @Deprecated
  196.     public default <T> T as (@Nonnull final Class<T> type, @Nonnull final NotFoundBehaviour<T> notFoundBehaviour)
  197.       {
  198.         return maybeAs(type).orElseGet(() -> notFoundBehaviour.run(new AsException(type)));
  199.       }

  200.     /*******************************************************************************************************************
  201.      *
  202.      * Returns the requested role or an empty {@link Optional}.
  203.      *
  204.      * @param   <T>                 the static type
  205.      * @param   type                the dynamic type
  206.      * @return                      the optional role
  207.      * @since                       3.2-ALPHA-3
  208.      *
  209.      ******************************************************************************************************************/
  210.     @Nonnull
  211.     public <T> Optional<T> maybeAs (@Nonnull Class<T> type);

  212.     /*******************************************************************************************************************
  213.      *
  214.      * Searches for multiple adapters of the given type and returns them.
  215.      *
  216.      * @param   <T>     the static type
  217.      * @param   type    the dynamic type
  218.      * @return          a collection of adapters, possibly empty
  219.      *
  220.      ******************************************************************************************************************/
  221.     @Nonnull
  222.     public <T> Collection<T> asMany (@Nonnull Class<T> type);

  223.     /*******************************************************************************************************************
  224.      *
  225.      * Creates a role type reference.
  226.      *
  227.      * @param   <T>                 the static type
  228.      * @param   type                the dynamic type
  229.      * @return                      the type reference
  230.      * @since                       3.2-ALPHA-12
  231.      *
  232.      ******************************************************************************************************************/
  233.     @Nonnull
  234.     public static <T> Type<T> type (@Nonnull final Class<?> type) // FIXME: there's no static check of the argument
  235.       {
  236.         return new Type<>(type);
  237.       }

  238.     /*******************************************************************************************************************
  239.      *
  240.      * Returns a role for this object of the specified type. If the implementation can find multiple compliant
  241.      * roles, only one will be returned.
  242.      *
  243.      * @param   <T>                 the static type
  244.      * @param   type                the type reference
  245.      * @return                      the role
  246.      * @since                       3.2-ALPHA-12
  247.      *
  248.      ******************************************************************************************************************/
  249.     @Nonnull
  250.     public default <T> T as (@Nonnull final Type<T> type)
  251.       {
  252.         return as(type.getType());
  253.       }

  254.     /*******************************************************************************************************************
  255.      *
  256.      * Returns the requested role or an empty {@link Optional}.
  257.      *
  258.      * @param   <T>                 the static type
  259.      * @param   type                the type reference
  260.      * @return                      the optional role
  261.      * @since                       3.2-ALPHA-12
  262.      *
  263.      ******************************************************************************************************************/
  264.     @Nonnull
  265.     public default <T> Optional<T> maybeAs (@Nonnull final Type<T> type)
  266.       {
  267.         return maybeAs(type.getType());
  268.       }

  269.     /*******************************************************************************************************************
  270.      *
  271.      * Returns the requested role or an empty {@link Optional}.
  272.      *
  273.      * @param   <T>                 the static type
  274.      * @param   type                the type reference
  275.      * @return                      the roles
  276.      * @since                       3.2-ALPHA-12
  277.      *
  278.      ******************************************************************************************************************/
  279.     @Nonnull
  280.     public default <T> Collection<T> asMany (@Nonnull final Type<T> type)
  281.       {
  282.         return asMany(type.getType());
  283.       }
  284.   }