[surepetcare] renaming of a couple of methods and addition Javadoc do…

…cumentation

Signed-off-by: Rene Scherer <[email protected]>

bundles/org.openhab.binding.surepetcare/README.md

@@ -6,7 +6,7 @@ This binding offers integration to the Sure Petcare API, supporting cloud-connec
 
 1. Read access to all attributes for households, devices (hubs, flaps) and pets through individual things/channels.
 2. Manual setting of pet location.
-3. Setting of LED Mode (hub) and Locking Mode (flaps).
+3. Setting of LED Mode (hub), Locking Mode (flaps) and Curfews.
 
 ### Restrictions / TODO
 
@@ -82,9 +82,18 @@ Channel names in **bold** are read/write, everything else is read-only
 | id                    | Number   | A unique id assigned by the Sure Petcare API                                               |
 | name                  | Text     | The name of the flap                                                                       |
 | product               | Text     | The type of product (3=pet flap, 6=cat flap)                                               |
-| **curfewEnabled1**    | Switch   | Indicator if this curfew configuration is enabled                                          |
-| **curfewLockTime1**   | Text     | The curfew locking time (HH:MM)                                                            |
-| **curfewUnlockTime1** | Text     | The curfew unlocking time (HH:MM)                                                          |
+| **curfewEnabled1**    | Switch   | Indicator if curfew #1 configuration is enabled                                            |
+| **curfewLockTime1**   | Text     | The curfew #1 locking time (HH:MM)                                                         |
+| **curfewUnlockTime1** | Text     | The curfew #1 unlocking time (HH:MM)                                                       |
+| **curfewEnabled2**    | Switch   | Indicator if curfew #2 configuration is enabled                                            |
+| **curfewLockTime2**   | Text     | The curfew #2 locking time (HH:MM)                                                         |
+| **curfewUnlockTime2** | Text     | The curfew #2 unlocking time (HH:MM)                                                       |
+| **curfewEnabled3**    | Switch   | Indicator if curfew #3 configuration is enabled                                            |
+| **curfewLockTime3**   | Text     | The curfew #3 locking time (HH:MM)                                                         |
+| **curfewUnlockTime3** | Text     | The curfew #3 unlocking time (HH:MM)                                                       |
+| **curfewEnabled4**    | Switch   | Indicator if curfew #4 configuration is enabled                                            |
+| **curfewLockTime4**   | Text     | The curfew #4 locking time (HH:MM)                                                         |
+| **curfewUnlockTime4** | Text     | The curfew #4 unlocking time (HH:MM)                                                       |
 | hardwareVersion       | Text     | The flap's hardware version number                                                         |
 | **lockingMode**       | Text     | The locking mode (e.g. in/out, in-only, out-only etc.)                                     |
 | hardwareVersion       | Number   | The flap's hardware version number                                                         |

bundles/org.openhab.binding.surepetcare/src/main/java/org/openhab/binding/surepetcare/internal/SurePetcareAPIHelper.java

@@ -51,7 +51,8 @@
 import com.google.gson.JsonSyntaxException;
 
 /**
- * Helper class to retrieve Sure Petcare data from the API.
+ * The {@link SurePetcareAPIHelper} is a helper class to abstract the Sure Petcare API. It handles authentication and
+ * all JSON API calls. If an API call fails it automatically refreshes the authentication token and retries.
  *
  * @author Rene Scherer - Initial contribution
  */
