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.json;
  14
  15 import org.eclipse.jdt.annotation.NonNullByDefault;
  16 import org.openhab.binding.velux.internal.bridge.common.BridgeCommunicationProtocol;
  17
  18 /**
  19  * <B>Common JSON-based bridge communication message scheme supported by the </B><I>Velux</I><B> bridge.</B>
  20  * <P>
  21  * This bridge communication is an extension of the common
  22  * {@link org.openhab.binding.velux.internal.bridge.common.BridgeCommunicationProtocol BridgeCommunicationProtocol}.
  23  * <P>
  24  * Message semantic will be defined by the implementation of the separate message classes,
  25  * which are defined within {@link org.openhab.binding.velux.internal.bridge.json.JsonBridgeAPI JsonBridgeAPI}.
  26  * <P>
  27  * The implementations will define the information which to send query and receive answer
  28  * through the
  29  * {@link org.openhab.binding.velux.internal.bridge.VeluxBridgeProvider VeluxBridgeProvider}.
  30  * <P>
  31  * (Methods in this interface for the appropriate interaction:
  32  * <UL>
  33  * <LI>{@link #getURL} to return the URL suffix for accessing the specific service access point.</LI>
  34  * <LI>{@link #getObjectOfRequest} to return the request object for further JSON serialization.</LI>
  35  * <LI>{@link #getClassOfResponse} to retrieve the class of the object of response message for further JSON
  36  * deserialization.</LI>
  37  * <LI>{@link #setResponse} for storing the response according to the desired class after JSON deserialization.</LI>
  38  * <LI>{@link #getDeviceStatus} to retrieve the current device status.</LI>
  39  * <LI>{@link #getErrors} to retrieve the current error status.</LI>
  40  * </UL>
  41  *
  42  *
  43  * @author Guenther Schreiner - Initial contribution.
  44  */
  45 @NonNullByDefault
  46 interface JsonBridgeCommunicationProtocol extends BridgeCommunicationProtocol {
  47
  48     /**
  49      * Returning the URL suffix for accessing the specific service access point.
  50      *
  51      * @return <b>sapURL</b>
  52      *         as String which is to be combined with the bridge address.
  53      */
  54     String getURL();
  55
  56     /**
  57      * Returning the request object for further JSON serialization.
  58      *
  59      * @return <b>ObjectOfRequest</b>
  60      *         is an Object.
  61      */
  62     Object getObjectOfRequest();
  63
  64     /**
  65      * Returning the class of the object of response message for further JSON deserialization.
  66      *
  67      * @return <b>ClassOfResponseObject</b>
  68      *         is the appropriate class Object.
  69      */
  70     Class<?> getClassOfResponse();
  71
  72     /**
  73      * Storing the response according to the desired class after JSON deserialization.
  74      *
  75      * @param response is the appropriate object of previously given class Object.
  76      */
  77     void setResponse(Object response);
  78
  79     /**
  80      * Returning the communication status included within the response message.
  81      *
  82      * @return <b>deviceStatus</b> as String describing the current status of the bridge.
  83      */
  84     String getDeviceStatus();
  85
  86     /**
  87      * Returning the communication status included within the response message.
  88      *
  89      * @return <b>errors</b> as String[] describing the status of the operation according to the request in depth.
  90      */
  91     String[] getErrors();
  92 }