Package nl.tno.imb

Class 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 Detail

      • MAGIC_BYTES

        public static final byte[] MAGIC_BYTES
        magic bytes to identify the start of a valid IMB packet

      • MAGIC_STRING_CHECK

        public static final byte[] MAGIC_STRING_CHECK
        magic bytes to identify the end of the payload on a valid IMB packet (as array of bytes)

      • MAX_PAYLOAD_SIZE

        public static final int MAX_PAYLOAD_SIZE
        The maximum size of the payload in a low level IMB command
        See Also:
        Constant Field Values

      • DEFAULT_HUB

        public static final String DEFAULT_HUB
        value to be used when no specific remote server is used
        See Also:
        Constant Field Values

      • DEFAULT_PORT

        public static final int DEFAULT_PORT
        value to be used when no specific port is used
        See Also:
        Constant Field Values

      • DEFAULT_FEDERATION

        public static final String DEFAULT_FEDERATION
        value to be used when no specific federation is used
        See Also:
        Constant Field Values

      • ICE_CONNECTION_CLOSED

        public static final int ICE_CONNECTION_CLOSED
        command result: the connection is closed
        See Also:
        Constant Field Values

      • ICE_EVENT_NOT_PUBLISHED

        public static final int ICE_EVENT_NOT_PUBLISHED
        command result: the event was not published
        See Also:
        Constant Field Values

      • autoPublish

        public boolean autoPublish
        when true events send on not-publuished events are automatically published

      • imb2Compatible

        public boolean imb2Compatible
        when true IMB2 features are used if possible to emulate IMB3 behavior

      • STATUS_READY

        public static final int STATUS_READY
        signal client status: ready (see updateStatus)
        See Also:
        Constant Field Values

      • STATUS_CALCULATING

        public static final int STATUS_CALCULATING
        signal client status: calculating (see updateStatus)
        See Also:
        Constant Field Values

      • STATUS_BUSY

        public static final int STATUS_BUSY
        signal client status: busy (see updateStatus)
        See Also:
        Constant Field Values

      • EF_PUBLISHERS

        public static final int EF_PUBLISHERS
        request event name filter: requesting publisher counts
        See Also:
        Constant Field Values

      • EF_SUBSCRIBERS

        public static final int EF_SUBSCRIBERS
        request event name filter: requesting subscriber counts
        See Also:
        Constant Field Values

      • EF_TIMERS

        public static final int EF_TIMERS
        request event name filter: requesting timer counts
        See Also:
        Constant Field Values

    • Constructor Detail

      • 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 Detail

      • 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)

      • 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)