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

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

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

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

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

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

  57.     /***********************************************************************************************************************************************************
  58.      * Disposes this object.
  59.      **********************************************************************************************************************************************************/
  60.     public void dispose();

  61.     /***********************************************************************************************************************************************************
  62.      * Adds a {@link PropertyChangeListener}.
  63.      *
  64.      * @param listener    the listener
  65.      **********************************************************************************************************************************************************/
  66.     public void addPropertyChangeListener (@Nonnull PropertyChangeListener listener);

  67.     /***********************************************************************************************************************************************************
  68.      * Adds a {@link PropertyChangeListener} for the given property.
  69.      *
  70.      * @param propertyName  the name of the property
  71.      * @param listener      the listener
  72.      **********************************************************************************************************************************************************/
  73.     public void addPropertyChangeListener (@Nonnull String propertyName, @Nonnull PropertyChangeListener listener);

  74.     /***********************************************************************************************************************************************************
  75.      * Removes a {@link PropertyChangeListener}.
  76.      *
  77.      * @param listener    the listener
  78.      **********************************************************************************************************************************************************/
  79.     public void removePropertyChangeListener (@Nonnull PropertyChangeListener listener);

  80.     /***********************************************************************************************************************************************************
  81.      * Removes a {@link PropertyChangeListener} for the given property.
  82.      *
  83.      * @param propertyName  the name of the property
  84.      * @param listener      the listener
  85.      **********************************************************************************************************************************************************/
  86.     public void removePropertyChangeListener (@Nonnull String propertyName, @Nonnull PropertyChangeListener listener);

  87.     /***********************************************************************************************************************************************************
  88.      * Checks whether the given property has been bound to listeners.
  89.      *
  90.      * @param propertyName  the name of the property
  91.      * @return              {@code true} if the property is bound
  92.      **********************************************************************************************************************************************************/
  93.     public boolean hasListeners (@Nonnull String propertyName);

  94.     /***********************************************************************************************************************************************************
  95.      * Returns all the bound {@link PropertyChangeListener}s.
  96.      *
  97.      * @return              the listeners
  98.      **********************************************************************************************************************************************************/
  99.     @Nonnull
  100.     public PropertyChangeListener[] getPropertyChangeListeners();

  101.     /***********************************************************************************************************************************************************
  102.      * Returns the bound {@link PropertyChangeListener}s for the given property.
  103.      *
  104.      * @param propertyName  the name of the property
  105.      * @return              the listeners
  106.      **********************************************************************************************************************************************************/
  107.     @Nonnull
  108.     public PropertyChangeListener[] getPropertyChangeListeners (@Nonnull String propertyName);

  109.     /***********************************************************************************************************************************************************
  110.      * Creates an instance given an owner and no roles.
  111.      *
  112.      * @param   owner   the owner
  113.      * @return          the new instance
  114.      * @since           3.2-ALPHA-3
  115.      **********************************************************************************************************************************************************/
  116.     @Nonnull
  117.     public static PresentationModel of (@Nonnull final Object owner)
  118.       {
  119.         Parameters.mustNotBeArrayOrCollection(owner, "owner");
  120.         return of(owner, Collections.emptyList());
  121.       }

  122.     /***********************************************************************************************************************************************************
  123.      * Creates an instance given an owner and a single role.
  124.      *
  125.      * @param   owner   the owner
  126.      * @param   role    the role (or a {@link it.tidalwave.util.RoleFactory})
  127.      * @return          the new instance
  128.      * @since           3.2-ALPHA-3
  129.      **********************************************************************************************************************************************************/
  130.     @Nonnull
  131.     public static PresentationModel of (@Nonnull final Object owner, @Nonnull final Object role)
  132.       {
  133.         Parameters.mustNotBeArrayOrCollection(owner, "owner");
  134.         Parameters.mustNotBeArrayOrCollection(role, "role");
  135.         return of(owner, r(role));
  136.       }

  137.     /***********************************************************************************************************************************************************
  138.      * Creates an instance given an owner and multiple roles.
  139.      *
  140.      * @param   owner   the owner
  141.      * @param   roles   roles or {@link it.tidalwave.util.RoleFactory} instances
  142.      * @return          the new instance
  143.      * @since           3.2-ALPHA-1
  144.      * @since           3.2-ALPHA-3 (refactored)
  145.      **********************************************************************************************************************************************************/
  146.     @Nonnull
  147.     public static PresentationModel of (@Nonnull final Object owner, @Nonnull final Collection<Object> roles)
  148.       {
  149.         Parameters.mustNotBeArrayOrCollection(owner, "owner");
  150.         return new DefaultPresentationModel(owner, roles);
  151.       }

  152.     /***********************************************************************************************************************************************************
  153.      * Returns an empty instance (no roles, with the exception of a dummy {@link Displayable}).
  154.      *
  155.      * @return          the empty instance
  156.      * @since           3.2-ALPHA-3
  157.      **********************************************************************************************************************************************************/
  158.     @Nonnull
  159.     public static PresentationModel empty()
  160.       {
  161.         // TODO: cache a singleton, but don't do eager initialization (e.g. a final static), as it would deadlock with
  162.         // SteelBlue.
  163.         return of("", Displayable.of("<empty presentation model>"));
  164.       }

  165.     /***********************************************************************************************************************************************************
  166.      * Creates an instance from an owner which might have the {@link Presentable} role. If it is present, it is called
  167.      * to create the {@code PresentationModel}; otherwise a default one is created. Additional roles are added.
  168.      *
  169.      * @param   owner   the owner
  170.      * @param   roles   roles or {@link it.tidalwave.util.RoleFactory} instances
  171.      * @return          the new instance
  172.      * @since           3.2-ALPHA-8
  173.      * @it.tidalwave.javadoc.experimental TODO: perhaps it could be merged to of().
  174.      **********************************************************************************************************************************************************/
  175.     @Nonnull
  176.     public static PresentationModel ofMaybePresentable (@Nonnull final As owner, @Nonnull final Collection<Object> roles)
  177.       {
  178.         Parameters.mustNotBeArrayOrCollection(owner, "owner");
  179.         return owner.maybeAs(_Presentable_)
  180.                     .map(p -> p.createPresentationModel(roles))
  181.                     .orElseGet(() -> of(owner, roles));
  182.       }

  183.     /***********************************************************************************************************************************************************
  184.      * Creates an instance from an owner which might have the {@link Presentable} role. If it is present, it is called
  185.      * to create the {@code PresentationModel}; otherwise a default one is created.
  186.      *
  187.      * @param   owner   the owner
  188.      * @return          the new instance
  189.      * @since           3.2-ALPHA-8
  190.      * @it.tidalwave.javadoc.experimental TODO: perhaps it could be merged to of().
  191.      **********************************************************************************************************************************************************/
  192.     @Nonnull
  193.     public static PresentationModel ofMaybePresentable (@Nonnull final As owner)
  194.       {
  195.         return ofMaybePresentable(owner, Collections.emptyList());
  196.       }
  197.   }