Target Communication Framework Specification

after

    Command X=2

    Event X=3
    Result X=2

    Event X=2
    Result X=3
    Event X=4

<message>
    ⇒ <command>
    ⇒ <result>
    ⇒ <event>
    ⇒ <flow control message>

<command>
    ⇒ C • <token> • <service name> • <command name> • <byte array: arguments>

<token>
    ⇒ <chars>

<service name>
    ⇒ <chars>

<command name>
    ⇒ <chars>

<result>
    ⇒ N • <token> •
    ⇒ R • <token> • <byte array: result data>
    ⇒ P • <token> • <byte array: progress data>

<token>
    ⇒ <chars>

<event>
    ⇒ E • <service name> • <event name> • <byte array: event data>

<service name>
    ⇒ <chars>

<event name>
    ⇒ <chars>

<flow control message>
    ⇒ F • <int: traffic congestion level> •

Send   :      C 1 RunControl suspend “Thread1”
Receive:      E RunControl suspended “Thread1”
Receive:      R 1 “Success”

Receive:      E RunControl suspended “Thread1”
…
Send   :      C 2 RunControl suspend “Thread1”
Receive:      R 2 “Already suspended”

Receive:      E RunControl running “Thread1”
…
Send   :      C 3 RunControl suspend “Thread1”
Receive:      E RunControl suspended “Thread1”
Receive:      R 3 “Already suspended”

/**
 *
 * Class Protocol provides static methods to access Target Communication Framework root objects:
 * 1. the framework event queue and dispatch thread;
 * 2. local instance of Locator service, which maintains a list of available targets;
 * 3. list of open communication channels.
 */
public class Protocol {

    private static IEventQueue event_queue;

    /**
     * Before TCF can be used it should be given an object implementing IEventQueue interface.
     * The implementation maintains a queue of objects implementing Runnable interface and
     * executes run methods of that objects in a sequence by a single thread.
     * The thread in referred as TCF event dispatch thread. Objects in the queue are called TCF events.
     * Executing run method of an event is also called dispatching of event.
     *
     * Only few methods in TCF APIs are thread safe - can be invoked from any thread.
     * If a method description does not say "can be invoked from any thread" explicitly -
     * the method must be invoked from TCF event dispatch thread. All TCF listeners are
     * invoked from the dispatch thread.
     *
     * @param event_queue - IEventQueue implementation.
     */
    public static void setEventQueue(IEventQueue event_queue);

    /**
     * @return instance of IEventQueue that should be used for TCF events.
     */
    public static IEventQueue getEventQueue();

    /**
     * Returns true if the calling thread is TCF dispatch thread.
     * Use this call to ensure that a given task is being executed (or not being)
     * on dispatch thread.
     * This method is thread-safe.
     *
     * @return true if running on the dispatch thread.
     */
    public static boolean isDispatchThread();

    /**
     * Causes runnable to have its run
     * method called in the dispatch thread of the framework.
     * Runnables are dispatched in same order as queued.
     * If invokeLater is called from the dispatching thread
     * the runnable.run() will still be deferred until
     * all pending events have been processed.
     *
     * This method can be invoked from any thread.
     *
     * @param runnable the Runnable whose run
     * method should be executed asynchronously.
     */
    public static void invokeLater(Runnable runnable);

    /**
     * Causes runnable to have its run
     * method called in the dispatch thread of the framework.
     * Calling thread is suspended util the method is executed.
     * This method is thread-safe.
     *
     * @param runnable the Runnable whose run
     * method should be executed on dispatch thread.
     */
    public static void invokeAndWait(Runnable runnable)
        throws InterruptedException;

    /**
     * Get instance of the framework locator service.
     * The service can be used to discover available remote peers.
     *
     * @return instance of ILocator.
     */
    public static ILocator getLocator();

    /**
     * Return an array of all open channels.
     * @return an array of IChannel
     */
    public static IChannel[] getOpenChannels();

    /**
     * Interface to be implemented by clients willing to be notified when
     * new TCF communication channel is opened.
     */
    public interface ChannelOpenListener {
        public void onChannelOpen(IChannel channel);
    }

    /**
     * Add a listener that will be notified when new channel is opened.
     * @param listener
     */
    public static void addChannelOpenListener(ChannelOpenListener listener);

