PresentationModel.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.ui;

  28. import javax.annotation.Nonnull;
  29. import java.beans.PropertyChangeListener;
  30. import java.util.Collection;
  31. import java.util.Collections;
  32. import it.tidalwave.util.As;
  33. import it.tidalwave.util.NamedCallback;
  34. import it.tidalwave.util.Parameters;
  35. import it.tidalwave.role.SimpleComposite;
  36. import it.tidalwave.role.ui.impl.DefaultPresentationModel;
  37. import static it.tidalwave.util.Parameters.r;
  38. import static it.tidalwave.role.ui.Presentable._Presentable_;

  39. /***********************************************************************************************************************
  40.  *
  41.  * TODO: As the NetBeans Node, it should allow children, have event listeners for children added/removed/changed.
  42.  * This class so becomes the true M in MVC.
  43.  *
  44.  * @stereotype Role
  45.  *
  46.  * @author  Fabrizio Giudici
  47.  *
  48.  **********************************************************************************************************************/
  49. public interface PresentationModel extends As
  50.   {
  51.     public static final Class<PresentationModel> PresentationModel = PresentationModel.class;

  52.     public static final As.Type<SimpleComposite<PresentationModel>> _SimpleCompositeOfPresentationModel_ =
  53.             As.type(SimpleComposite.class);

  54.     public static final String PROPERTY_CHILDREN = "children";

  55.     /** This is an undocumented feature. If you add a {@link NamedCallback} with this name as a role in this object, it
  56.      * will be called back when {@link #dispose()} is called. */
  57.     public static final String CALLBACK_DISPOSE = "dispose";

  58.     /*******************************************************************************************************************
  59.      *
  60.      * Disposes this object.
  61.      *
  62.      ******************************************************************************************************************/
  63.     public void dispose();

  64.     /*******************************************************************************************************************
  65.      *
  66.      * Adds a {@link PropertyChangeListener}.
  67.      *
  68.      * @param listener    the listener
  69.      *
  70.      ******************************************************************************************************************/
  71.     public void addPropertyChangeListener (@Nonnull PropertyChangeListener listener);

  72.     /*******************************************************************************************************************
  73.      *
  74.      * Adds a {@link PropertyChangeListener} for the given property.
  75.      *
  76.      * @param propertyName  the name of the property
  77.      * @param listener      the listener
  78.      *
  79.      ******************************************************************************************************************/
  80.     public void addPropertyChangeListener (@Nonnull String propertyName, @Nonnull PropertyChangeListener listener);

  81.     /*******************************************************************************************************************
  82.      *
  83.      * Removes a {@link PropertyChangeListener}.
  84.      *
  85.      * @param listener    the listener
  86.      *
  87.      ******************************************************************************************************************/
  88.     public void removePropertyChangeListener (@Nonnull PropertyChangeListener listener);

  89.     /*******************************************************************************************************************
  90.      *
  91.      * Removes a {@link PropertyChangeListener} for the given property.
  92.      *
  93.      * @param propertyName  the name of the property
  94.      * @param listener      the listener
  95.      *
  96.      ******************************************************************************************************************/
  97.     public void removePropertyChangeListener (@Nonnull String propertyName, @Nonnull PropertyChangeListener listener);

  98.     /*******************************************************************************************************************
  99.      *
  100.      * Checks whether the given property has been bound to listeners.
  101.      *
  102.      * @param propertyName  the name of the property
  103.      * @return              {@code true} if the property is bound
  104.      *
  105.      ******************************************************************************************************************/
  106.     public boolean hasListeners (@Nonnull String propertyName);

  107.     /*******************************************************************************************************************
  108.      *
  109.      * Returns all the bound {@link PropertyChangeListener}s.
  110.      *
  111.      * @return              the listeners
  112.      *
  113.      ******************************************************************************************************************/
  114.     @Nonnull
  115.     public PropertyChangeListener[] getPropertyChangeListeners();

  116.     /*******************************************************************************************************************
  117.      *
  118.      * Returns the bound {@link PropertyChangeListener}s for the given property.
  119.      *
  120.      * @param propertyName  the name of the property
  121.      * @return              the listeners
  122.      *
  123.      ******************************************************************************************************************/
  124.     @Nonnull
  125.     public PropertyChangeListener[] getPropertyChangeListeners (@Nonnull String propertyName);

  126.     /*******************************************************************************************************************
  127.      *
  128.      * Creates an instance given an owner and no roles.
  129.      *
  130.      * @param   owner   the owner
  131.      * @return          the new instance
  132.      * @since           3.2-ALPHA-3
  133.      *
  134.      ******************************************************************************************************************/
  135.     @Nonnull
  136.     public static PresentationModel of (@Nonnull final Object owner)
  137.       {
  138.         Parameters.mustNotBeArrayOrCollection(owner, "owner");
  139.         return of(owner, Collections.emptyList());
  140.       }

  141.     /*******************************************************************************************************************
  142.      *
  143.      * Creates an instance given an owner and a single role.
  144.      *
  145.      * @param   owner   the owner
  146.      * @param   role    the role (or a {@link it.tidalwave.util.RoleFactory})
  147.      * @return          the new instance
  148.      * @since           3.2-ALPHA-3
  149.      *
  150.      ******************************************************************************************************************/
  151.     @Nonnull
  152.     public static PresentationModel of (@Nonnull final Object owner, @Nonnull final Object role)
  153.       {
  154.         Parameters.mustNotBeArrayOrCollection(owner, "owner");
  155.         Parameters.mustNotBeArrayOrCollection(role, "role");
  156.         return of(owner, r(role));
  157.       }

  158.     /*******************************************************************************************************************
  159.      *
  160.      * Creates an instance given an owner and multiple roles.
  161.      *
  162.      * @param   owner   the owner
  163.      * @param   roles   roles or {@link it.tidalwave.util.RoleFactory} instances
  164.      * @return          the new instance
  165.      * @since           3.2-ALPHA-1
  166.      * @since           3.2-ALPHA-3 (refactored)
  167.      *
  168.      ******************************************************************************************************************/
  169.     @Nonnull
  170.     public static PresentationModel of (@Nonnull final Object owner, @Nonnull final Collection<Object> roles)
  171.       {
  172.         Parameters.mustNotBeArrayOrCollection(owner, "owner");
  173.         return new DefaultPresentationModel(owner, roles);
  174.       }

  175.     /*******************************************************************************************************************
  176.      *
  177.      * Returns an empty instance (no roles, with the exception of a dummy {@link Displayable}).
  178.      *
  179.      * @return          the empty instance
  180.      * @since           3.2-ALPHA-3
  181.      *
  182.      ******************************************************************************************************************/
  183.     @Nonnull
  184.     public static PresentationModel empty()
  185.       {
  186.         // TODO: cache a singleton, but don't do eager initialization (e.g. a final static), as it would deadlock with
  187.         // SteelBlue.
  188.         return of("", Displayable.of("<empty presentation model>"));
  189.       }

  190.     /*******************************************************************************************************************
  191.      *
  192.      * Creates an instance from an owner which might have the {@link Presentable} role. If it is present, it is called
  193.      * to create the {@code PresentationModel}; otherwise a default one is created. Additional roles are added.
  194.      *
  195.      * @param   owner   the owner
  196.      * @param   roles   roles or {@link it.tidalwave.util.RoleFactory} instances
  197.      * @return          the new instance
  198.      * @since           3.2-ALPHA-8
  199.      * @it.tidalwave.javadoc.experimental TODO: perhaps it could be merged to of().
  200.      *
  201.      ******************************************************************************************************************/
  202.     @Nonnull
  203.     public static PresentationModel ofMaybePresentable (@Nonnull final As owner, @Nonnull final Collection<Object> roles)
  204.       {
  205.         Parameters.mustNotBeArrayOrCollection(owner, "owner");
  206.         return owner.maybeAs(_Presentable_)
  207.                     .map(p -> p.createPresentationModel(roles))
  208.                     .orElseGet(() -> of(owner, roles));
  209.       }

  210.     /*******************************************************************************************************************
  211.      *
  212.      * Creates an instance from an owner which might have the {@link Presentable} role. If it is present, it is called
  213.      * to create the {@code PresentationModel}; otherwise a default one is created.
  214.      *
  215.      * @param   owner   the owner
  216.      * @return          the new instance
  217.      * @since           3.2-ALPHA-8
  218.      * @it.tidalwave.javadoc.experimental TODO: perhaps it could be merged to of().
  219.      *
  220.      ******************************************************************************************************************/
  221.     @Nonnull
  222.     public static PresentationModel ofMaybePresentable (@Nonnull final As owner)
  223.       {
  224.         return ofMaybePresentable(owner, Collections.emptyList());
  225.       }
  226.   }