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
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 *
41 * The role of an object which can provide its own display name.
42 *
43 * @stereotype Role
44 *
45 * @author Fabrizio Giudici
46 * @it.tidalwave.javadoc.stable
47 *
48 **************************************************************************************************************************************************************/
49 @FunctionalInterface
50 public interface Displayable
51 {
52 public static final Class<Displayable> _Displayable_ = Displayable.class;
53
54 /***********************************************************************************************************************************************************
55 * A default {@code Displayable} with an empty display name.
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 @Nonnull
65 public String getDisplayName();
66
67 /***********************************************************************************************************************************************************
68 * Sends the display name in the current {@link java.util.Locale} to a given customer.
69 *
70 * @param consumer the {@code Consumer}
71 * @since 3.2-ALPHA-15
72 **********************************************************************************************************************************************************/
73 @SuppressWarnings("BoundedWildcard")
74 public default void display (@Nonnull final Consumer<String> consumer)
75 {
76 consumer.accept(getDisplayName());
77 }
78
79 /***********************************************************************************************************************************************************
80 * Creates an instance with a given display name.
81 *
82 * @param displayName the display name
83 * @return the new instance
84 * @since 3.2-ALPHA-1 (was {@code DefaultDisplayable}
85 **********************************************************************************************************************************************************/
86 @Nonnull
87 public static Displayable of (@Nonnull final String displayName)
88 {
89 return of(displayName, "???");
90 }
91
92 /***********************************************************************************************************************************************************
93 * Creates an instance with a given display name iand an explicit label for {@code toString()}.
94 *
95 * @param displayName the display name
96 * @param toStringName the name to be rendered when {@code toString()} is called
97 * @return the new instance
98 * @since 3.2-ALPHA-1 (was {@code DefaultDisplayable}
99 **********************************************************************************************************************************************************/
100 @Nonnull
101 public static Displayable of (@Nonnull final String displayName, @Nonnull final String toStringName)
102 {
103 return new DefaultDisplayable(displayName, toStringName);
104 }
105
106 /***********************************************************************************************************************************************************
107 * Creates an instance from a {@link Supplier}{@code <String>}. The supplier is invoked each time
108 * {@link #getDisplayName()} is called.
109 *
110 * @param supplier the {@code Supplier}
111 * @return the new instance
112 * @since 3.2-ALPHA-3
113 * @it.tidalwave.javadoc.experimental
114 **********************************************************************************************************************************************************/
115 @Nonnull
116 public static Displayable of (@Nonnull final Supplier<String> supplier)
117 {
118 return supplier::get;
119 }
120
121 /***********************************************************************************************************************************************************
122 * Creates an instance from a {@link Function}{@code <T, String>} and a generic object that the function is applied
123 * to. The function is invoked each time {@link #getDisplayName()} is called.
124 *
125 * @param <T> the type of the object
126 * @param function the {@code Function}
127 * @param object the object
128 * @return the new instance
129 * @since 3.2-ALPHA-3
130 * @it.tidalwave.javadoc.experimental
131 **********************************************************************************************************************************************************/
132 @Nonnull
133 public static <T> Displayable of (@Nonnull final Function<T, String> function, @Nonnull final T object)
134 {
135 return () -> function.apply(object);
136 }
137
138 /***********************************************************************************************************************************************************
139 * Creates a {@link LocalizedDisplayable} from a resource bundle. The bundle resource file is named
140 * {@code Bundle.properties} and it should be placed in the same package as the owner class.
141 *
142 * @param ownerClass the class that owns the bundle
143 * @param key the resource key
144 * @return the new instance
145 * @since 3.2-ALPHA-1 (was previously in {@code Displayable8}
146 **********************************************************************************************************************************************************/
147 @Nonnull
148 public static LocalizedDisplayable fromBundle (@Nonnull final Class<?> ownerClass, @Nonnull final String key)
149 {
150 return new DefaultDisplayable(getMessage(ownerClass, key));
151 }
152
153 /***********************************************************************************************************************************************************
154 * Returns a {@link Comparator} for comparing two instances of {@code Displayable}.
155 *
156 * @return the {@code Comparator}
157 * @since 3.2-ALPHA-6
158 **********************************************************************************************************************************************************/
159 @Nonnull
160 public static Comparator<Displayable> comparing()
161 {
162 return DisplayableComparator.getInstance();
163 }
164
165 /***********************************************************************************************************************************************************
166 * Returns a {@link Comparator} for comparing two instances of objects implementing {@code As} that contain the
167 * {@code Displayable} role.
168 *
169 * @return the {@code Comparator}
170 * @since 3.2-ALPHA-6
171 **********************************************************************************************************************************************************/
172 @Nonnull
173 public static Comparator<As> asComparing()
174 {
175 return AsDisplayableComparator.getInstance();
176 }
177 }