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

   1 /**
   2  * Copyright (c) 2010-2022 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.net;
  14
  15 import java.io.IOException;
  16
  17 /**
  18  * This is a socket session interface that defines the contract for a socket session. A socket session will initiate
  19  * communications with the underlying device and provide message back via the {@link SocketSessionListener}
  20  *
  21  * @author Tim Roberts - Initial contribution
  22  */
  23 public interface SocketSession {
  24
  25     /**
  26      * Adds a {@link SocketSessionListener} to call when responses/exceptions have been received
  27      *
  28      * @param listener a non-null {@link SocketSessionListener} to use
  29      */
  30     void addListener(SocketSessionListener listener);
  31
  32     /**
  33      * Clears all listeners
  34      */
  35     void clearListeners();
  36
  37     /**
  38      * Removes a {@link SocketSessionListener} from this session
  39      *
  40      * @param listener a non-null {@link SocketSessionListener} to remove
  41      * @return true if removed, false otherwise
  42      */
  43     boolean removeListener(SocketSessionListener listener);
  44
  45     /**
  46      * Will attempt to connect to the {@link #_host} on port {@link #_port}. Simply calls {@link #connect(int)} with
  47      * a 2 second timeout
  48      *
  49      * @throws java.io.IOException if an exception occurs during the connection attempt
  50      */
  51     void connect() throws IOException;
  52
  53     /**
  54      * Will attempt to connect to the {@link #_host} on port {@link #_port}. If we are current connected, will
  55      * {@link #disconnect()} first. Once connected, the {@link #_writer} and {@link #_reader} will be created, the
  56      * {@link #_dispatcher} and {@link #_responseReader} will be started.
  57      *
  58      * @param timeout a connection timeout (in milliseconds)
  59      * @throws java.io.IOException if an exception occurs during the connection attempt
  60      */
  61     void connect(int timeout) throws IOException;
  62
  63     /**
  64      * Disconnects from the {@link #_host} if we are {@link #isConnected()}. The {@link #_writer}, {@link #_reader} and
  65      * {@link #_client}
  66      * will be closed and set to null. The {@link #_dispatcher} and {@link #_responseReader} will be stopped, the
  67      * {@link #_listeners} will be nulled and the {@link #_responses} will be cleared.
  68      *
  69      * @throws java.io.IOException if an exception occurs during the disconnect attempt
  70      */
  71     void disconnect() throws IOException;
  72
  73     /**
  74      * Returns true if we are connected ({@link #_client} is not null and is connected)
  75      *
  76      * @return true if connected, false otherwise
  77      */
  78     boolean isConnected();
  79
  80     /**
  81      * Sends the specified command to the underlying socket
  82      *
  83      * @param command a non-null, non-empty command
  84      * @throws java.io.IOException an exception that occurred while sending
  85      */
  86     void sendCommand(String command) throws IOException;
  87 }