    /**
     * Remove channel opening listener.
     * @param listener
     */
    public static void removeChannelOpenListener(ChannelOpenListener listener);

    /**
     * Transmit TCF event message.
     * The message is sent to all open communication channels – broadcasted.
     */
    public static void sendEvent(String service, String name, byte[] data);

    /**
     * Call back after TCF messages sent by this host up to this moment are delivered
     * to their intended target. This method is intended for synchronization of messages
     * across multiple channels.
     *
     * Note: Cross channel synchronization can reduce performance and throughput.
     * Most clients don't need cross channel synchronization and should not call this method.
     *
     * @param done will be executed by dispatch thread after communication
     * messages are delivered to corresponding targets.
     */
    public static void sync(Runnable done);
}

/**
 * IChannel represents communication link connecting two endpoints (peers).
 * The channel asynchroniously transmits messages: commands, results and events.
 * A single channel may be used to communicate with multiple services.
 * Multiple channels may be used to connect the same peers, however no command or event
 * ordering is guaranteed across channels.
 */
public interface IChannel {

    /**
     * Channel state IDs
     */
    static final int
        STATE_OPENNING = 0,
        STATE_OPEN = 1,
        STATE_CLOSED = 2;

    /**
     * @return channel current state, see STATE_*
     */
    int getState();

    /**
     * Send command message to remote peer for execution. Commands can be queued
     * locally before transmission. Sending commands too fast can fill up
     * communication channel buffers. Calling thread will be blocked until
     * enough buffer space is freed up by transmitting pending messages.
     * @param service - a remote service that will be sent the command
     * @param name - command name
     * @param args - command arguments encoded into array of bytes
     * @param done - call back object
     * @return pending command handle
     */
    IToken sendCommand(IService service, String name, byte[] args,
        ICommandListener done);

    /**
     * Command listener interface. Clients implement this interface
     * to receive command results.
     */
    interface ICommandListener {

        /**
         * Called when progress message (intermediate result) is received
         * from remote peer.
         * @param token - command handle
         * @param data - progress message arguments encoded into array of bytes
         */
        void progress(byte[] data);

        /**
         * Called when command result received from remote peer.
         * @param token - command handle
         * @param data - command result message arguments encoded into array of bytes
         */
        void result(byte[] data);

        /**
         * Called when communication channel was closed while command was waiting for result.
         * @param token - command handle
         * @param error - exception that forced the channel to close
         */
        void terminated(IToken token, Exception error);
    }

    /**
     * Send result message to remote peer. Messages can be queued locally before
     * transmission. Sending messages too fast can fill up communication channel
     * buffers. Calling thread will be blocked until enough buffer space is
     * freed up by transmitting pending messages.
     * @param token - command handle
     * @param results - result message arguments encoded into array of bytes
     */
    void sendResult(IToken token, byte[] results);

    /**
     * Get current level of outbound traffic congestion.
     *
     * @return integer value in range –100..100, where –100 means no pending
     * messages (no traffic), 0 means optimal load, and positive numbers
     * indicate level of congestion.
     *
     * Note: in-bound traffic congestion is detected by framework and reported to
     * remote peer without client needed to be involved. Clients willing to provide
     * additional data about local congestion should register itself using
     * Protocol.addCongestionMonitor().
     */
    int getCongestion();

    /**
     * Channel listener interface.
     */
    interface IChannelListener {

        /**
         * Called when a channel is opened.
         */
        void onChannelOpened();

        /**
         * Called when channel closed. If it is closed because of an error,
         * ‘error’ parameter will describe the error. ‘error’ is null if channel
         * is closed normally by calling Channel.close().
         * @param error - channel exception or null
         */
        void onChannelClosed(Throwable error);

        /**
         * Notifies listeners about congestion level changes. When level > 0
         * client should delay sending more messages.
         * @param level - current congestion level
         */
        void congestionLevel(int level);
    }

    /**
     * Subscribe a channel listener. The listener will be notified about changes of
     * outbound traffic congestion level.
     * @param listener - channel listener implementation
     */
    void addChannelListener(IChannelListener listener);

    /**
     * Remove a channel listener.
     * @param listener - channel listener implementation
     */
    void removeChannelListener(IChannelListener listener);

    /**
     * Command server interface.
     * This interface is to be implemented by service providers.
     */
    interface ICommandServer {

