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

   1 /**
   2  * Copyright (c) 2010-2020 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.io.transport.modbus;
  14
  15 import java.util.concurrent.Future;
  16
  17 import org.eclipse.jdt.annotation.NonNullByDefault;
  18 import org.openhab.io.transport.modbus.endpoint.ModbusSlaveEndpoint;
  19
  20 /**
  21  * Interface for interacting with a particular modbus slave.
  22  *
  23  * When no further communication is expected with the slave, close the interface so that any underlying resources can be
  24  * freed.
  25  *
  26  * Close unregisters all the regular polls registered with registerRegularPoll. When endpoint's last
  27  * communication interface is closed, the connection is closed as well, no matter the what EndpointPoolConfiguration
  28  * says.
  29  *
  30  * @author Sami Salonen - Initial contribution
  31  *
  32  */
  33 @NonNullByDefault
  34 public interface ModbusCommunicationInterface extends AutoCloseable {
  35
  36     /**
  37      * Get endpoint associated with this communication interface
  38      *
  39      * @return modbus slave endpoint
  40      */
  41     public ModbusSlaveEndpoint getEndpoint();
  42
  43     /**
  44      * Submit one-time poll task. The method returns immediately, and the execution of the poll task will happen in
  45      * background.
  46      *
  47      * @param request request to send
  48      * @param callback callback to call with data
  49      * @param callback callback to call in case of failure
  50      * @return future representing the polled task
  51      * @throws IllegalStateException when this communication has been closed already
  52      */
  53     public Future<?> submitOneTimePoll(ModbusReadRequestBlueprint request, ModbusReadCallback resultCallback,
  54             ModbusFailureCallback<ModbusReadRequestBlueprint> failureCallback);
  55
  56     /**
  57      * Register regularly polled task. The method returns immediately, and the execution of the poll task will happen in
  58      * the background.
  59      *
  60      * One can register only one regular poll task for triplet of (endpoint, request, callback).
  61      *
  62      * @param request request to send
  63      * @param pollPeriodMillis poll interval, in milliseconds
  64      * @param initialDelayMillis initial delay before starting polling, in milliseconds
  65      * @param callback callback to call with data
  66      * @param callback callback to call in case of failure
  67      * @return poll task representing the regular poll
  68      * @throws IllegalStateException when this communication has been closed already
  69      */
  70     public PollTask registerRegularPoll(ModbusReadRequestBlueprint request, long pollPeriodMillis,
  71             long initialDelayMillis, ModbusReadCallback resultCallback,
  72             ModbusFailureCallback<ModbusReadRequestBlueprint> failureCallback);
  73
  74     /**
  75      * Unregister regularly polled task
  76      *
  77      * If this communication interface is closed already, the method returns immediately with false return value
  78      *
  79      * @param task poll task to unregister
  80      * @return whether poll task was unregistered. Poll task is not unregistered in case of unexpected errors or
  81      *         in the case where the poll task is not registered in the first place
  82      */
  83     public boolean unregisterRegularPoll(PollTask task);
  84
  85     /**
  86      * Submit one-time write task. The method returns immediately, and the execution of the task will happen in
  87      * background.
  88      *
  89      * @param request request to send
  90      * @param callback callback to call with response
  91      * @param callback callback to call in case of failure
  92      * @return future representing the task
  93      * @throws IllegalStateException when this communication has been closed already
  94      */
  95     public Future<?> submitOneTimeWrite(ModbusWriteRequestBlueprint request, ModbusWriteCallback resultCallback,
  96             ModbusFailureCallback<ModbusWriteRequestBlueprint> failureCallback);
  97
  98     /**
  99      * Close this communication interface and try to free all resources associated with it
 100      *
 101      * Upon close, all polling tasks registered by this instance are unregistered. In addition, connections are closed
 102      * eagerly if this was the last connection interface pointing to the endpoint.
 103      *
 104      * After close, the communication interface cannot be used to communicate with the device.
 105      *
 106      */
 107     @Override
 108     public void close() throws Exception;
 109 }