git.basschouten.com Git - openhab-addons.git/blob

   1 /**
   2  * Copyright (c) 2010-2023 Contributors to the openHAB project
   3  *
   4  * See the NOTICE file(s) distributed with this work for additional
   5  * information.
   6  *
   7  * This program and the accompanying materials are made available under the
   8  * terms of the Eclipse Public License 2.0 which is available at
   9  * http://www.eclipse.org/legal/epl-2.0
  10  *
  11  * SPDX-License-Identifier: EPL-2.0
  12  */
  13 package org.openhab.binding.velux.internal.bridge.slip.utils;
  14
  15 import org.eclipse.jdt.annotation.NonNullByDefault;
  16 import org.openhab.binding.velux.internal.things.VeluxKLFAPI.Command;
  17 import org.openhab.binding.velux.internal.things.VeluxKLFAPI.CommandNumber;
  18 import org.slf4j.Logger;
  19
  20 /**
  21  * Utility class for handling of KLF200 response packets.
  22  *
  23  * <P>
  24  * Methods available:
  25  * <P>
  26  * Static methods are:
  27  * <UL>
  28  * <LI>{@link #introLogging} for logging used at the beginning of the response handling.</LI>
  29  * <LI>{@link #errorLogging} for error logging during processing.</LI>
  30  * <LI>{@link #outroLogging} logging used at the end of the response handling.</LI>
  31  * <LI>{@link #isLengthValid} for validation of length of the data part of the message.</LI>
  32  * <LI>{@link #check4matchingNodeID} for validation of node identifier.</LI>
  33  * <LI>{@link #check4matchingSessionID} for validation of session identifier.</LI>
  34  * </UL>
  35  *
  36  * @author Guenther Schreiner - Initial contribution.
  37  */
  38 @NonNullByDefault
  39 public class KLF200Response {
  40
  41     /**
  42      * Provides user-oriented logging in two log levels for monitoring KLF behavior.
  43      * <P>
  44      * Introduction logging used at the beginning of the response handling.
  45      *
  46      * @param logger Instantiated logging class to be used for output.
  47      * @param responseCommand The command byte of the response packet.
  48      * @param thisResponseData The array of bytes which are passed back within the response package.
  49      */
  50     public static void introLogging(Logger logger, short responseCommand, byte[] thisResponseData) {
  51         logger.debug("setResponse({} with {} bytes of data) called.", Command.get(responseCommand).toString(),
  52                 thisResponseData.length);
  53         logger.trace("setResponse(): handling response {} ({}).", Command.get(responseCommand).toString(),
  54                 new CommandNumber(responseCommand).toString());
  55     }
  56
  57     /**
  58      * Provides user-oriented logging in two log levels for monitoring KLF behavior.
  59      * <P>
  60      * Error logging used at the point where an unexpected or unrecognized command has been received.
  61      *
  62      * @param logger Instantiated logging class to be used for output.
  63      * @param responseCommand The command byte of the response packet.
  64      */
  65     public static void errorLogging(Logger logger, short responseCommand) {
  66         logger.trace("setResponse(): cannot handle response {} ({}).", Command.get(responseCommand).toString(),
  67                 new CommandNumber(responseCommand).toString());
  68         logger.debug("Gateway response {} ({}) cannot be handled at this point of interaction.",
  69                 Command.get(responseCommand).toString(), new CommandNumber(responseCommand).toString());
  70     }
  71
  72     /**
  73      * Provides user-oriented logging in two log levels for monitoring KLF behavior.
  74      * <P>
  75      * Conclusion logging used at the end of the response handling.
  76      *
  77      * @param logger Instantiated logging class to be used for output.
  78      * @param success Describes the success of the response processing.
  79      * @param finished Describes whether the response processing has come to an end.
  80      */
  81     public static void outroLogging(Logger logger, boolean success, boolean finished) {
  82         logger.trace("setResponse(): finished={},success={}.", finished, success);
  83     }
  84
  85     /**
  86      * Provides user-oriented logging in two log levels for monitoring KLF behavior.
  87      * <P>
  88      * Check the intended length of the response packet.
  89      *
  90      * @param logger Instantiated logging class to be used for output.
  91      * @param responseCommand The command byte of the response packet.
  92      * @param thisResponseData The array of bytes which are passed back within the response package.
  93      * @param requiredResponseDataLength The expected size of the array of bytes which are passed back within the
  94      *            response package.
  95      * @return <b>isLengthValid</b> of type boolean which signals the validity of the packet length.
  96      */
  97     public static boolean isLengthValid(Logger logger, short responseCommand, byte[] thisResponseData,
  98             int requiredResponseDataLength) {
  99         logger.trace("isLengthValid() called for {} ({}) with {} bytes of data.",
 100                 Command.get(responseCommand).toString(), new CommandNumber(responseCommand).toString(),
 101                 thisResponseData.length);
 102         if (thisResponseData.length != requiredResponseDataLength) {
 103             logger.warn(
 104                     "Gateway response {} ({}) consists of a malformed packet (effective length is {}, required length is {}).",
 105                     Command.get(responseCommand).toString(), new CommandNumber(responseCommand).toString(),
 106                     thisResponseData.length, requiredResponseDataLength);
 107             return false;
 108         }
 109         logger.trace("isLengthValid() returns {}.", true);
 110         return true;
 111     }
 112
 113     /**
 114      * Provides user-oriented logging in two log levels for monitoring KLF behavior.
 115      * <P>
 116      * Internal support method to match two values for equality.
 117      *
 118      * @param logger Instantiated logging class to be used for output.
 119      * @param idName String describing the type of values being compared.
 120      * @param requestID Value of type int have been replaced within the request.
 121      * @param responseID Value of type int being received within the response.
 122      * @return <b>check4matchingAnyID</b> of type boolean which signals the equality.
 123      */
 124     private static boolean check4matchingAnyID(Logger logger, String idName, int requestID, int responseID) {
 125         logger.trace("check4matchingAnyID() called for request {} {} and response {} {}.", idName, requestID, idName,
 126                 responseID);
 127         if (requestID != responseID) {
 128             logger.debug("Gateway query for {} {} received unexpected response of {} {}.", idName, requestID, idName,
 129                     responseID);
 130             return false;
 131         }
 132         logger.trace("check4matchingAnyID() returns {}.", true);
 133         return true;
 134     }
 135
 136     /**
 137      * Compare the node identifier of the request with the node identifier within the response
 138      * with user-oriented logging in two log levels for monitoring KLF behavior.
 139      *
 140      * @param logger Instantiated logging class to be used for output.
 141      * @param reqNodeID Node identifier of the request.
 142      * @param cfmNodeID Node identifier of the response.
 143      * @return <b>success</b> of type boolean which signals the success of the communication.
 144      */
 145     public static boolean check4matchingNodeID(Logger logger, int reqNodeID, int cfmNodeID) {
 146         logger.trace("check4matchingNodeID() called for request NodeID {} and response NodeID {}.", reqNodeID,
 147                 cfmNodeID);
 148         return check4matchingAnyID(logger, "NodeID", reqNodeID, cfmNodeID);
 149     }
 150
 151     /**
 152      * Compare the session identifier of the request with the session identifier within the response
 153      * with user-oriented logging in two log levels for monitoring KLF behavior.
 154      *
 155      * @param logger Instantiated logging class to be used for output.
 156      * @param reqSessionID Session identifier of the request.
 157      * @param cfmSessionID Session identifier of the response.
 158      * @return <b>success</b> of type boolean which signals the success of the communication.
 159      */
 160     public static boolean check4matchingSessionID(Logger logger, int reqSessionID, int cfmSessionID) {
 161         logger.trace("check4matchingSessionID() called for request SessionID {} and response SessionID {}.",
 162                 reqSessionID, cfmSessionID);
 163         return check4matchingAnyID(logger, "SessionID", reqSessionID, cfmSessionID);
 164     }
 165 }