Package nl.tno.imb

Class TConnection

java.lang.Object
nl.tno.imb.TConnection
public class TConnection
extends Object
The connection to the framework and starting point to use IMB. All further actions are started through a new object of this class. Main actions are:
subscribe to events to receive events
publish events to send events (called signal). if autoPublish is true you start sending events immediately
set global framework variables
send streams over the framework
set/update the current status for the connected client
optionally define the owner (specific: connected model name and id)
optionally set specific socket and connection options

Subscribe and publish return TEventEntry objects that can be used to set handlers for receiving specific events.
Default a reading thread is started to handle all socket reading. The thread calls registered event handlers for the received events.
Author:
hans.cornelissen@tno.nl

  • Field Details

  • Constructor Details

    • TConnection

      public TConnection​(String aRemoteHost, int aRemotePort, String aOwnerName, int aOwnerID, String aFederation)
      Create an IMB connection to the framework
      Parameters:
      aRemoteHost - String; IP address or DNS name of the IMB hub to connect to
      aRemotePort - int; TCP port of the IMB hub to connect to
      aOwnerName - String; optional description of the connecting client
      aOwnerID - int; optional id of the connecting client
      aFederation - federation to connect with; this is default prefixed to subscribed and published event names

    • TConnection

      public TConnection​(String aRemoteHost, int aRemotePort, String aOwnerName, int aOwnerID, String aFederation, boolean aStartReadingThread)
      Create an IMB connection to the framework
      Parameters:
      aRemoteHost - String; IP address or DNS name of the IMB hub to connect to
      aRemotePort - int; TCP port of the IMB hub to connect to
      aOwnerName - String; optional description of the connecting client
      aOwnerID - int; optional id of the connecting client
      aFederation - federation to connect with; this is default prefixed to subscribed and published event names
      aStartReadingThread - boolean; use an internal reader thread for processing events and commands from the connected hub

  • Method Details

    • finalize

      protected void finalize()
      Overrides:
      finalize in class Object

    • writeCommand

      protected int writeCommand​(int aCommand, byte[] aPayload)
      Write a single command to the framework
      Parameters:
      aCommand - int;
      aPayload - byte[];
      Returns:
      see ICE_* constants

    • prefixFederation

      protected String prefixFederation​(String aName)

    • prefixFederation

      protected String prefixFederation​(String aName, boolean aUseFederationPrefix)

    • handleCommandOther

      protected void handleCommandOther​(int aCommand, TByteBuffer aPayload)

    • setState

      protected void setState​(TConnection.TConnectionState aState)

    • open

      protected boolean open​(String aHost, int aPort)

    • open

      protected boolean open​(String aHost, int aPort, boolean aStartReadingThread)

    • getFederation

      public String getFederation()
      Returns the current federation

    • setFederation

      public void setFederation​(String aFederation)
      Set the current federation. All subscribed and published events are unsubscribed/unpublished, then the federation is changed and all previously subscribed/publuished events are re-subscribed/re-published
      Parameters:
      aFederation - String; the new federation

    • getRemoteHost

      public String getRemoteHost()
      Returns the IP address or DNS name of the currently connected hub

    • getRemotePort

      public int getRemotePort()
      Returns the TCP port of the currently connected hub

    • getNoDelay

      public boolean getNoDelay() throws SocketException
      Returns the state of the NAGLE algorithm on the connected socket
      Returns:
      if true NAGLE is disabled (default false)
      Throws:
      SocketException

    • setNoDelay

      public void setNoDelay​(boolean aValue) throws SocketException
      Sets the state of the NAGLE algorithm on the socket
      Parameters:
      aValue - boolean; if true the NAGLE algorithm is DISABLED (default false)
      Throws:
      SocketException

    • getLinger

      public boolean getLinger() throws SocketException
      Returns the status of the linger option on the connected socket
      Returns:
      if true the linger option is enabled
      Throws:
      SocketException

    • setLinger

      public void setLinger​(boolean aValue) throws SocketException
      Sets the status of the linger option on the connected socket
      Parameters:
      aValue - boolean; if true the linger option is enabled with a linger time of 2 seconds
      Throws:
      SocketException

    • isConnected

      public boolean isConnected()
      Returns the connected state of the connection

    • close

      public void close()
      Closes the connection and cleans up socket, streams and thread

    • setThrottle

      public void setThrottle​(int aThrottle)
      Throttle down buffer events send to this client if specific flags are set on events
      Parameters:
      aThrottle - int;

    • readCommandsNonBlocking

      public void readCommandsNonBlocking() throws IOException
      Manually reading commands when not using a reader thread. Commands are read until connection is idle.
      Throws:
      IOException

    • readCommandsNonThreaded

      public void readCommandsNonThreaded​(int aTimeOut) throws SocketException
      Manually reading commands when not using a reader thread. Commands are processed until the reading on the connection times out
      Parameters:
      aTimeOut - int;
      Throws:
      SocketException

    • getOwnerID

      public int getOwnerID()
      Returns the currently specified owner id

    • setOwnerID

      public void setOwnerID​(int aValue)
      Changes the owner id
      Parameters:
      aValue - int; the new owner id

    • getOwnerName

      public String getOwnerName()
      Returns the currently specified owner name

    • setOwnerName

      public void setOwnerName​(String aValue)
      Changes the owner name
      Parameters:
      aValue - String; the new owner name

    • getUniqueClientID

      public int getUniqueClientID()
      Returns the unique client id the hub assigned to this connection

    • getClientHandle

      public int getClientHandle()
      Returns the client handle the hub assigned to this connection

    • subscribe

      public TEventEntry subscribe​(String aEventName)
      Subscribe to the specified event
      Parameters:
      aEventName - String; the event name to subscribe to (it will be prefixed with the current federation)
      Returns:
      event entry that is to be used to assign the handler for the received events

    • subscribe

      public TEventEntry subscribe​(String aEventName, boolean aUseFederationPrefix)
      Subscribe to the specified event
      Parameters:
      aEventName - String; the event name to subscribe to
      aUseFederationPrefix - boolean; if true the given event name will be prefixed with the current federation
      Returns:
      event entry that is to be used to assign the handler for the received events

    • publish

      public TEventEntry publish​(String aEventName)
      Publishes on the specified event
      Parameters:
      aEventName - String; the event name to publish on (it will be prefixed with the current federation)
      Returns:
      event entry that is to be used to signal events on

    • publish

      public TEventEntry publish​(String aEventName, boolean aUseFederationPrefix)
      Publishes on the specified event
      Parameters:
      aEventName - String; the event name to publish on
      aUseFederationPrefix - boolean; if true the given event name will be prefixed with the current federation
      Returns:
      event entry that is to be used to signal events on

    • unSubscribe

      public void unSubscribe​(String aEventName)
      Unsubscribe from the specified event
      Parameters:
      aEventName - String; the event name to unsubscribe from (it will be prefixed with the current federation)

    • unSubscribe

      public void unSubscribe​(String aEventName, boolean aUseFederationPrefix)
      Unsubscribe from the specified event
      Parameters:
      aEventName - String; the event name to unsubscribe from
      aUseFederationPrefix - boolean; if true the given event name will be prefixed with the current federation

    • unPublish

      public void unPublish​(String aEventName)
      Unpublish on the specified event.
      Parameters:
      aEventName - String; the event name to unpublish on (it will be prefixed with the current federation)

    • unPublish

      public void unPublish​(String aEventName, boolean aUseFederationPrefix)
      Unpublish on the specified event.
      Parameters:
      aEventName - String; the event name to unpublish on
      aUseFederationPrefix - boolean; if true the given event name will be prefixed with the current federation

    • signalEvent

      public int signalEvent​(String aEventName, int aEventKind, TByteBuffer aEventPayload)
      Send an event to the framework. This is the simple way to send events. More performance can be gained by using the returned event entry from publish().
      Parameters:
      aEventName - String;
      aEventKind - int;
      aEventPayload - TByteBuffer;
      Returns:
      result of the command (see ICE_* constants)

    • signalEvent

      public int signalEvent​(String aEventName, int aEventKind, TByteBuffer aEventPayload, boolean aUseFederationPrefix)
      Send an event to the framework. This is the simple way to send events. More performance can be gained by using the returned event entry from publish().
      Parameters:
      aEventName - String;
      aEventKind - int;
      aEventPayload - TByteBuffer;
      aUseFederationPrefix - boolean; if true the given event name will be prefixed with the current federation
      Returns:
      result of the command (see ICE_* constants)

    • signalBuffer

      public int signalBuffer​(String aEventName, int aBufferID, byte[] aBuffer)
      Send a buffer event to the framework. This is the simple way to send events. More performance can be gained by using the returned event entry from publish().
      Parameters:
      aEventName - String;
      aBufferID - int;
      aBuffer - byte[];
      Returns:
      result of the command (see ICE_* constants)

    • signalBuffer

      public int signalBuffer​(String aEventName, int aBufferID, byte[] aBuffer, int aEventFlags, boolean aUseFederationPrefix)
      Send a buffer event to the framework. This is the simple way to send events. More performance can be gained by using the returned event entry from publish().
      Parameters:
      aEventName - String;
      aBufferID - int;
      aBuffer - byte[];
      aEventFlags - int;
      aUseFederationPrefix - boolean; if true the given event name will be prefixed with the current federation
      Returns:
      result of the command (see ICE_* constants)

    • signalChangeObject

      public int signalChangeObject​(String aEventName, int aAction, int aObjectID, String aAttribute)
      Send a ChangeObject event to the framework This is the simple way to send events. More performance can be gained by using the returned event entry from publish().
      Parameters:
      aEventName - String;
      aAction - int;
      aObjectID - int;
      aAttribute - String;
      Returns:
      result of the command (see ICE_* constants)

    • signalChangeObject

      public int signalChangeObject​(String aEventName, int aAction, int aObjectID, String aAttribute, boolean aUseFederationPrefix)
      Send a ChangeObject event to the framework This is the simple way to send events. More performance can be gained by using the returned event entry from publish().
      Parameters:
      aEventName - String;
      aAction - int;
      aObjectID - int;
      aAttribute - String;
      aUseFederationPrefix - boolean; if true the given event name will be prefixed with the current federation
      Returns:
      result of the command (see ICE_* constants)

    • signalStream

      public int signalStream​(String aEventName, String aStreamName, InputStream aStream)
      Send a stream to the framework
      Parameters:
      aEventName - String;
      aStreamName - String; name of the stream to identify the stream by the receiver
      aStream - InputStream;
      Returns:
      result of the command (see ICE_* constants)

    • signalStream

      public int signalStream​(String aEventName, String aStreamName, InputStream aStream, boolean aUseFederationPrefix)
      Send a stream to the framework
      Parameters:
      aEventName - String;
      aStreamName - String;
      aStream - InputStream;
      aUseFederationPrefix - boolean;
      Returns:
      result of the command (see ICE_* constants)

    • setOnVariable

      public void setOnVariable​(TConnection.TOnVariable aValue)
      Set the callback handler for framework variable changes
      Parameters:
      aValue - TOnVariable;

    • requestAllVariables

      protected void requestAllVariables()
      Send a request to the framework to send all variables with their contents to this client

    • setVariableValue

      public void setVariableValue​(String aVarName, String aVarValue)
      Set the value of a global framework variable
      Parameters:
      aVarName - String;
      aVarValue - String;

    • setVariableValue

      public void setVariableValue​(String aVarName, TByteBuffer aVarValue)
      Set the value of a global framework variable
      Parameters:
      aVarName - String;
      aVarValue - TByteBuffer;

    • setVariableValue

      public void setVariableValue​(String aVarName, String aVarValue, TConnection.TVarPrefix aVarPrefix)
      Set the value of a global framework variable
      Parameters:
      aVarName - String;
      aVarValue - String;
      aVarPrefix - TVarPrefix;

    • setVariableValue

      public void setVariableValue​(String aVarName, TByteBuffer aVarValue, TConnection.TVarPrefix aVarPrefix)
      Set the value of a global framework variable
      Parameters:
      aVarName - String;
      aVarValue - TByteBuffer;
      aVarPrefix - TVarPrefix;

    • setOnStatusUpdate

      public void setOnStatusUpdate​(TConnection.TOnStatusUpdate aValue)
      Set the callback handler for status updates
      Parameters:
      aValue - TOnStatusUpdate;

    • updateStatus

      public void updateStatus​(int aProgress, int aStatus) throws InterruptedException
      Update the central status for this client
      Parameters:
      aProgress - int; the progress, if available, from 0 to 100 or counting down to 0
      aStatus - int; the current status of the client (see STATUS_* constants)
      Throws:
      InterruptedException

    • removeStatus

      public void removeStatus()
      Removes the current status for this client

    • subscribeOnFocus

      public void subscribeOnFocus​(TEventEntry.TOnFocus aOnFocus)
      Subscribe to focus events and registers the callback handler for these events.
      Parameters:
      aOnFocus - TEventEntry.TOnFocus; callback event handler

    • signalFocus

      public int signalFocus​(double aX, double aY)
      Signal a new focus point to the framework
      Parameters:
      aX - double;
      aY - double;
      Returns:
      result of the command (see ICE_* constants)

    • subscribeOnFederationChange

      public void subscribeOnFederationChange​(TEventEntry.TOnChangeFederation aOnChangeFederation)
      Subscribe to federation change events and register the callback handler for these events
      Parameters:
      aOnChangeFederation - TEventEntry.TOnChangeFederation;

    • signalChangeFederation

      public int signalChangeFederation​(int aNewFederationID, String aNewFederation)
      Signal a new federation to the framework
      Parameters:
      aNewFederationID - int;
      aNewFederation - String;
      Returns:
      result of the command (see ICE_* constants)

    • logWriteLn

      public int logWriteLn​(String aLogEventName, String aLine, TEventEntry.TLogLevel aLevel)
      Log an entry to the framework
      Parameters:
      aLogEventName - String;
      aLine - String;
      aLevel - TEventEntry.TLogLevel;
      Returns:
      result of the command (see ICE_* constants)

    • requestEventname

      public int requestEventname​(String aEventNameFilter, int aEventFilters)
      Query the framework for registered event names
      Parameters:
      aEventNameFilter - String;
      aEventFilters - int;
      Returns:
      result of the command (see ICE_* constants)

    • toString

      public final String toString()
      Overrides:
      toString in class Object