javadoc

Author: burdoto

src/main/java/org/comroid/api/BitmaskAttribute.java

@@ -0,0 +1,121 @@
+package org.comroid.api;
+
+import org.comroid.util.Bitmask;
+import org.jetbrains.annotations.NotNull;
+
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.Set;
+
+/**
+ * Helper interface for enum classes that store an integer bitmask.
+ * <p>
+ * The default generated bitmasks are dependent on the order of constants.
+ *
+ * @param <S> The implementing Enum type
+ * @see #getValue() for further information
+ * @see Named Default Enum implementation
+ */
+public interface BitmaskAttribute<S extends BitmaskAttribute<S>> extends IntegerAttribute, SelfDeclared<S>, Named {
+    /**
+     * Computes a default integer value for this bitmask, depending on enum order.
+     * If implemented by an enum class, this method provides unique default bitmasks for every enum constant.
+     *
+     * @return The integer value of this Bitmask constant.
+     * @see IntegerAttribute#getValue() Returns Enums ordinal value if possible
+     */
+    @Override
+    @NotNull
+    default Integer getValue() {
+        return 1 << IntegerAttribute.super.getValue();
+    }
+
+    /**
+     * Creates a set of all mask attributes from an integer value and an enum class.
+     *
+     * @param mask    The integer value to scan
+     * @param viaEnum The enum to use all constants from.
+     * @param <T>     The enum type.
+     * @return A set of all Bitmask attributes set in the integer value
+     */
+    static <T extends java.lang.Enum<? extends T> & BitmaskAttribute<T>> Set<T> valueOf(int mask, Class<T> viaEnum) {
+        if (!viaEnum.isEnum())
+            throw new IllegalArgumentException("Only enums allowed as parameter 'viaEnum'");
+
+        return valueOf(mask, viaEnum.getEnumConstants());
+    }
+
+
+    /**
+     * Creates a set of all mask attributes from an integer value and an enum class.
+     *
+     * @param mask   The integer value to scan
+     * @param values All possible mask attributes
+     * @param <T>    The enum type.
+     * @return A set of all Bitmask attributes set in the integer value
+     */
+    static <T extends BitmaskAttribute<T>> Set<T> valueOf(int mask, T[] values) {
+        HashSet<T> yields = new HashSet<>();
+
+        for (T constant : values) {
+            if (constant.isFlagSet(mask))
+                yields.add(constant);
+        }
+
+        return Collections.unmodifiableSet(yields);
+    }
+
+    /**
+     * Creates an integer value containing all provided Bitmask attributes.
+     *
+     * @param values All values to combine
+     * @return The result integer value
+     */
+    static int toMask(BitmaskAttribute<?>[] values) {
+        int x = 0;
+        for (BitmaskAttribute<?> each : values)
+            x = each.apply(x, true);
+        return x;
+    }
+
+    /**
+     * Checks whether this Bitmask attribute contains another attribute.
+     *
+     * @param other The other attribute.
+     * @return Whether the other attribute is contained in this attribute
+     */
+    default boolean hasFlag(BitmaskAttribute<S> other) {
+        return Bitmask.isFlagSet(getValue(), other.getValue());
+    }
+
+    /**
+     * Checks whether this attribute is set within an integer mask.
+     *
+     * @param inMask The mask to check.
+     * @return Whether this attribute is contained in the mask
+     */
+    default boolean isFlagSet(int inMask) {
+        return Bitmask.isFlagSet(inMask, getValue());
+    }
+
+    /**
+     * Applies the {@code newState} of this attribute to the given mask, and returns the result.
+     *
+     * @param toMask   The mask to apply this attribute to
+     * @param newState The desired state of this attribute within the mask
+     * @return The new mask
+     */
+    default int apply(int toMask, boolean newState) {
+        return Bitmask.modifyFlag(toMask, getValue(), newState);
+    }
+
+    /**
+     * {@linkplain Object#equals(Object) Equals-implementation} to accept instances of BitmaskAttribute
+     *
+     * @param other The attribute to check against.
+     * @return Whether the attribute values are equal
+     */
+    default boolean equals(BitmaskAttribute<?> other) {
+        return getValue() == (int) other.getValue();
+    }
+}

src/main/java/org/comroid/api/BitmaskEnum.java

@@ -2,7 +2,17 @@
 
 import java.util.concurrent.CompletableFuture;
 
