Displayable.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.util.Comparator;
  30. import java.util.function.Consumer;
  31. import java.util.function.Function;
  32. import java.util.function.Supplier;
  33. import it.tidalwave.util.As;
  34. import it.tidalwave.role.ui.impl.AsDisplayableComparator;
  35. import it.tidalwave.role.ui.impl.DefaultDisplayable;
  36. import it.tidalwave.role.ui.impl.DisplayableComparator;
  37. import static it.tidalwave.util.BundleUtilities.getMessage;

  38. /***********************************************************************************************************************
  39.  *
  40.  * The role of an object which can provide its own display name.
  41.  *
  42.  * @stereotype Role
  43.  *
  44.  * @author  Fabrizio Giudici
  45.  * @it.tidalwave.javadoc.stable
  46.  *
  47.  **********************************************************************************************************************/
  48. @FunctionalInterface
  49. public interface Displayable
  50.   {
  51.     public static final Class<Displayable> _Displayable_ = Displayable.class;

  52.     /*******************************************************************************************************************
  53.      *
  54.      * A default {@code Displayable} with an empty display name.
  55.      *
  56.      ******************************************************************************************************************/
  57.     public static final Displayable DEFAULT = new DefaultDisplayable("", "DEFAULT");

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

  67.     /*******************************************************************************************************************
  68.      *
  69.      * Sends the display name in the current {@link java.util.Locale} to a given customer.
  70.      *
  71.      * @param     consumer    the {@code Consumer}
  72.      * @since     3.2-ALPHA-15
  73.      *
  74.      ******************************************************************************************************************/
  75.     @SuppressWarnings("BoundedWildcard")
  76.     public default void display (@Nonnull final Consumer<String> consumer)
  77.       {
  78.         consumer.accept(getDisplayName());
  79.       }

  80.     /*******************************************************************************************************************
  81.      *
  82.      * Creates an instance with a given display name.
  83.      *
  84.      * @param  displayName    the display name
  85.      * @return                the new instance
  86.      * @since                 3.2-ALPHA-1 (was {@code DefaultDisplayable}
  87.      *
  88.      ******************************************************************************************************************/
  89.     @Nonnull
  90.     public static Displayable of (@Nonnull final String displayName)
  91.       {
  92.         return of(displayName, "???");
  93.       }

  94.     /*******************************************************************************************************************
  95.      *
  96.      * Creates an instance with a given display name iand an explicit label for  {@code toString()}.
  97.      *
  98.      * @param  displayName    the display name
  99.      * @param  toStringName   the name to be rendered when {@code toString()} is called
  100.      * @return                the new instance
  101.      * @since                 3.2-ALPHA-1 (was {@code DefaultDisplayable}
  102.      *
  103.      ******************************************************************************************************************/
  104.     @Nonnull
  105.     public static Displayable of (@Nonnull final String displayName, @Nonnull final String toStringName)
  106.       {
  107.         return new DefaultDisplayable(displayName, toStringName);
  108.       }

  109.     /*******************************************************************************************************************
  110.      *
  111.      * Creates an instance from a {@link Supplier}{@code <String>}. The supplier is invoked each time
  112.      * {@link #getDisplayName()} is called.
  113.      *
  114.      * @param   supplier      the {@code Supplier}
  115.      * @return                the new instance
  116.      * @since                 3.2-ALPHA-3
  117.      * @it.tidalwave.javadoc.experimental
  118.      *
  119.      ******************************************************************************************************************/
  120.     @Nonnull
  121.     public static Displayable of (@Nonnull final Supplier<String> supplier)
  122.       {
  123.         return supplier::get;
  124.       }

  125.     /*******************************************************************************************************************
  126.      *
  127.      * Creates an instance from a {@link Function}{@code <T, String>} and a generic object that the function is applied
  128.      * to. The function is invoked each time {@link #getDisplayName()} is called.
  129.      *
  130.      * @param   <T>           the type of the object
  131.      * @param   function      the {@code Function}
  132.      * @param   object        the object
  133.      * @return                the new instance
  134.      * @since                 3.2-ALPHA-3
  135.      * @it.tidalwave.javadoc.experimental
  136.      *
  137.      ******************************************************************************************************************/
  138.     @Nonnull
  139.     public static <T> Displayable of (@Nonnull final Function<T, String> function, @Nonnull final T object)
  140.       {
  141.         return () -> function.apply(object);
  142.       }

  143.     /*******************************************************************************************************************
  144.      *
  145.      * Creates a {@link LocalizedDisplayable} from a resource bundle. The bundle resource file is named
  146.      * {@code Bundle.properties} and it should be placed in the same package as the owner class.
  147.      *
  148.      * @param   ownerClass    the class that owns the bundle
  149.      * @param   key           the resource key
  150.      * @return                the new instance
  151.      * @since                 3.2-ALPHA-1 (was previously in {@code Displayable8}
  152.      *
  153.      ******************************************************************************************************************/
  154.     @Nonnull
  155.     public static LocalizedDisplayable fromBundle (@Nonnull final Class<?> ownerClass, @Nonnull final String key)
  156.       {
  157.         return new DefaultDisplayable(getMessage(ownerClass, key));
  158.       }

  159.     /*******************************************************************************************************************
  160.      *
  161.      * Returns a {@link Comparator} for comparing two instances of {@code Displayable}.
  162.      *
  163.      * @return  the {@code Comparator}
  164.      * @since   3.2-ALPHA-6
  165.      *
  166.      ******************************************************************************************************************/
  167.     @Nonnull
  168.     public static Comparator<Displayable> comparing()
  169.       {
  170.         return DisplayableComparator.getInstance();
  171.       }

  172.     /*******************************************************************************************************************
  173.      *
  174.      * Returns a {@link Comparator} for comparing two instances of objects implementing {@code As} that contain the
  175.      * {@code Displayable} role.
  176.      *
  177.      * @return  the {@code Comparator}
  178.      * @since   3.2-ALPHA-6
  179.      *
  180.      ******************************************************************************************************************/
  181.     @Nonnull
  182.     public static Comparator<As> asComparing()
  183.       {
  184.         return AsDisplayableComparator.getInstance();
  185.       }
  186.   }