add name, active and fault interfaces

Author: yfre

src/main/java/io/github/hapjava/accessories/LockMechanismAccessory.java

@@ -34,6 +34,7 @@ public interface LockMechanismAccessory extends HomekitAccessory {
    * set lock target state the lock trget state.
    *
    * @param state lock target state
+   * @return a future that completes when the change is made
    */
   CompletableFuture<Void> setLockTargetState(LockTargetStateEnum state);
 

src/main/java/io/github/hapjava/accessories/optionalcharacteristic/AccessoryWithDuration.java

@@ -11,28 +11,24 @@
 public interface AccessoryWithDuration {
 
   /**
-   * Retrieves the current set duration for which the valve will be scheduled to run; this is
-   * usually used as the duration to use when the valve is set to active.
+   * Retrieves the current set duration;
    *
    * @return a future with the value
    */
   CompletableFuture<Integer> getSetDuration();
 
   /**
-   * Sets the duration for which the valve will be scheduled to run; this is usually used as the
-   * duration to use when the valve is set to active.
+   * Sets the duration for which the service should run.
    *
-   * <p>If the valve is currently running, then Homekit assumes that changing this value affects the
-   * current remaining duration.
-   *
-   * @return a future with the value
+   * @param value duration in seconds
+   * @return a future that completes when the change is made
    */
   CompletableFuture<Void> setSetDuration(int value);
 
   /**
    * Subscribes to changes in the set duration
    *
-   * @param callback the function when the value has changed
+   * @param callback the function when the duration has changed
    */
   void subscribeSetDuration(HomekitCharacteristicChangeCallback callback);
 

src/main/java/io/github/hapjava/accessories/optionalcharacteristic/AccessoryWithFanState.java

@@ -16,37 +16,39 @@
 public interface AccessoryWithFanState {
 
   /**
-   * OPTIONAL: Retrieves the current state of the fan (INACTIVE, IDLE, BLOWING AIR).
+   * Retrieves the current state of the fan (INACTIVE, IDLE, BLOWING AIR).
    *
    * @return a future that will contain the state
    */
   CompletableFuture<CurrentFanStateEnum> getCurrentFanState();
 
   /**
-   * OPTIONAL: Retrieves the target state of the fan (MANUAL, AUTO).
+   * Retrieves the target state of the fan (MANUAL, AUTO).
    *
    * @return a future that will contain the state
    */
   CompletableFuture<TargetFanStateEnum> getTargetFanState();
 
   /**
-   * OPTIONAL: Set the target state of the fan (MANUAL, AUTO).
+   * Set the target state of the fan (MANUAL, AUTO).
    *
    * @param targetState target state
+   * @return a future that completes when the change is made
    */
   CompletableFuture<Void> setTargetFanState(TargetFanStateEnum targetState);
 
   /**
-   * OPTIONAL: Retrieves the swing mode of the fan.
+   * Retrieves the swing mode of the fan.
    *
    * @return a future that will contain the swing mode
    */
   CompletableFuture<SwingModeEnum> getSwingMode();
 
   /**
-   * OPTIONAL: Set the swing mode of the fan (DISABLED, ENABLED).
+   * Set the swing mode of the fan (DISABLED, ENABLED).
    *
    * @param swingMode swing mode
+   * @return a future that completes when the change is made
    */
   CompletableFuture<Void> setSwingMode(SwingModeEnum swingMode);
 
@@ -58,28 +60,29 @@ public interface AccessoryWithFanState {
   CompletableFuture<LockPhysicalControlsEnum> getLockControls();
 
   /**
-   * OPTIONAL: Set the lock controls of the fan (DISABLED, ENABLED).
+   * Set the lock controls of the fan (DISABLED, ENABLED).
    *
    * @param lockControls lock controls mode
+   * @return a future that completes when the change is made
    */
   CompletableFuture<Void> setLockControls(LockPhysicalControlsEnum lockControls);
 
   /**
-   * OPTIONAL: Retrieves the current rotation direction of the fan.
+   * Retrieves the current rotation direction of the fan.
    *
    * @return a future that will contain the direction
    */
   CompletableFuture<RotationDirectionEnum> getRotationDirection();
 
   /**
-   * OPTIONAL: Retrieves the current speed of the fan's rotation
+   * Retrieves the current speed of the fan's rotation
    *
    * @return a future that will contain the speed, expressed as an integer between 0 and 100.
    */
   CompletableFuture<Integer> getRotationSpeed();
 
   /**
-   * OPTIONAL: Sets the rotation direction of the fan
+   * Sets the rotation direction of the fan
    *
    * @param direction the direction to set
    * @return a future that completes when the change is made
@@ -97,62 +100,62 @@ public interface AccessoryWithFanState {
   CompletableFuture<Void> setRotationSpeed(Integer speed) throws Exception;
 
   /**
-   * OPTIONAL: Subscribes to changes in the rotation direction of the fan.
+   * Subscribes to changes in the rotation direction of the fan.
    *
    * @param callback the function to call when the direction changes.
    */
   void subscribeRotationDirection(HomekitCharacteristicChangeCallback callback);
 
   /**
-   * OPTIONAL: Subscribes to changes in the current fan state.
+   * Subscribes to changes in the current fan state.
    *
    * @param callback the function to call when the direction changes.
    */
   void subscribeCurrentFanState(HomekitCharacteristicChangeCallback callback);
 
   /**
-   * OPTIONAL: Subscribes to changes in the target fan state.
+   * Subscribes to changes in the target fan state.
    *
    * @param callback the function to call when the direction changes.
    */
   void subscribeTargetFanState(HomekitCharacteristicChangeCallback callback);
 
   /**
-   * OPTIONAL: Subscribes to changes in the rotation speed of the fan.
+   * Subscribes to changes in the rotation speed of the fan.
    *
    * @param callback the function to call when the speed changes.
    */
   void subscribeRotationSpeed(HomekitCharacteristicChangeCallback callback);
 
   /**
-   * OPTIONAL: Subscribes to changes in the swing mode of the fan.
+   * Subscribes to changes in the swing mode of the fan.
    *
    * @param callback the function to call when the swing mode changes.
    */
   void subscribeSwingMode(HomekitCharacteristicChangeCallback callback);
 
   /**
-   * OPTIONAL: Subscribes to changes in the lock controls of the fan.
+   * Subscribes to changes in the lock controls of the fan.
    *
    * @param callback the function to call when the lock controls changes.
    */
   void subscribeLockControls(HomekitCharacteristicChangeCallback callback);
 
-  /** OPTIONAL: Unsubscribes from changes in the rotation direction of the fan. */
+  /** Unsubscribes from changes in the rotation direction of the fan. */
   void unsubscribeRotationDirection();
 
-  /** OPTIONAL: Unsubscribes from changes in the fan's rotation speed. */
+  /** Unsubscribes from changes in the fan's rotation speed. */
   void unsubscribeRotationSpeed();
 
-  /** OPTIONAL: Unsubscribes from changes in the current state of the fan. */
+  /** Unsubscribes from changes in the current state of the fan. */
   void unsubscribeCurrentFanState();
 
-  /** OPTIONAL: Unsubscribes from changes in the target state of the fan. */
+  /** Unsubscribes from changes in the target state of the fan. */
   void unsubscribeTargetFanState();
 
-  /** OPTIONAL: Unsubscribes from changes in the swing mode of the fan. */
+  /** Unsubscribes from changes in the swing mode of the fan. */
   void unsubscribeSwingMode();
 
-  /** OPTIONAL: Unsubscribes from changes in the lock controls of the fan. */
+  /** Unsubscribes from changes in the lock controls of the fan. */
   void unsubscribeLockControls();
 }

src/main/java/io/github/hapjava/accessories/optionalcharacteristic/AccessoryWithName.java

@@ -0,0 +1,18 @@
+package io.github.hapjava.accessories.optionalcharacteristic;
+
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * Accessory with name.
+ *
+ * @author Eugen Freiter
+ */
+public interface AccessoryWithName {
+
+  /**
+   * Retrieves the name of service.
+   *
+   * @return a future with the name
+   */
+  CompletableFuture<String> getName();
+}

src/main/java/io/github/hapjava/accessories/optionalcharacteristic/AccessoryWithRemainingDuration.java

@@ -11,15 +11,15 @@
 public interface AccessoryWithRemainingDuration {
 
   /**
-   * Retrieves the current duration for which the valve will run
+   * Retrieves the remaining duration
    *
-   * @return a future with the value
+   * @return a future with the duration in seconds
    */
   CompletableFuture<Integer> getRemainingDuration();
 
   /**
    * Subscribes to changes in the duration; note it is not necessary to emit a change every second,
-   * homekit infers the countdown progress clientside.
+   * homekit infers the countdown progress client side.
    *
    * @param callback the function when the existing duration has been replaced with a new one.
    */

src/main/java/io/github/hapjava/accessories/optionalcharacteristic/AccessoryWithStatusActive.java

@@ -0,0 +1,30 @@
+package io.github.hapjava.accessories.optionalcharacteristic;
+
+import io.github.hapjava.characteristics.HomekitCharacteristicChangeCallback;
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * Accessory with status active.
+ *
+ * @author Eugen Freiter
+ */
+public interface AccessoryWithStatusActive {
+
+  /**
+   * Retrieves the status active. A value of true indicates that the accessory is active and is
+   * functioning without any errors.
+   *
+   * @return a future with the value
+   */
+  CompletableFuture<Boolean> getStatusActive();
+
+  /**
+   * Subscribes to changes in status active.
+   *
+   * @param callback the function when the status active changes
+   */
+  void subscribeStatusActive(HomekitCharacteristicChangeCallback callback);
+
+  /** Unsubscribes from changes */
+  void unsubscribeStatusActive();
+}

src/main/java/io/github/hapjava/accessories/optionalcharacteristic/AccessoryWithStatusFault.java

@@ -0,0 +1,34 @@
+package io.github.hapjava.accessories.optionalcharacteristic;
+
+import io.github.hapjava.characteristics.HomekitCharacteristicChangeCallback;
+import io.github.hapjava.characteristics.impl.common.StatusFaultEnum;
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * Accessory with characteristic that describes an accessory which has a fault. A non-zero value
+ * indicates that the accessory has experienced a fault that may be interfering with its intended
+ * functionality. A value of 0 indicates that there is no fault.
+ *
+ * @author Eugen Freiter
+ */
+public interface AccessoryWithStatusFault {
+
+  /**
+   * Retrieves the status fault. A non-zero value indicates that the accessory has experienced a
+   * fault that may be interfering with its intended functionality. A value of 0 indicates that
+   * there is no fault.
+   *
+   * @return a future with the value
+   */
+  CompletableFuture<StatusFaultEnum> getStatusFault();
+
+  /**
+   * Subscribes to changes in status fault.
+   *
+   * @param callback the function when the status fault changes
+   */
+  void subscribeStatusFault(HomekitCharacteristicChangeCallback callback);
+
+  /** Unsubscribes from changes */
+  void unsubscribeStatusFault();
+}

src/main/java/io/github/hapjava/characteristics/impl/accessoryinformation/IdentifyCharacteristic.java

@@ -1,7 +1,7 @@
 package io.github.hapjava.characteristics.impl.accessoryinformation;
 
-import io.github.hapjava.characteristics.impl.base.BooleanCharacteristic;
 import io.github.hapjava.characteristics.ExceptionalConsumer;
+import io.github.hapjava.characteristics.impl.base.BooleanCharacteristic;
 import java.util.Optional;
 
 /** This characteristic enables accessory to run its identify routine. */

src/main/java/io/github/hapjava/characteristics/impl/base/BaseCharacteristic.java

@@ -1,5 +1,8 @@
 package io.github.hapjava.characteristics.impl.base;
 
+import io.github.hapjava.characteristics.Characteristic;
+import io.github.hapjava.characteristics.EventableCharacteristic;
+import io.github.hapjava.characteristics.HomekitCharacteristicChangeCallback;
 import java.math.BigDecimal;
 import java.math.BigInteger;
 import java.util.Optional;
@@ -13,9 +16,6 @@
 import javax.json.JsonValue;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
-import io.github.hapjava.characteristics.Characteristic;
-import io.github.hapjava.characteristics.EventableCharacteristic;
-import io.github.hapjava.characteristics.HomekitCharacteristicChangeCallback;
 
 /**
  * Base class for implementing {@link Characteristic}.

src/main/java/io/github/hapjava/characteristics/impl/base/BooleanCharacteristic.java

@@ -1,14 +1,14 @@
 package io.github.hapjava.characteristics.impl.base;
 
+import io.github.hapjava.characteristics.ExceptionalConsumer;
+import io.github.hapjava.characteristics.HomekitCharacteristicChangeCallback;
 import java.util.Optional;
 import java.util.concurrent.CompletableFuture;
 import java.util.function.Consumer;
 import java.util.function.Supplier;
 import javax.json.JsonNumber;
 import javax.json.JsonValue;
 import javax.json.JsonValue.ValueType;
-import io.github.hapjava.characteristics.ExceptionalConsumer;
-import io.github.hapjava.characteristics.HomekitCharacteristicChangeCallback;
 
 /**
  * Characteristic that exposes a Boolean value.
@@ -26,6 +26,10 @@ public abstract class BooleanCharacteristic extends BaseCharacteristic<Boolean>
    * @param type a string containing a UUID that indicates the type of characteristic. Apple defines
    *     a set of these, however implementors can create their own as well.
    * @param description a description of the characteristic to be passed to the consuming device.
+   * @param getter getter to retrieve the value
+   * @param setter setter to set value
+   * @param subscriber subscriber to subscribe to changes
+   * @param unsubscriber unsubscriber to unsubscribe from chnages
    */
   public BooleanCharacteristic(
       String type,