+/**
+ * A builder-like interface which returns a {@link CompletableFuture} to complete with the product, instead of the finished object.
+ *
+ * @param <T> The type of the result object
+ */
 public interface Composer<T> extends Provider<T> {
+    /**
+     * Starts computation for the creation of the object.
+     *
+     * @return A future to complete with the final object.
+     */
     CompletableFuture<T> compose();
 
     @Override

src/main/java/org/comroid/api/Composer.java

@@ -0,0 +1,76 @@
+package org.comroid.api;
+
+import org.comroid.util.StandardValueType;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * An attribute interface for objects that contains a plain integer value.
+ *
+ * @see Named
+ */
+public interface IntegerAttribute extends Named, ValueBox<Integer> {
+    /**
+     * Default implementation. If this is an instance of {@link Enum}, the {@linkplain Enum#ordinal() enum ordinal} is returned.
+     * Otherwise, an {@link AbstractMethodError} will be thrown.
+     *
+     * @return The integer value
+     * @throws AbstractMethodError If this is not an {@link Enum} instance
+     */
+    @Override
+    default @NotNull Integer getValue() throws AbstractMethodError {
+        if (this instanceof Enum)
+            return ((Enum<?>) this).ordinal();
+        throw new AbstractMethodError();
+    }
+
+    /**
+     * Default implementation to obtain the {@link StandardValueType#INTEGER default integer value type} for {@link ValueBox}.
+     *
+     * @return {@link StandardValueType#INTEGER}
+     */
+    @Override
+    default ValueType<? extends Integer> getHeldType() {
+        return StandardValueType.INTEGER;
+    }
+
+    /**
+     * Returns a {@link Rewrapper} supplying an instance of the corresponding attribute within the given enum class.
+     *
+     * @param value   The integer value
+     * @param viaEnum The enum the check it's attributes
+     * @param <T>     The enum type
+     * @return A Rewrapper that supplies the result attribute, or an empty rewrapper.
+     */
+    static <T extends java.lang.Enum<? extends T> & IntegerAttribute> Rewrapper<T> valueOf(int value, Class<T> viaEnum) {
+        if (!viaEnum.isEnum())
+            throw new IllegalArgumentException("Only enums allowed as parameter 'viaEnum'");
+
+        return valueOf(value, viaEnum.getEnumConstants());
+    }
+
+
+    /**
+     * Returns a {@link Rewrapper} supplying an instance of the corresponding attribute within the given enum class.
+     *
+     * @param value     The integer value
+     * @param constants All possible values
+     * @param <T>       The enum type
+     * @return A Rewrapper that supplies the result attribute, or an empty rewrapper.
+     */
+    static <T extends IntegerAttribute> Rewrapper<T> valueOf(int value, final T[] constants) {
+        for (T it : constants)
+            if (it.getValue() == value)
+                return () -> it;
+        return Rewrapper.empty();
+    }
+
+    /**
+     * An equals-implementation to accept int values.
+     *
+     * @param value The value to check
+     * @return Whether this objects value and the other value are equal.
+     */
+    default boolean equals(int value) {
+        return getValue() == value;
+    }
+}

src/main/java/org/comroid/api/IntEnum.java

@@ -1,19 +1,50 @@
 package org.comroid.api;
 
 public interface MutableState {
+    /**
+     * Checks whether this container object is currently allowed to change its value.
+     *
+     * @return whether this container object is currently allowed to change its value
+     */
     boolean isMutable();
 
+    /**
+     * Checks whether this container object is currently prohibited to change its value.
+     *
+     * @return whether this container object is currently prohibited to change its value.
+     */
     default boolean isImmutable() {
         return !isMutable();
     }
 
+    /**
+     * Attempts to change the mutability state of this container object.
+     * <p>
+     * If the return value is {@code true}, the new {@code state} could be applied.
+     * Returns {@code false} if otherwise.
+     *
+     * @param state The new mutability state
+     * @return Whether the new mutability state could be applied
+     */
     boolean setMutable(boolean state);
 
-    default boolean setMutable() {
-        return setMutable(true);
+    /**
+     * Attempts to allow mutation of this container object.
+     *
+     * @throws UnsupportedOperationException if this object could not be made mutable. May be caused by object already being mutable.
+     */
+    default void setMutable() throws UnsupportedOperationException {
+        if (!setMutable(true))
+            throw new UnsupportedOperationException("Could not make " + this + " mutable");
     }
 
-    default boolean setImmutable() {
-        return setMutable(false);
+    /**
+     * Attempts to disallow mutation of this container object.
+     *
+     * @throws UnsupportedOperationException if this object could not be made immutable. May be caused by object already being mutable.
+     */
+    default void setImmutable() {
+        if (!setMutable(false))
+            throw new UnsupportedOperationException("Could not make " + this + " immutable");
     }
 }