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;

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

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

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

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

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

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

  95.     /***********************************************************************************************************************************************************
  96.      * Returns the supported {@code Locale}s.
  97.      * @since                 2.0-ALPHA-2
  98.      * @return                the available {@code Locale}s
  99.      **********************************************************************************************************************************************************/
  100.     @Nonnull
  101.     public default SortedSet<Locale> getLocales()
  102.       {
  103.         return new TreeSet<>();
  104.       }

  106.     /***********************************************************************************************************************************************************
  107.      * Sends the display name in the current {@link java.util.Locale} to a given customer.
  108.      *
  109.      * @param     consumer    the {@code Consumer}
  110.      * @since     3.2-ALPHA-15
  111.      **********************************************************************************************************************************************************/
  112.     @SuppressWarnings("BoundedWildcard")
  113.     public default void display (@Nonnull final Consumer<String> consumer)
  114.       {
  115.         consumer.accept(getDisplayName());
  116.       }

  118.     /***********************************************************************************************************************************************************
  119.      * Creates an instance with a given display name.
  120.      *
  121.      * @param  displayName    the display name
  122.      * @return                the new instance
  123.      * @since                 3.2-ALPHA-1 (was {@code DefaultDisplayable}
  124.      **********************************************************************************************************************************************************/
  125.     @Nonnull
  126.     public static Displayable of (@Nonnull final String displayName)
  127.       {
  128.         return of(displayName, "???");
  129.       }

  131.     /***********************************************************************************************************************************************************
  132.      * Creates an instance with a given display name iand an explicit label for  {@code toString()}.
  133.      *
  134.      * @param  displayName    the display name
  135.      * @param  toStringName   the name to be rendered when {@code toString()} is called
  136.      * @return                the new instance
  137.      * @since                 3.2-ALPHA-1 (was {@code DefaultDisplayable}
  138.      **********************************************************************************************************************************************************/
  139.     @Nonnull
  140.     public static Displayable of (@Nonnull final String displayName, @Nonnull final String toStringName)
  141.       {
  142.         return new DefaultDisplayable(displayName, toStringName);
  143.       }

  145.     /***********************************************************************************************************************************************************
  146.      * Creates an instance from a {@link Supplier}{@code <String>}. The supplier is invoked each time
  147.      * {@link #getDisplayName()} is called.
  148.      *
  149.      * @param   supplier      the {@code Supplier}
  150.      * @return                the new instance
  151.      * @since                 3.2-ALPHA-3
  152.      * @it.tidalwave.javadoc.experimental
  153.      **********************************************************************************************************************************************************/
  154.     @Nonnull
  155.     public static Displayable of (@Nonnull final Supplier<String> supplier)
  156.       {
  157.         return supplier::get;
  158.       }

  160.     /***********************************************************************************************************************************************************
  161.      * Creates an instance from a {@link Function}{@code <T, String>} and a generic object that the function is applied
  162.      * to. The function is invoked each time {@link #getDisplayName()} is called.
  163.      *
  164.      * @param   <T>           the type of the object
  165.      * @param   function      the {@code Function}
  166.      * @param   object        the object
  167.      * @return                the new instance
  168.      * @since                 3.2-ALPHA-3
  169.      * @it.tidalwave.javadoc.experimental
  170.      **********************************************************************************************************************************************************/
  171.     @Nonnull
  172.     public static <T> Displayable of (@Nonnull final Function<T, String> function, @Nonnull final T object)
  173.       {
  174.         return () -> function.apply(object);
  175.       }

  177.     /***********************************************************************************************************************************************************
  178.      * 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
  179.      * package as the owner class.
  180.      * @param   ownerClass    the class that owns the bundle
  181.      * @param   key           the resource key
  182.      * @since                 2.0-ALPHA-2
  183.      * @return                the new instance
  184.      **********************************************************************************************************************************************************/
  185.     @Nonnull
  186.     public static Displayable fromBundle (@Nonnull final Class<?> ownerClass, @Nonnull final String key)
  187.       {
  188.         return new DefaultDisplayable(getMessage(ownerClass, key));
  189.       }

  191.     /***********************************************************************************************************************************************************
  192.      * Returns a {@link Comparator} for comparing two instances of {@code Displayable}.
  193.      *
  194.      * @return  the {@code Comparator}
  195.      * @since   3.2-ALPHA-6
  196.      **********************************************************************************************************************************************************/
  197.     @Nonnull
  198.     public static Comparator<Displayable> comparing()
  199.       {
  200.         return DisplayableComparator.getInstance();
  201.       }

  203.     /***********************************************************************************************************************************************************
  204.      * Returns a {@link Comparator} for comparing two instances of objects implementing {@code As} that contain the
  205.      * {@code Displayable} role.
  206.      *
  207.      * @return  the {@code Comparator}
  208.      * @since   3.2-ALPHA-6
  209.      **********************************************************************************************************************************************************/
  210.     @Nonnull
  211.     public static Comparator<As> asComparing()
  212.       {
  213.         return AsDisplayableComparator.getInstance();
  214.       }

  216.     /***********************************************************************************************************************************************************
  217.      * 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
  218.      * are usually specific of the object attached to this role.
  219.      * @param  args  optional rendering parameters
  220.      * @return       the string
  221.      **********************************************************************************************************************************************************/
  222.     @Nonnull
  223.     public default String render (@Nonnull final Object ... args)
  224.       {
  225.         return getDisplayName();
  226.       }

  228.     /***********************************************************************************************************************************************************
  229.      * 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
  230.      * the rendering; they are usually specific of the object attached to this role.
  231.      * @param  consumer        the {@code Consumer} to append to
  232.      * @param  args            optional rendering parameters
  233.      **********************************************************************************************************************************************************/
  234.     public default void renderTo (@Nonnull final Consumer<? super String> consumer, @Nonnull final Object ... args)
  235.       {
  236.         consumer.accept(render(args));
  237.       }
  238.   }
Created with JaCoCo 0.8.12.202403310830