Package org.openremote.agent.protocol

Class AbstractProtocol<T extends org.openremote.model.asset.agent.Agent<T,?,U>,U extends org.openremote.model.asset.agent.AgentLink<?>>

java.lang.Object
org.openremote.agent.protocol.AbstractProtocol<T,U>
All Implemented Interfaces:
org.openremote.model.asset.agent.Protocol<T>
Direct Known Subclasses:
AbstractHTTPServerProtocol, AbstractIOClientProtocol, AbstractTCPServerProtocol, AbstractVelbusProtocol, BluetoothMeshProtocol, ControllerProtocol, HTTPProtocol, KNXProtocol, SimulatorProtocol, SNMPProtocol, StorageSimulatorProtocol, TradfriProtocol, ZWaveProtocol
public abstract class AbstractProtocol<T extends org.openremote.model.asset.agent.Agent<T,?,U>,U extends org.openremote.model.asset.agent.AgentLink<?>> extends Object implements org.openremote.model.asset.agent.Protocol<T>
Thread-safe base implementation for protocols.

Subclasses should use the GlobalLock.withLock(java.lang.String, java.lang.Runnable) and GlobalLock.withLockReturning(java.lang.String, java.util.function.Supplier<R>) methods to guard critical sections when modifying shared state: 


 withLock(getProtocolName(), () -> {
     // Critical section
 });
 

 return withLockReturning(() -> {
     // Critical section
     return ...;
 });