        /**
         * Called every time a command is received from remote peer.
         * @param token - command handle
         * @param name - command name
         * @param data - command arguments encoded into array of bytes
         */
        void command(IToken token, String name, byte[] data);
    }

    /**
     * Subscribe a command server. The server will be notified about command
     * messages received through this channel for given service.
     * @param service - local service implementation
     * @param server - implementation of service commands listener
     */
    void addCommandServer(IService service, ICommandServer listener);

    /**
     * Remove a command server.
     * @param service - local service implementation
     * @param server - implementation of service commands listener
     */
    void removeCommandServer(IService service, ICommandServer listener);

    /**
     * A generic interface for service event listener.
     * Services usually define a service specific event listener interface,
     * which is implemented using this generic listener.
     * Service clients should use service specific listener interface,
     * unless no such interface is defined.
     */
    interface IEventListener {
        /**
         * Called when service event message is received
         * @param name - event name
         * @param data - event arguments encode as array of bytes
         */
        void event(String name, byte[] data);
    }

    /**
     * Subscribe an event message listener for given service.
     * @param service - remote service proxy
     * @param server - implementation of service event listener
     */
    void addEventListener(IService service, IEventListener listener);

    /**
     * Unsubscribe an event message listener for given service.
     * @param service - remote service proxy
     * @param server - implementation of service event listener
     */
    void removeEventListener(IService service, IEventListener listener);

    /**
     * @return IPeer object representing local endpoint of communication channel.
     */
    IPeer getLocalPeer();

    /**
     * @return IPeer object representing remote endpoint of communication channel.
     */
    IPeer getRemotePeer();

    /**
     * @return collection of services available on local peer.
     */
    Collection<String> getLocalServices();

    /**
     * @return an object representing a service from local peer.
     * Return null if the service is not available.
     */
    IService getLocalService(String service_name);

    /**
     * @return an object representing a service from local peer.
     * Service object should implement given interface.
     * Return null if implementation of the interface is not available.
     */
    <V extends IService> V getLocalService(Class<V> service_interface);

    /**
     * @return collection of services available on remote peer.
     */
    Collection<String> getRemoteServices();

    /**
     * @return an object (proxy) representing a service from remote peer.
     * Return null if the service is not available.
     * Return an instance of GenericProxy if 'service_name' is not a standard TCF service.
     */
    IService getRemoteService(String service_name);

    /**
     * @return an object (proxy) representing a service from remote peer,
     * which implements given interface.
     * Return null if implementation of the interface is not available.
     */
    <V extends IService> V getRemoteService(Class<V> service_interface);

    /**
     * Install a service proxy object on this channel.
     * This method can be called only from channel open call-back.
     * It allows a client to extends TCF by adding proxy objects for non-standard services.
     * Client, wishing to become service proxy provider, should register itself
     * using either Protocol.addChannelOpenListener() or IChannel.addChannelListener().
     * It is not allowed to register more then one proxy for a given service interface.
     */
    <V extends IService> void setServiceProxy(Class<V> service_interface, IService service_proxy);

    /**
     * Close communication channel.
     */
    void close();

    /**
     * Close channel in case of communication error.
     * @param error - cause of channel termination
     */
    void terminate(Throwable error);

    /**
     * Redirect this channel to given peer using this channel remote peer locator service as a proxy.
     * @param peer_ - peer that will become new remote communication endpoint of this channel
     */
    void redirect(IPeer peer);
}

/**
 * Object implemeting IToken interface is created by framework for every
 * command sent over communication channel. It is used to match command to its
 * results, and also can be used to cancel commands.
 */
public interface IToken {

    /**
     * Try to cancel a command associated with given token. A command can be
     * canceled by this method only if it was not transmitted yet to remote peer
     * for execution. Successfully canceled command does not produce any result
     * messages.
     *
     * @return true if successful.
     */
    boolean cancel();
}

Version	Date	Change
0.1	2008-01-10	Initial contribution
1.0	2008-05-06	Approved
1.1	2009-03-04	Added N message

Target Communication Framework Specification

Table of Contents

Version History

Overview

Goals

Definitions

Requirements

Framework Software Design Considerations

Concurrency

Reflection

Message ordering

Transport Layer

Communication Protocol

Commands

Results

Events

Flow Control

Message Examples

Framework API

Preferred Marshaling

Locator Service