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