All abstract methods are always called within lock scope. An implementation can rely on this lock and safely modify internal, protocol-specific shared state. However, if a protocol implementation schedules an asynchronous task, this task must obtain the lock to call any protocol operations.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected T
    agent
     
    protected ProtocolAssetService
    assetService
     
    protected ProtocolDatapointService
    datapointService
     
    protected final Set<org.openremote.model.attribute.AttributeRef>
    dynamicAttributes
     
    protected ScheduledExecutorService
    executorService
     
    protected final Map<org.openremote.model.attribute.AttributeRef,org.openremote.model.attribute.Attribute<?>>
    linkedAttributes
     
    protected org.openremote.container.message.MessageBrokerContext
    messageBrokerContext
     
    protected ProtocolPredictedDatapointService
    predictedDatapointService
     
    protected org.apache.camel.ProducerTemplate
    producerTemplate
     
    protected org.openremote.container.timer.TimerService
    timerService
     

    Fields inherited from interface org.openremote.model.asset.agent.Protocol

    ACTUATOR_TOPIC, ACTUATOR_TOPIC_TARGET_PROTOCOL, DYNAMIC_TIME_PLACEHOLDER_REGEXP, DYNAMIC_VALUE_PLACEHOLDER, DYNAMIC_VALUE_PLACEHOLDER_REGEXP, SENSOR_QUEUE, SENSOR_QUEUE_SOURCE_PROTOCOL

  • Constructor Summary

    Constructors
    Constructor
    Description
    AbstractProtocol(T agent)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    protected abstract void
    doLinkAttribute(String assetId, org.openremote.model.attribute.Attribute<?> attribute, U agentLink)
    Link an Attribute to its linked Agent.
    protected abstract void
    doLinkedAttributeWrite(org.openremote.model.attribute.Attribute<?> attribute, U agentLink, org.openremote.model.attribute.AttributeEvent event, Object processedValue)
    An Attribute event (write) has been requested for an attribute linked to this protocol.
    protected abstract void
    doStart(org.openremote.model.Container container)
    Start this protocol instance
    protected abstract void
    doStop(org.openremote.model.Container container)
    Stop this protocol instance
    protected abstract void
    doUnlinkAttribute(String assetId, org.openremote.model.attribute.Attribute<?> attribute, U agentLink)
    Unlink an Attribute from its linked Agent.
    T
    getAgent()
    Get the Agent associated with this protocol instance.
    Map<org.openremote.model.attribute.AttributeRef,org.openremote.model.attribute.Attribute<?>>
    getLinkedAttributes()
    Get list of Attributes currently linked to this protocol instance grouped by Asset ID
    final void
    linkAttribute(String assetId, org.openremote.model.attribute.Attribute<?> attribute)
    Links an Attribute to its' agent; the agent would have been connected before this call.
    protected final void
    processLinkedAttributeWrite(org.openremote.model.attribute.AttributeEvent event)
     
    protected final void
    sendAttributeEvent(org.openremote.model.attribute.AttributeEvent event)
    Send an arbitrary AttributeEvent through the processing chain.
    protected final void
    sendAttributeEvent(org.openremote.model.attribute.AttributeState state)
    Send an arbitrary AttributeState through the processing chain using the current system time as the timestamp.
    protected void
    setConnectionStatus(org.openremote.model.asset.agent.ConnectionStatus connectionStatus)
     
    void
    start(org.openremote.model.Container container)
    Called before any calls to Protocol.linkAttribute(java.lang.String, org.openremote.model.attribute.Attribute<?>) to allow the protocol to perform required tasks with ContainerServices (e.g.
    final void
    stop(org.openremote.model.Container container)
    Called once all linked attributes have been unlinked via Protocol.unlinkAttribute(java.lang.String, org.openremote.model.attribute.Attribute<?>) to allow the protocol to perform required tasks with ContainerServices e.g.
    String
    toString()
     
    final void
    unlinkAttribute(String assetId, org.openremote.model.attribute.Attribute<?> attribute)
    Un-links an Attribute from its' agent; the agent will still be connected during this call.
    protected final void
    updateAgentAttribute(org.openremote.model.attribute.AttributeState state)
    Update the value of one of this Protocols linked Agent's Attributes.
    protected final void
    updateLinkedAttribute(org.openremote.model.attribute.AttributeState state)
    Update the value of a linked attribute, with the current system time as event time see updateLinkedAttribute(AttributeState, long) for more details.
    protected final void
    updateLinkedAttribute(org.openremote.model.attribute.AttributeState state, long timestamp)
    Update the value of a linked attribute.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    Methods inherited from interface org.openremote.model.asset.agent.Protocol

    getProtocolInstanceUri, getProtocolName, prefixLogMessage

  • Field Details

    • linkedAttributes

      protected final Map<org.openremote.model.attribute.AttributeRef,org.openremote.model.attribute.Attribute<?>> linkedAttributes

    • dynamicAttributes

      protected final Set<org.openremote.model.attribute.AttributeRef> dynamicAttributes

    • messageBrokerContext

      protected org.openremote.container.message.MessageBrokerContext messageBrokerContext

    • producerTemplate

      protected org.apache.camel.ProducerTemplate producerTemplate

    • timerService

      protected org.openremote.container.timer.TimerService timerService

    • executorService

      protected ScheduledExecutorService executorService

    • assetService

      protected ProtocolAssetService assetService

    • predictedDatapointService

      protected ProtocolPredictedDatapointService predictedDatapointService

    • datapointService

      protected ProtocolDatapointService datapointService

    • agent

      protected T extends org.openremote.model.asset.agent.Agent<T,?,U> agent

  • Constructor Details

    • AbstractProtocol

      public AbstractProtocol(T agent)

  • Method Details

    • start

      public void start(org.openremote.model.Container container) throws Exception
      Description copied from interface: org.openremote.model.asset.agent.Protocol
      Called before any calls to Protocol.linkAttribute(java.lang.String, org.openremote.model.attribute.Attribute<?>) to allow the protocol to perform required tasks with ContainerServices (e.g. register Camel routes). The protocol instance should validate the settings defined in the associated Agent; but whether or not the protocol establishes a connection/ fully initialises at this time is up to the protocol implementation, it could be desirable to wait until Protocol.linkAttribute(java.lang.String, org.openremote.model.attribute.Attribute<?>) is called for the first time, or it could be a connectionless protocol. If there is a configuration issue etc. then an appropriate exception should be thrown and suitable logs made.
      Specified by:
      start in interface org.openremote.model.asset.agent.Protocol<T extends org.openremote.model.asset.agent.Agent<T,?,U>>
      Throws:
      Exception

    • stop

      public final void stop(org.openremote.model.Container container)
      Description copied from interface: org.openremote.model.asset.agent.Protocol
      Called once all linked attributes have been unlinked via Protocol.unlinkAttribute(java.lang.String, org.openremote.model.attribute.Attribute<?>) to allow the protocol to perform required tasks with ContainerServices e.g. remove Camel routes, destroy/cleanup resources etc.
      Specified by:
      stop in interface org.openremote.model.asset.agent.Protocol<T extends org.openremote.model.asset.agent.Agent<T,?,U>>

    • setConnectionStatus

      protected void setConnectionStatus(org.openremote.model.asset.agent.ConnectionStatus connectionStatus)

    • linkAttribute

      public final void linkAttribute(String assetId, org.openremote.model.attribute.Attribute<?> attribute) throws Exception
      Description copied from interface: org.openremote.model.asset.agent.Protocol
      Links an Attribute to its' agent; the agent would have been connected before this call. This is called when the agent is connected or when the attribute has been modified and re-linked.

      If the attribute is not valid for this protocol then it is up to the protocol to log the issue and return false.

      Attributes are linked to an agent via an MetaItemType.AGENT_LINK meta item.

      Specified by:
      linkAttribute in interface org.openremote.model.asset.agent.Protocol<T extends org.openremote.model.asset.agent.Agent<T,?,U>>
      Throws:
      Exception

    • unlinkAttribute

      public final void unlinkAttribute(String assetId, org.openremote.model.attribute.Attribute<?> attribute) throws Exception
      Description copied from interface: org.openremote.model.asset.agent.Protocol
      Un-links an Attribute from its' agent; the agent will still be connected during this call. This is called whenever the attribute is modified or removed or when the agent is modified or removed.
      Specified by:
      unlinkAttribute in interface org.openremote.model.asset.agent.Protocol<T extends org.openremote.model.asset.agent.Agent<T,?,U>>
      Throws:
      Exception

    • getAgent

      public T getAgent()
      Description copied from interface: org.openremote.model.asset.agent.Protocol
      Get the Agent associated with this protocol instance.
      Specified by:
      getAgent in interface org.openremote.model.asset.agent.Protocol<T extends org.openremote.model.asset.agent.Agent<T,?,U>>

    • getLinkedAttributes

      public Map<org.openremote.model.attribute.AttributeRef,org.openremote.model.attribute.Attribute<?>> getLinkedAttributes()
      Description copied from interface: org.openremote.model.asset.agent.Protocol
      Get list of Attributes currently linked to this protocol instance grouped by Asset ID
      Specified by:
      getLinkedAttributes in interface org.openremote.model.asset.agent.Protocol<T extends org.openremote.model.asset.agent.Agent<T,?,U>>

    • processLinkedAttributeWrite

      protected final void processLinkedAttributeWrite(org.openremote.model.attribute.AttributeEvent event)

    • sendAttributeEvent

      protected final void sendAttributeEvent(org.openremote.model.attribute.AttributeState state)
      Send an arbitrary AttributeState through the processing chain using the current system time as the timestamp. Use updateLinkedAttribute(org.openremote.model.attribute.AttributeState, long) to publish new sensor values, which performs additional verification and uses a different messaging queue.

    • sendAttributeEvent

      protected final void sendAttributeEvent(org.openremote.model.attribute.AttributeEvent event)
      Send an arbitrary AttributeEvent through the processing chain. Use updateLinkedAttribute(org.openremote.model.attribute.AttributeState, long) to publish new sensor values, which performs additional verification and uses a different messaging queue.

    • updateLinkedAttribute

      protected final void updateLinkedAttribute(org.openremote.model.attribute.AttributeState state, long timestamp)
      Update the value of a linked attribute. Call this to publish new sensor values. This will call ProtocolUtil.doInboundValueProcessing(java.lang.String, org.openremote.model.attribute.Attribute<?>, org.openremote.model.asset.agent.AgentLink<?>, java.lang.Object) before sending on the sensor queue.

    • updateAgentAttribute

      protected final void updateAgentAttribute(org.openremote.model.attribute.AttributeState state)
      Update the value of one of this Protocols linked Agent's Attributes.

    • updateLinkedAttribute

      protected final void updateLinkedAttribute(org.openremote.model.attribute.AttributeState state)
      Update the value of a linked attribute, with the current system time as event time see updateLinkedAttribute(AttributeState, long) for more details.

    • doStart

      protected abstract void doStart(org.openremote.model.Container container) throws Exception
      Start this protocol instance
      Throws:
      Exception

    • doStop

      protected abstract void doStop(org.openremote.model.Container container) throws Exception
      Stop this protocol instance
      Throws:
      Exception

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • doLinkAttribute

      protected abstract void doLinkAttribute(String assetId, org.openremote.model.attribute.Attribute<?> attribute, U agentLink) throws RuntimeException
      Link an Attribute to its linked Agent.
      Throws:
      RuntimeException

    • doUnlinkAttribute

      protected abstract void doUnlinkAttribute(String assetId, org.openremote.model.attribute.Attribute<?> attribute, U agentLink)
      Unlink an Attribute from its linked Agent.

    • doLinkedAttributeWrite

      protected abstract void doLinkedAttributeWrite(org.openremote.model.attribute.Attribute<?> attribute, U agentLink, org.openremote.model.attribute.AttributeEvent event, Object processedValue)
      An Attribute event (write) has been requested for an attribute linked to this protocol. The processedValue is the resulting value after applying standard outbound value processing (see ProtocolUtil.doOutboundValueProcessing(java.lang.String, org.openremote.model.attribute.Attribute<?>, org.openremote.model.asset.agent.AgentLink<?>, java.lang.Object, boolean)). Protocol implementations should generally use the processedValue but may also choose to use the original value for some purpose if required.