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

  27. import jakarta.annotation.Nonnull;
  28. import java.util.Comparator;
  29. import java.util.Locale;
  30. import java.util.Map;
  31. import java.util.SortedSet;
  32. import java.util.TreeSet;
  33. import java.util.function.Consumer;
  34. import java.util.function.Function;
  35. import java.util.function.Supplier;
  36. import it.tidalwave.ui.core.role.impl.AsDisplayableComparator;
  37. import it.tidalwave.ui.core.role.impl.DefaultDisplayable;
  38. import it.tidalwave.ui.core.role.impl.DisplayableComparator;
  39. import it.tidalwave.util.As;
  40. import static it.tidalwave.util.BundleUtilities.getMessage;

  41. /***************************************************************************************************************************************************************
  42.  *
  43.  * The role of an object which can provide its own display name.
  44.  *
  45.  * @stereotype Role
  46.  *
  47.  * @since   2.0-ALPHA-1
  48.  * @author  Fabrizio Giudici
  49.  * @it.tidalwave.javadoc.stable
  50.  *
  51.  **************************************************************************************************************************************************************/
  52. @FunctionalInterface
  53. public interface Displayable
  54.   {
  55.     /** Shortcut for {@link it.tidalwave.util.As}. */
  56.     public static final Class<Displayable> _Displayable_ = Displayable.class;

  57.     /***********************************************************************************************************************************************************
  58.      * A default {@code Displayable} with an empty display name.
  59.      **********************************************************************************************************************************************************/
  60.     public static final Displayable DEFAULT = new DefaultDisplayable("", "DEFAULT");

  61.     /***********************************************************************************************************************************************************
  62.      * Returns the display name in the current {@link java.util.Locale}.
  63.      *
  64.      * @return  the display name
  65.      **********************************************************************************************************************************************************/
  66.     @Nonnull
  67.     public String getDisplayName();

  68.     /***********************************************************************************************************************************************************
  69.      * Returns the display name in the given {@link Locale}.
  70.      * @param    locale       the {@code Locale}
  71.      * @since                 2.0-ALPHA-2
  72.      * @return                the display name
  73.      **********************************************************************************************************************************************************/
  74.     @Nonnull
  75.     public default String getDisplayName (@Nonnull final Locale locale)
  76.       {
  77.         return getDisplayName();
  78.       }

  79.     /***********************************************************************************************************************************************************
  80.      * Returns all the display names in {@link Map} where they are indexed by {@code Locale}.
  81.      * @since                 2.0-ALPHA-2
  82.      * @return                the display names
  83.      **********************************************************************************************************************************************************/
  84.     @Nonnull
  85.     public default Map<Locale, String> getDisplayNames()
  86.       {
  87.         return Map.of();
  88.       }

  89.     /***********************************************************************************************************************************************************
  90.      * Returns the supported {@code Locale}s.
  91.      * @since                 2.0-ALPHA-2
  92.      * @return                the available {@code Locale}s
  93.      **********************************************************************************************************************************************************/
  94.     @Nonnull
  95.     public default SortedSet<Locale> getLocales()
  96.       {
  97.         return new TreeSet<>();
  98.       }

  99.     /***********************************************************************************************************************************************************
  100.      * Sends the display name in the current {@link java.util.Locale} to a given customer.
  101.      *
  102.      * @param     consumer    the {@code Consumer}
  103.      * @since     3.2-ALPHA-15
  104.      **********************************************************************************************************************************************************/
  105.     @SuppressWarnings("BoundedWildcard")
  106.     public default void display (@Nonnull final Consumer<String> consumer)
  107.       {
  108.         consumer.accept(getDisplayName());
  109.       }

  110.     /***********************************************************************************************************************************************************
  111.      * Creates an instance with a given display name.
  112.      *
  113.      * @param  displayName    the display name
  114.      * @return                the new instance
  115.      * @since                 3.2-ALPHA-1 (was {@code DefaultDisplayable}
  116.      **********************************************************************************************************************************************************/
  117.     @Nonnull
  118.     public static Displayable of (@Nonnull final String displayName)
  119.       {
  120.         return of(displayName, "???");
  121.       }

  122.     /***********************************************************************************************************************************************************
  123.      * Creates an instance with a given display name iand an explicit label for  {@code toString()}.
  124.      *
  125.      * @param  displayName    the display name
  126.      * @param  toStringName   the name to be rendered when {@code toString()} is called
  127.      * @return                the new instance
  128.      * @since                 3.2-ALPHA-1 (was {@code DefaultDisplayable}
  129.      **********************************************************************************************************************************************************/
  130.     @Nonnull
  131.     public static Displayable of (@Nonnull final String displayName, @Nonnull final String toStringName)
  132.       {
  133.         return new DefaultDisplayable(displayName, toStringName);
  134.       }

  135.     /***********************************************************************************************************************************************************
  136.      * Creates an instance from a {@link Supplier}{@code <String>}. The supplier is invoked each time
  137.      * {@link #getDisplayName()} is called.
  138.      *
  139.      * @param   supplier      the {@code Supplier}
  140.      * @return                the new instance
  141.      * @since                 3.2-ALPHA-3
  142.      * @it.tidalwave.javadoc.experimental
  143.      **********************************************************************************************************************************************************/
  144.     @Nonnull
  145.     public static Displayable of (@Nonnull final Supplier<String> supplier)
  146.       {
  147.         return supplier::get;
  148.       }

  149.     /***********************************************************************************************************************************************************
  150.      * Creates an instance from a {@link Function}{@code <T, String>} and a generic object that the function is applied
  151.      * to. The function is invoked each time {@link #getDisplayName()} is called.
  152.      *
  153.      * @param   <T>           the type of the object
  154.      * @param   function      the {@code Function}
  155.      * @param   object        the object
  156.      * @return                the new instance
  157.      * @since                 3.2-ALPHA-3
  158.      * @it.tidalwave.javadoc.experimental
  159.      **********************************************************************************************************************************************************/
  160.     @Nonnull
  161.     public static <T> Displayable of (@Nonnull final Function<T, String> function, @Nonnull final T object)
  162.       {
  163.         return () -> function.apply(object);
  164.       }

  165.     /***********************************************************************************************************************************************************
  166.      * Creates a {@link Displayable} from a resource bundle. The bundle resource file is named {@code Bundle.properties} and it should be placed in the same
  167.      * package as the owner class.
  168.      * @param   ownerClass    the class that owns the bundle
  169.      * @param   key           the resource key
  170.      * @since                 2.0-ALPHA-2
  171.      * @return                the new instance
  172.      **********************************************************************************************************************************************************/
  173.     @Nonnull
  174.     public static Displayable fromBundle (@Nonnull final Class<?> ownerClass, @Nonnull final String key)
  175.       {
  176.         return new DefaultDisplayable(getMessage(ownerClass, key));
  177.       }

  178.     /***********************************************************************************************************************************************************
  179.      * Returns a {@link Comparator} for comparing two instances of {@code Displayable}.
  180.      *
  181.      * @return  the {@code Comparator}
  182.      * @since   3.2-ALPHA-6
  183.      **********************************************************************************************************************************************************/
  184.     @Nonnull
  185.     public static Comparator<Displayable> comparing()
  186.       {
  187.         return DisplayableComparator.getInstance();
  188.       }

  189.     /***********************************************************************************************************************************************************
  190.      * Returns a {@link Comparator} for comparing two instances of objects implementing {@code As} that contain the
  191.      * {@code Displayable} role.
  192.      *
  193.      * @return  the {@code Comparator}
  194.      * @since   3.2-ALPHA-6
  195.      **********************************************************************************************************************************************************/
  196.     @Nonnull
  197.     public static Comparator<As> asComparing()
  198.       {
  199.         return AsDisplayableComparator.getInstance();
  200.       }

  201.     /***********************************************************************************************************************************************************
  202.      * Renders the attached object into a {@link String}. The method accepts optional parameters that can be used to control the format of the rendering; they
  203.      * are usually specific of the object attached to this role.
  204.      * @param  args  optional rendering parameters
  205.      * @return       the string
  206.      **********************************************************************************************************************************************************/
  207.     @Nonnull
  208.     public default String render (@Nonnull final Object ... args)
  209.       {
  210.         return getDisplayName();
  211.       }

  212.     /***********************************************************************************************************************************************************
  213.      * Renders the attached object providing the string tu a {@link Consumer}. The method accepts optional parameters that can be used to control the format of
  214.      * the rendering; they are usually specific of the object attached to this role.
  215.      * @param  consumer        the {@code Consumer} to append to
  216.      * @param  args            optional rendering parameters
  217.      **********************************************************************************************************************************************************/
  218.     public default void renderTo (@Nonnull final Consumer<? super String> consumer, @Nonnull final Object ... args)
  219.       {
  220.         consumer.accept(render(args));
  221.       }
  222.   }