Composite.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.role;

  28. import javax.annotation.Nonnull;
  29. import it.tidalwave.util.Finder;
  30. import it.tidalwave.util.NotFoundException;

  31. /***********************************************************************************************************************
  32.  *
  33.  * The role of a composite object, that is an object which contains children. They are exposed by means of a
  34.  * {@link Finder}.
  35.  *
  36.  * @stereotype Role
  37.  *
  38.  * @author  Fabrizio Giudici
  39.  * @it.tidalwave.javadoc.stable
  40.  *
  41.  **********************************************************************************************************************/
  42. @FunctionalInterface
  43. public interface Composite<TYPE, SPECIALIZED_FINDER extends Finder<? extends TYPE>>
  44.   {
  45.     public static final Class<Composite> _Composite_ = Composite.class;

  46.     /*******************************************************************************************************************
  47.      *
  48.      * A default <code>Composite</code> with no children.
  49.      *
  50.      ******************************************************************************************************************/
  51.     public static final Composite<Object, Finder<Object>> DEFAULT = new Composite<Object, Finder<Object>>()
  52.       {
  53.         @Override @Nonnull
  54.         public Finder<Object> findChildren()
  55.           {
  56.             return Finder.empty();
  57.           }
  58.       };

  59.     /*******************************************************************************************************************
  60.      *
  61.      * Returns the children of this object.
  62.      *
  63.      * @return  the children
  64.      *
  65.      ******************************************************************************************************************/
  66.     @Nonnull
  67.     public SPECIALIZED_FINDER findChildren();

  68.     /*******************************************************************************************************************
  69.      *
  70.      *
  71.      ******************************************************************************************************************/
  72.     @SuppressWarnings("EmptyMethod")
  73.     public static interface Visitor<T, R>
  74.       {
  75.         /***************************************************************************************************************
  76.          *
  77.          * Visits an object. This method is called before visiting children (pre-order).
  78.          *
  79.          * @param  object  the visited object
  80.          *
  81.          **************************************************************************************************************/
  82.         public void preVisit (@Nonnull T object);

  83.         /***************************************************************************************************************
  84.          *
  85.          * Visits an object. This method is actually called just after {@link #preVisit(Object)}, it makes sense to
  86.          * implement it when you don't need to distinguish between pre-order and post-order traversal.
  87.          *
  88.          * @param  object  the visited object
  89.          *
  90.          **************************************************************************************************************/
  91.         public void visit (@Nonnull T object);

  92.         /***************************************************************************************************************
  93.          *
  94.          * Visits an object. This method is called after visiting children (post-order).
  95.          *
  96.          * @param  object  the visited object
  97.          *
  98.          **************************************************************************************************************/
  99.         public void postVisit (@Nonnull T object);

  100.         /***************************************************************************************************************
  101.          *
  102.          * Returns the value of this visitor.
  103.          *
  104.          * @return                     the value
  105.          * @throws  NotFoundException  when no value has been found
  106.          *
  107.          **************************************************************************************************************/
  108.         @Nonnull
  109.         public R getValue()
  110.           throws NotFoundException;
  111.       }

  112.     /*******************************************************************************************************************
  113.      *
  114.      * A support class for {@link Visitor} which provides default empty methods.
  115.      *
  116.      ******************************************************************************************************************/
  117.     public static class VisitorSupport<T, R> implements Visitor<T, R>
  118.       {
  119.         /** {@inheritDoc} */
  120.         @Override
  121.         public void preVisit (@Nonnull final T object)
  122.           {
  123.           }

  124.         /** {@inheritDoc} */
  125.         @Override
  126.         public void visit (@Nonnull final T object)
  127.           {
  128.           }

  129.         /** {@inheritDoc} */
  130.         @Override
  131.         public void postVisit (@Nonnull final T object)
  132.           {
  133.           }

  134.         /** {@inheritDoc} */
  135.         @Override @Nonnull
  136.         public R getValue()
  137.           throws NotFoundException
  138.           {
  139.             throw new NotFoundException("Must be implemented by subclasses");
  140.           }
  141.       }
  142.   }