@@ -83,8 +84,15 @@ public class SurePetcareAPIHelper {
 
     private SurePetcareTopology topologyCache = new SurePetcareTopology();
 
-    public synchronized void login(String username, String password)
-            throws JsonSyntaxException, AuthenticationException {
+    /**
+     * This method uses the provided username and password to obtain an authentication token used for subsequent API
+     * calls.
+     *
+     * @param username The Sure Petcare username (email address) to be used
+     * @param password The password
+     * @throws AuthenticationException
+     */
+    public synchronized void login(String username, String password) throws AuthenticationException {
         try {
             URL object = new URL(LOGIN_URL);
             HttpURLConnection con = (HttpURLConnection) object.openConnection();
@@ -126,6 +134,10 @@ public synchronized void login(String username, String password)
         }
     }
 
+    /**
+     * Refreshes the whole topology, i.e. all devices, pets etc. through a call to the Sure Petcare API. The APi call is
+     * quite resource intensive and should be used very infrequently.
+     */
     public synchronized void updateTopologyCache() {
         try {
             topologyCache = gson.fromJson(getDataFromApi(TOPOLOGY_URL), SurePetcareTopology.class);
@@ -134,6 +146,10 @@ public synchronized void updateTopologyCache() {
         }
     }
 
+    /**
+     * Refreshes only the pet status (location activity and feeding information). This API call can be used more
+     * frequently.
+     */
     public synchronized void updatePetStatus() {
         try {
             for (SurePetcarePet pet : topologyCache.getPets()) {
@@ -145,27 +161,62 @@ public synchronized void updatePetStatus() {
         }
     }
 
-    public final SurePetcareTopology retrieveTopology() {
+    /**
+     * Returns the whole topology.
+     *
+     * @return the topology
+     */
+    public final SurePetcareTopology getTopology() {
         return topologyCache;
     }
 
-    public final @Nullable SurePetcareHousehold retrieveHousehold(String id) {
+    /**
+     * Returns a household object if one exists with the given id, otherwise null.
+     *
+     * @param id the household id
+     * @return the household with the given id
+     */
+    public final @Nullable SurePetcareHousehold getHousehold(String id) {
         return topologyCache.getHouseholdById(id);
     }
 
-    public final @Nullable SurePetcareDevice retrieveDevice(String id) {
+    /**
+     * Returns a device object if one exists with the given id, otherwise null.
+     *
+     * @param id the device id
+     * @return the device with the given id
+     */
+    public final @Nullable SurePetcareDevice getDevice(String id) {
         return topologyCache.getDeviceById(id);
     }
 
-    public final @Nullable SurePetcarePet retrievePet(String id) {
+    /**
+     * Returns a pet object if one exists with the given id, otherwise null.
+     *
+     * @param id the pet id
+     * @return the pet with the given id
+     */
+    public final @Nullable SurePetcarePet getPet(String id) {
         return topologyCache.getPetById(id);
     }
 
-    public final @Nullable SurePetcareTag retrieveTag(String id) {
+    /**
+     * Returns a tag object if one exists with the given id, otherwise null.
+     *
+     * @param id the tag id
+     * @return the tag with the given id
+     */
+    public final @Nullable SurePetcareTag getTag(String id) {
         return topologyCache.getTagById(id);
     }
 
-    public final @Nullable SurePetcarePetLocation retrievePetLocation(String id) {
+    /**
+     * Returns the location object if a pet exists with the given id, otherwise null.
+     *
+     * @param id the pet id
+     * @return the location of the pet with the given id
+     */
+    public final @Nullable SurePetcarePetLocation getPetLocation(String id) {
         SurePetcarePet pet = topologyCache.getPetById(id);
         if (pet != null) {
             return pet.getLocation();
@@ -174,7 +225,13 @@ public final SurePetcareTopology retrieveTopology() {
         }
     }
 
-    public final @Nullable SurePetcarePetStatus retrievePetStatus(String id) {
+    /**
+     * Returns the status object if a pet exists with the given id, otherwise null.
+     *
+     * @param id the pet id
+     * @return the status of the pet with the given id
+     */
+    public final @Nullable SurePetcarePetStatus getPetStatus(String id) {
         SurePetcarePet pet = topologyCache.getPetById(id);
         if (pet != null) {
             return pet.getPetStatus();
@@ -183,6 +240,13 @@ public final SurePetcareTopology retrieveTopology() {
         }
     }
 
+    /**
+     * Updates the pet location through an API call to the Sure Petcare API.
+     *
+     * @param pet the pet
+     * @param newLocationId the id of the new location
+     * @throws SurePetcareApiException
+     */
     public synchronized void setPetLocation(SurePetcarePet pet, Integer newLocationId) throws SurePetcareApiException {
         pet.getLocation().setPetId(pet.getId());
         pet.getLocation().setWhere(newLocationId);
@@ -191,6 +255,13 @@ public synchronized void setPetLocation(SurePetcarePet pet, Integer newLocationI
         setDataThroughApi(url, HTTP_REQUEST_METHOD_POST, pet.getLocation());
     }
 
+    /**
+     * Updates the device locking mode through an API call to the Sure Petcare API.
+     *
+     * @param device the device
+     * @param newLockingModeId the id of the new locking mode
+     * @throws SurePetcareApiException
+     */
     public synchronized void setDeviceLockingMode(SurePetcareDevice device, Integer newLockingModeId)
             throws SurePetcareApiException {
         // post new JSON control structure to API
@@ -205,6 +276,13 @@ public synchronized void setDeviceLockingMode(SurePetcareDevice device, Integer
         device.getStatus().assign(newStatus);
     }
 
+    /**
+     * Updates the device led mode through an API call to the Sure Petcare API.
+     *
+     * @param device the device
+     * @param newLedModeId the id of the new led mode
+     * @throws SurePetcareApiException
+     */
     public synchronized void setDeviceLedMode(SurePetcareDevice device, Integer newLedModeId)
             throws SurePetcareApiException {
         // post new JSON control structure to API
@@ -219,6 +297,13 @@ public synchronized void setDeviceLedMode(SurePetcareDevice device, Integer newL
         device.getStatus().assign(newStatus);
     }
 
+    /**
+     * Updates all curfews through an API call to the Sure Petcare API.
+     *
+     * @param device the device
+     * @param curfewList the list of curfews
+     * @throws SurePetcareApiException
+     */
     public void setCurfews(SurePetcareDevice device, SurePetcareDeviceCurfewList curfewList)
             throws SurePetcareApiException {
         // post new JSON control structure to API
@@ -234,10 +319,19 @@ public void setCurfews(SurePetcareDevice device, SurePetcareDeviceCurfewList cur
         device.setControl(newControl);
     }
 
+    /**
+     * @return true, if the API is connected and successfully authenticated.
+     */
     public final boolean isOnline() {
         return online;
     }
 
+    /**
+     * Returns a unique device id used during the authentication process with the Sure Petcare API. The id is derived
+     * from the local MAC address or hostname.
+     *
+     * @return a unique device id
+     */
     public final Integer getDeviceId() {
         int decimal = 0;
         try {
@@ -271,6 +365,12 @@ public final Integer getDeviceId() {
         return decimal;
     }
 
+    /**
+     * Sets a set of required HTTP headers for the JSON API calls.
+     *
+     * @param con the HTTP connection
+     * @throws ProtocolException
+     */
     private void setConnectionHeaders(HttpURLConnection con) throws ProtocolException {
         // headers
         con.setRequestProperty("Connection", "keep-alive");
@@ -300,17 +400,25 @@ private JsonElement getDataFromApi(String url) throws SurePetcareApiException {
     }
 
     /**
-     * Return the "data" element of the API result as a JsonElement.
+     * Sends a given object as a JSON payload to the API.
      *
-     * @param url The URL of the API call.
-     * @return The "data" element of the API result.
+     * @param url the URL
+     * @param requestMethod the request method (POST, PUT etc.)
+     * @param payload an object used for the payload
      * @throws SurePetcareApiException
      */
     private void setDataThroughApi(String url, String requestMethod, Object payload) throws SurePetcareApiException {
         String jsonPayload = gson.toJson(payload);
         postDataThroughAPI(url, requestMethod, jsonPayload);
     }
 
+    /**
+     * Returns the result of a GET API call as a string.
+     *
+     * @param url the URL
+     * @return a JSON string with the API result
+     * @throws SurePetcareApiException
+     */
     private String getResultFromApi(String url) throws SurePetcareApiException {
         boolean success = false;
         String responseData = "";
@@ -353,6 +461,14 @@ private String getResultFromApi(String url) throws SurePetcareApiException {
         return responseData;
     }
 
+    /**
+     * Uses the given request method to send a JSON string to an API.
+     *
+     * @param url the URL
+     * @param requestMethod the required request method (POST, PUT etc.)
+     * @param jsonPayload the JSON string
+     * @throws SurePetcareApiException
+     */
     private void postDataThroughAPI(String url, String requestMethod, String jsonPayload)
             throws SurePetcareApiException {
         boolean success = false;

bundles/org.openhab.binding.surepetcare/src/main/java/org/openhab/binding/surepetcare/internal/SurePetcareHandlerFactory.java

@@ -62,11 +62,17 @@ public class SurePetcareHandlerFactory extends BaseThingHandlerFactory {
             .of(BRIDGE_THING_TYPES_UIDS, SurePetcareConstants.SUPPORTED_THING_TYPES_UIDS).flatMap(x -> x.stream())
             .collect(Collectors.toSet());
 
+    /**
+     * Returns true if the factory supports the given thing type.
+     */
     @Override
     public boolean supportsThingType(ThingTypeUID thingTypeUID) {
         return SUPPORTED_THING_TYPES_UIDS.contains(thingTypeUID);
     }
 
+    /**
+     * Returns a newly created thing handler for the given thing.
+     */
     @Override
     protected @Nullable ThingHandler createHandler(Thing thing) {
         logger.debug("createHandler - create handler for {}", thing.toString());
@@ -90,6 +96,9 @@ public boolean supportsThingType(ThingTypeUID thingTypeUID) {
         return null;
     }
 
+    /**
+     * Removed the thing handler.
+     */
     @Override
     protected void removeHandler(ThingHandler thingHandler) {
         if (thingHandler instanceof SurePetcareBridgeHandler) {

bundles/org.openhab.binding.surepetcare/src/main/java/org/openhab/binding/surepetcare/internal/data/SurePetcareDeviceCurfewList.java

@@ -14,6 +14,8 @@
 
 import java.util.ArrayList;
 
+import org.openhab.binding.surepetcare.internal.SurePetcareConstants;
+
 /**
  * The {@link SurePetcareDeviceCurfewList} class is used to serialize a list of curfew parameters.
  *
@@ -51,9 +53,9 @@ public String toString() {
     }
 
     /**
-     * Creates a list of 4 curfews with enabled ones at the front of the list and disabled ones at the back.
+     * Creates a list of curfews with enabled ones at the front of the list and disabled ones at the back.
      *
-     * @return new ordered list
+     * @return new ordered list.
      */
     public SurePetcareDeviceCurfewList order() {
         SurePetcareDeviceCurfewList orderedList = new SurePetcareDeviceCurfewList();
@@ -63,12 +65,17 @@ public SurePetcareDeviceCurfewList order() {
                 orderedList.add(curfew);
             }
         }
-        for (int i = orderedList.size(); i < 4; i++) {
+        for (int i = orderedList.size(); i < SurePetcareConstants.FLAP_MAX_NUMBER_OF_CURFEWS; i++) {
             orderedList.add(new SurePetcareDeviceCurfew());
         }
         return orderedList;
     }
 
+    /**
+     * Trims the list of curfews and removes any disabled ones.
+     *
+     * @return the new compact list of curfews.
+     */
     public SurePetcareDeviceCurfewList compact() {
         SurePetcareDeviceCurfewList compactList = new SurePetcareDeviceCurfewList();
         // remove any disabled curfews from the list

bundles/org.openhab.binding.surepetcare/src/main/java/org/openhab/binding/surepetcare/internal/discovery/SurePetcareDiscoveryService.java

@@ -119,7 +119,7 @@ private void retrieveTopologyFromSurePetcare() {
         while (retryCount-- > 0) {
             if (petcareAPI.isOnline()) {
                 logger.debug("I'm discovering the Sure Petcare topology ...");
-                SurePetcareTopology topology = petcareAPI.retrieveTopology();
+                SurePetcareTopology topology = petcareAPI.getTopology();
                 for (SurePetcareHousehold household : topology.getHouseholds()) {
                     logger.debug("Found new household thing: {}", household.toString());
                     createHouseholdThing(household);

bundles/org.openhab.binding.surepetcare/src/main/java/org/openhab/binding/surepetcare/internal/handler/SurePetcareBaseObjectHandler.java

@@ -55,6 +55,9 @@ public void handleCommand(ChannelUID channelUID, Command command) {
         }
     }
 
-    public abstract void updateThing();
+    /**
+     * Updates all channels of a thing.
+     */
+    protected abstract void updateThing();
 
 }

bundles/org.openhab.binding.surepetcare/src/main/java/org/openhab/binding/surepetcare/internal/handler/SurePetcareBridgeHandler.java

@@ -154,7 +154,7 @@ public void handleCommand(ChannelUID channelUID, Command command) {
         }
     }
 
-    private synchronized void updateThings() {
+    protected synchronized void updateThings() {
         logger.debug("Updating {} connected things", ((Bridge) thing).getThings().size());
         // update existing things
         for (Thing th : ((Bridge) thing).getThings()) {