Mutable.java

  1. /*
  2.  * *************************************************************************************************************************************************************
  3.  *
  4.  * SteelBlue: DCI User Interfaces
  5.  * http://tidalwave.it/projects/steelblue
  6.  *
  7.  * Copyright (C) 2015 - 2025 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/steelblue-src
  22.  * git clone https://github.com/tidalwave-it/steelblue-src
  23.  *
  24.  * *************************************************************************************************************************************************************
  25.  */
  26. package it.tidalwave.ui.core;

  27. import jakarta.annotation.Nonnull;
  28. import java.beans.PropertyChangeListener;
  29. import org.apiguardian.api.API;
  30. import static org.apiguardian.api.API.Status.EXPERIMENTAL;

  31. /***************************************************************************************************************************************************************
  32.  *
  33.  * An interface that describes the capability of mutate status and of supporting listeners. Both old-style {@link PropertyChangeListener} and a new
  34.  * experimental {@link MutableListener}s are supported. The three different methods {@link #addListener1(MutableListener1)},
  35.  * {@link #addListener2(MutableListener2)} and {@link #addListener(MutableListener)} allow shorter syntaxes when only one or two parameters
  36.  * of the callback are needed, that is:
  37.  *
  38.  * <pre>
  39.  * {@code
  40.  * mutable.addMutableListener1(newValue -> consumer1.accept(newValue));
  41.  * mutable.addMutableListener2((oldValue, newValue) -> consumer2.accept(oldValue, newValue));
  42.  * mutable.addMutableListener((source, oldValue, newValue) -> consumer3.accept(source, oldValue, newValue));
  43.  * }
  44.  * </pre>
  45.  *
  46.  * @see           MutableListener
  47.  * @see           MutableListener1
  48.  * @see           MutableListener2
  49.  * @since         2.0-ALPHA-2
  50.  * @author        Fabrizio Giudici
  51.  *
  52.  **************************************************************************************************************************************************************/
  53. @API(status = EXPERIMENTAL)
  54. public interface Mutable
  55.   {
  56.     /***********************************************************************************************************************************************************
  57.      * Registers a {@link PropertyChangeListener}.
  58.      * @param  listener   the listener
  59.      **********************************************************************************************************************************************************/
  60.     public void addPropertyChangeListener (@Nonnull PropertyChangeListener listener);

  61.     /***********************************************************************************************************************************************************
  62.      * Registers a {@link PropertyChangeListener} for the given property.
  63.      * @param propertyName  the name of the property
  64.      * @param listener      the listener
  65.      **********************************************************************************************************************************************************/
  66.     public void addPropertyChangeListener (@Nonnull String propertyName, @Nonnull PropertyChangeListener listener);

  67.     /***********************************************************************************************************************************************************
  68.      * Unregisters a {@link PropertyChangeListener}.
  69.      * @param  listener   the listener
  70.      **********************************************************************************************************************************************************/
  71.     public void removePropertyChangeListener (@Nonnull PropertyChangeListener listener);

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

  78.     /***********************************************************************************************************************************************************
  79.      * Returns all the bound {@link PropertyChangeListener}s.
  80.      * @return              the listeners
  81.      **********************************************************************************************************************************************************/
  82.     @Nonnull
  83.     public PropertyChangeListener[] getPropertyChangeListeners();

  84.     /***********************************************************************************************************************************************************
  85.      * Returns the bound {@link PropertyChangeListener}s for the given property.
  86.      * @param propertyName  the name of the property
  87.      * @return              the listeners
  88.      **********************************************************************************************************************************************************/
  89.     @Nonnull
  90.     public PropertyChangeListener[] getPropertyChangeListeners (@Nonnull String propertyName);

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

  97.     /***********************************************************************************************************************************************************
  98.      * Registers a {@link MutableListener}.
  99.      * @param  <T>        the type of the listener
  100.      * @param  listener   the listener
  101.      **********************************************************************************************************************************************************/
  102.     public <T> void addListener (@Nonnull final MutableListener<T> listener);

  103.     /***********************************************************************************************************************************************************
  104.      * Registers a {@link MutableListener}. This method is needed to allow the compiler to infer the correct type of lambdas.
  105.      * @param  <T>        the type of the listener
  106.      * @param  listener   the listener
  107.      **********************************************************************************************************************************************************/
  108.     public default <T> void addListener1 (@Nonnull final MutableListener1<T> listener)
  109.       {
  110.         addListener(listener);
  111.       }

  112.     /***********************************************************************************************************************************************************
  113.      * Registers a {@link MutableListener}. This method is needed to allow the compiler to infer the correct type of lambdas.
  114.      * @param  <T>        the type of the listener
  115.      * @param  listener   the listener
  116.      **********************************************************************************************************************************************************/
  117.     public default <T> void addListener2 (@Nonnull final MutableListener2<T> listener)
  118.       {
  119.         addListener(listener);
  120.       }

  121.     /***********************************************************************************************************************************************************
  122.      * Unregisters a {@link MutableListener}.
  123.      * @param  <T>        the type of the listener
  124.      * @param  listener   the listener
  125.      **********************************************************************************************************************************************************/
  126.     public <T> void removeListener (@Nonnull final MutableListener<T> listener);
  127.   }