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.russound.internal.rio;
  14
  15 import java.io.IOException;
  16
  17 import org.openhab.binding.russound.internal.net.SocketSession;
  18 import org.openhab.binding.russound.internal.net.SocketSessionListener;
  19 import org.openhab.binding.russound.internal.rio.system.RioSystemHandler;
  20 import org.openhab.core.thing.ThingStatus;
  21 import org.openhab.core.thing.ThingStatusDetail;
  22 import org.openhab.core.types.State;
  23
  24 /**
  25  * Defines the abstract base for a protocol handler. This base provides managment of the {@link SocketSession} and
  26  * provides helper methods that will callback {@link RioHandlerCallback}
  27  *
  28  * @author Tim Roberts - Initial contribution
  29  */
  30 public abstract class AbstractRioProtocol implements SocketSessionListener {
  31     /**
  32      * The {@link SocketSession} used by this protocol handler
  33      */
  34     private final SocketSession session;
  35
  36     /**
  37      * The {@link RioSystemHandler} to call back to update status and state
  38      */
  39     private final RioHandlerCallback callback;
  40
  41     /**
  42      * Constructs the protocol handler from given parameters and will add this handler as a
  43      * {@link SocketSessionListener} to the specified {@link SocketSession} via
  44      * {@link SocketSession#addListener(SocketSessionListener)}
  45      *
  46      * @param session a non-null {@link SocketSession} (may be connected or disconnected)
  47      * @param callback a non-null {@link RioHandlerCallback} to update state and status
  48      */
  49     protected AbstractRioProtocol(SocketSession session, RioHandlerCallback callback) {
  50         if (session == null) {
  51             throw new IllegalArgumentException("session cannot be null");
  52         }
  53
  54         if (callback == null) {
  55             throw new IllegalArgumentException("callback cannot be null");
  56         }
  57
  58         this.session = session;
  59         this.session.addListener(this);
  60         this.callback = callback;
  61     }
  62
  63     /**
  64      * Sends the command and puts the thing into {@link ThingStatus#OFFLINE} if an IOException occurs
  65      *
  66      * @param command a non-null, non-empty command to send
  67      */
  68     protected void sendCommand(String command) {
  69         if (command == null) {
  70             throw new IllegalArgumentException("command cannot be null");
  71         }
  72         try {
  73             session.sendCommand(command);
  74         } catch (IOException e) {
  75             getCallback().statusChanged(ThingStatus.OFFLINE, ThingStatusDetail.COMMUNICATION_ERROR,
  76                     "Exception occurred sending command: " + e);
  77         }
  78     }
  79
  80     /**
  81      * Updates the state via the {@link RioHandlerCallback#stateChanged(String, State)}
  82      *
  83      * @param channelId the channel id to update state
  84      * @param newState the new state
  85      */
  86     protected void stateChanged(String channelId, State newState) {
  87         getCallback().stateChanged(channelId, newState);
  88     }
  89
  90     /**
  91      * Updates a property via the {@link RioHandlerCallback#setProperty(String, String)}
  92      *
  93      * @param propertyName a non-null, non-empty property name
  94      * @param propertyValue a non-null, possibly empty property value
  95      */
  96     protected void setProperty(String propertyName, String propertyValue) {
  97         getCallback().setProperty(propertyName, propertyValue);
  98     }
  99
 100     /**
 101      * Updates the status via {@link RioHandlerCallback#statusChanged(ThingStatus, ThingStatusDetail, String)}
 102      *
 103      * @param status the new status
 104      * @param statusDetail the status detail
 105      * @param msg the status detail message
 106      */
 107     protected void statusChanged(ThingStatus status, ThingStatusDetail statusDetail, String msg) {
 108         getCallback().statusChanged(status, statusDetail, msg);
 109     }
 110
 111     /**
 112      * Disposes of the protocol by removing ourselves from listening to the socket via
 113      * {@link SocketSession#removeListener(SocketSessionListener)}
 114      */
 115     public void dispose() {
 116         session.removeListener(this);
 117     }
 118
 119     /**
 120      * Implements the {@link SocketSessionListener#responseException(Exception)} to automatically take the thing offline
 121      * via {@link RioHandlerCallback#statusChanged(ThingStatus, ThingStatusDetail, String)}
 122      *
 123      * @param e the exception
 124      */
 125     @Override
 126     public void responseException(IOException e) {
 127         getCallback().statusChanged(ThingStatus.OFFLINE, ThingStatusDetail.COMMUNICATION_ERROR,
 128                 "Exception occurred reading from the socket: " + e);
 129     }
 130
 131     /**
 132      * Returns the {@link RioHandlerCallback} used by this protocol
 133      *
 134      * @return a non-null {@link RioHandlerCallback}
 135      */
 136     public RioHandlerCallback getCallback() {
 137         return callback;
 138     }
 139 }