|
9 | 9 | import java.util.function.Function; |
10 | 10 | import java.util.function.Supplier; |
11 | 11 |
|
| 12 | +/** |
| 13 | + * Represents an object that stores attributes that can be retrieved and updated concurrently. |
| 14 | + * <p> |
| 15 | + * Attributes are indexed by {@link AttributeKey} objects, which can be created with {@link AttributeKey#register(Class)}. |
| 16 | + * These keys are used to get and set objects with the type declared in the attribute type parameter. |
| 17 | + */ |
12 | 18 | public interface AttributeHolder extends Observable, AttributeObservable { |
13 | 19 |
|
14 | | - AttributeRegistry getAttributes(); |
| 20 | + /** |
| 21 | + * Retrieves the {@link AttributeRegistry} instance powering this {@link AttributeHolder}. |
| 22 | + * This method should always return the same registry instance. |
| 23 | + * @return attribute registry powering this object |
| 24 | + */ |
| 25 | + @NotNull AttributeRegistry getAttributes(); |
15 | 26 |
|
16 | 27 | @Override |
17 | 28 | default @NotNull ObserverEmitter getObserver() { |
18 | 29 | return getAttributes().getObserver(); |
19 | 30 | } |
20 | 31 |
|
| 32 | + /** |
| 33 | + * Checks whether a given attribute is stored in this attribute holder. It is worth noting |
| 34 | + * that a null value is treated as the value not being stored. |
| 35 | + * @param key attribute key |
| 36 | + * @return whether a value is stored |
| 37 | + */ |
21 | 38 | default boolean hasAttribute(@NotNull AttributeKey<?> key) { |
22 | 39 | return getAttribute(key) != null; |
23 | 40 | } |
24 | 41 |
|
| 42 | + /** |
| 43 | + * Retrieves an attribute from a given attribute key. |
| 44 | + * @param key attribute key |
| 45 | + * @return current attribute value, or null if not stored |
| 46 | + */ |
25 | 47 | default <T> @Nullable T getAttribute(@NotNull AttributeKey<T> key) { |
26 | 48 | return getAttributes().getAttribute(key); |
27 | 49 | } |
28 | 50 |
|
29 | | - default <T> @Nullable T getAttributeOrDefault(@NotNull AttributeKey<T> key, @Nullable T defaultValue) { |
| 51 | + /** |
| 52 | + * Retrieves an attribute from a given attribute key, but returns a default value if the |
| 53 | + * attribute is not stored. This method will not set the default value as the stored value |
| 54 | + * if the attribute is not stored. |
| 55 | + * @param key attribute key |
| 56 | + * @param defaultValue default value to return if not stored |
| 57 | + * @return current attribute value, or default value if not stored |
| 58 | + */ |
| 59 | + default <T> @NotNull T getAttributeOrDefault(@NotNull AttributeKey<T> key, @NotNull T defaultValue) { |
30 | 60 | return getAttributes().getAttributeOrDefault(key, defaultValue); |
31 | 61 | } |
32 | 62 |
|
| 63 | + /** |
| 64 | + * Retrieves an attribute from a given attribute key, but calls default value if the |
| 65 | + * attribute is not stored. This method will set the default value as the stored value |
| 66 | + * if the attribute is not stored. |
| 67 | + * @param key attribute key |
| 68 | + * @param supplier default value supplier to call and return if not stored |
| 69 | + * @return final attribute value, or default value if not stored |
| 70 | + */ |
33 | 71 | default <T> @NotNull T getAttributeOrCreateDefault(@NotNull AttributeKey<T> key, @NotNull Supplier<@NotNull T> supplier) { |
34 | 72 | return getAttributes().getAttributeOrCreateDefault(key, supplier); |
35 | 73 | } |
36 | 74 |
|
| 75 | + /** |
| 76 | + * Sets an attribute with a given attribute key to a given value. If the given value is |
| 77 | + * null, the value will no longer be stored. |
| 78 | + * @param key attribute key |
| 79 | + * @param value new stored value |
| 80 | + */ |
37 | 81 | default <T> void setAttribute(@NotNull AttributeKey<T> key, @Nullable T value) { |
38 | 82 | getAttributes().setAttribute(key, value); |
39 | 83 | } |
40 | 84 |
|
41 | | - default <T> @Nullable T getAttributeOrSetDefault(@NotNull AttributeKey<T> key, @Nullable T defaultValue) { |
| 85 | + /** |
| 86 | + * Retrieves an attribute from a given attribute key, but returns a default value if the |
| 87 | + * attribute is not stored. This method will set the default value as the stored value |
| 88 | + * if the attribute is not stored. |
| 89 | + * @param key attribute key |
| 90 | + * @param defaultValue default value to return if not stored |
| 91 | + * @return final attribute value, or default value if not stored |
| 92 | + */ |
| 93 | + default <T> @Nullable T getAttributeOrSetDefault(@NotNull AttributeKey<T> key, @NotNull T defaultValue) { |
42 | 94 | return getAttributes().getAttributeOrSetDefault(key, defaultValue); |
43 | 95 | } |
44 | 96 |
|
45 | | - default <T> T getAttributeAndUpdate(@NotNull AttributeKey<T> key, @NotNull Function<@Nullable T, @Nullable T> function) { |
| 97 | + /** |
| 98 | + * Gets an attribute from a given attribute key, and applies a function to it before storing |
| 99 | + * the value returned by the function. |
| 100 | + * @param key attribute key |
| 101 | + * @param function function to apply to the previous value to obtain the new stored value |
| 102 | + * @return previous stored value |
| 103 | + */ |
| 104 | + default <T> @Nullable T getAttributeAndUpdate(@NotNull AttributeKey<T> key, @NotNull Function<@Nullable T, @Nullable T> function) { |
46 | 105 | return getAttributes().getAndUpdate(key, function); |
47 | 106 | } |
48 | 107 |
|
49 | | - @Deprecated(forRemoval = true, since = "0.2.0") |
50 | | - default <T> T getAndUpdateAttribute(@NotNull AttributeKey<T> key, @NotNull Function<@Nullable T, @Nullable T> function) { |
51 | | - return getAttributes().getAndUpdate(key, function); |
52 | | - } |
53 | | - |
54 | | - default <T> Optional<T> getAttibuteAsOptional(@NotNull AttributeKey<T> key) { |
55 | | - return getAttributes().getAsOptional(key); |
| 108 | + /** |
| 109 | + * Gets an attribute from a given attribute key, and applies a function to it before storing |
| 110 | + * the value returned by the function. |
| 111 | + * @param key attribute key |
| 112 | + * @param function function to apply to the previous value to obtain the new stored value |
| 113 | + * @return final stored value |
| 114 | + */ |
| 115 | + default <T> @Nullable T updateAttributeAndGet(@NotNull AttributeKey<T> key, @NotNull Function<@Nullable T, @Nullable T> function) { |
| 116 | + return getAttributes().updateAndGet(key, function); |
56 | 117 | } |
57 | 118 |
|
58 | | - @Deprecated(forRemoval = true, since = "0.2.0") |
59 | | - default <T> Optional<T> getAsOptional(@NotNull AttributeKey<T> key) { |
| 119 | + /** |
| 120 | + * Gets an attribute from a given attribute key as an optional. The optional will be empty |
| 121 | + * if the value is not stored. |
| 122 | + * @param key attribute key |
| 123 | + * @return optional with the stored value |
| 124 | + */ |
| 125 | + default <T> @NotNull Optional<T> getAttributeAsOptional(@NotNull AttributeKey<T> key) { |
60 | 126 | return getAttributes().getAsOptional(key); |
61 | 127 | } |
62 | 128 |
|
|
0 commit comments