Target Communication Framework Services - Locator

Locator Service

Version History

Version Date Change
1.0 2008-05-06 Initial

Overview

The Locator service uses the transport layer to search for peers and to collect data about the peer's attributes and capabilities (services). The discovery mechanism depends on the transport protocol and is part of that protocol handler. Targets, known by other hosts, are added to local list of peers. Security? Automatically discovered targets require no further configuration. Additional targets can be configured manually.

All TCF peers must implement Locator service. The implementation is part of the framework itself. It is the only required service, all other services are optional and, formally, not part of the framework.

Peer Attributes

<object: peer data> is collection of peer attributes. It should, at least, contain member "ID" : <string>. It can also contain a number of components describing peer properties and capabilities. Predefined attributes are:

Most clients do not need to know any peer attributes other than ID and Name. Clients are expected to call the IPeer.openChannel() method and let the framework check peer attributes and create appropriate communication channel that is best suited for communication with the peer. After a channel is established, a client can learn the peer capabilities by looking at what services it implements (use IChannel.getRemoteServices() method to get a map of services).

The service uses standard format for error reports, see Error Report Format.

Commands

redirect


C • <token> • Locator • redirect • <peer> •

<peer>
    ⇒ <string: peer ID>
    ⇒ <object: peer data>

The command redirects the channel to become connected to the given peer. The Locator service starts acting as a proxy.

Reply:


R • <token> • <error report> •

sync


C • <token> • Locator • sync •

The sync command does nothing and simply returns back an empty result. The command is used for cross channel synchronization. Since commands are executed in order they were issued, by waiting for sync result a client makes sure that all commands, that were issued before sync, are fully processed.

Reply:


R • <token> •

Get Agent ID


C • <token> • Locator • getAgentID •

Get agent ID of the agent providing the locator service. The agent ID can be used to identify the agent among all the peers.

Reply:


R • <token> • <error report> • <string: agent ID> •

Locator Service Events


E • Locator • Hello • <array: service names> •
E • Locator • peerAdded • <object: peer data> •
E • Locator • peerChanged • <object: peer data> •
E • Locator • peerRemoved • <string: peer ID> •
E • Locator • peerHeartBeat • <string: peer ID> •
Hello
is the first message sent by the framework after establishing a communication channel. The message lets other side of the channel know capabilities of this peer. Message data consists of an array of service names that are provided by the peer. The service name list is a complete and unambiguous declaration of peer's capabilities. To avoid ambiguity, different services (even slightly different, like versions of same service) must have different names. Framework delays all other communications between peers until exchange of Hello messages is complete.
peerAdded
is sent when the service discovers a new peer.
peerChanged
is sent when peer attributes change.
peerRemoved
is sent when the service deletes information about a peer.
peerHeartBeat
is sent periodically when the service receives a communication from the peer that confirms that the peer is still alive.

Interfaces

/**
 * Base interface for all service interfaces. A client can get list of available services
 * by calling IChannel.getLocalServices() and IChannel.getRemoteServices().
 *
 * Remote services are represented by a proxy objects that implement service interfaces by
 * translating method calls to TCF messages and sending them to a remote peer.
 * When communication channel is open, TCF automatically creates proxies for standard services.
 * TCF clients can provides addition proxies for non-standard services by calling IChannel.setServiceProxy().
 */
public interface IService {

    /**
     * Get unique name of this service.
     */
    String getName();
}

/**
 * Both hosts and targets are represented by objects
 * implementing IPeer interface. A peer can act as host or
 * target depending on services it implements.
 * List of currently known peers can be retrieved by
 * calling ILocator.getPeers()
 *
 * A TCF agent houses one or more service managers. A service manager has a one or more
 * services to expose to the world. The service manager creates one or more peers
 * to represent itself, one for every access path the agent is
 * reachable by. For example, in agents accessible via TCP/IP, the
 * service manger would create a peer for every subnet it wants to participate in.
 * All peers of particular service manager represent identical sets of services.
 *
 * @noimplement This interface is not intended to be implemented by clients.
 * Client can extends the abstract IPeer implementation: AbstractPeer.
 */
public interface IPeer {

    /**
     * Peer property names. Implementation can define additional properties.
     */
    static final String
        /** Peer unique ID */
        ATTR_ID = "ID",

        /** Unique ID of service manager that is represented by this peer */
        ATTR_SERVICE_MANGER_ID = "ServiceManagerID",

        /** Agent unique ID */
        ATTR_AGENT_ID = "AgentID",

        /** Peer name */
        ATTR_NAME = "Name",

        /** Name of the peer operating system */
        ATTR_OS_NAME = "OSName",

        /** Transport name, for example TCP, SSL */
        ATTR_TRANSPORT_NAME = "TransportName",

        /** If present, indicates that the peer can forward traffic to other peers */
        ATTR_PROXY = "Proxy",

        /** Host DNS name or IP address */
        ATTR_IP_HOST = "Host",

        /** Optional list of host aliases */
        ATTR_IP_ALIASES = "Aliases",

        /** Optional list of host addresses */
        ATTR_IP_ADDRESSES = "Addresses",

        /** IP port number, must be decimal number */
        ATTR_IP_PORT = "Port";


    /**
     * @return map of peer attributes
     */
    Map<String, String> getAttributes();

    /**
     * @return peer unique ID, same as getAttributes().get(ATTR_ID)
     */
    String getID();

    /**
     * @return service manager unique ID, same as getAttributes().get(ATTR_SERVICE_MANAGER_ID)
     */
    String getServiceManagerID();

    /**
     * @return agent unique ID, same as getAttributes().get(ATTR_AGENT_ID)
     */
    String getAgentID();

    /**
     * @return peer name, same as getAttributes().get(ATTR_NAME)
     */
    String getName();

    /**
     * @return agent OS name, same as getAttributes().get(ATTR_OS_NAME)
     */
    String getOSName();

    /**
     * @return transport name, same as getAttributes().get(ATTR_TRANSPORT_NAME)
     */
    String getTransportName();

    /**
     * Open channel to communicate with this peer.
     * Note: the channel is not fully open yet when this method returns.
     * It's state is IChannel.STATE_OPENNING.
     * Protocol.Listener will be called when the channel will be opened or closed.
     */
    IChannel openChannel() throws IOException;
}

API

/**
 * ILocator service uses transport layer to search for peers and to collect data about
 * peer's attributes and capabilities (services). Discovery mechanism depends on transport protocol
 * and is part of that protocol handler. Targets, known to other hosts, can be found through
 * remote instances of ILocator service. Automatically discovered targets require no further
 * configuration. Additional targets can be configured manually.
 *
 * Clients should use Protocol.getLocator() to obtain local instance of ILocator,
 * then ILocator.getPeers() can be used to get list of available peers (hosts and targets).
 *
 * @noimplement This interface is not intended to be implemented by clients.
 */
public interface ILocator extends IService {

    static final String NAME = "Locator";

    /**
     * Peer data retention period in milliseconds.
     */
    static final long DATA_RETENTION_PERIOD = 60 * 1000;

    /**
     * Auto-configuration protocol version.
     */
    static char CONF_VERSION = '2';

    /**
     * Auto-configuration command and response codes.
     */
    static final int
        CONF_REQ_INFO = 1,
        CONF_PEER_INFO = 2,
        CONF_REQ_SLAVES = 3,
        CONF_SLAVES_INFO = 4,
        CONF_PEERS_REMOVED = 5;

    /**
     * @return Locator service name: "Locator"
     */
    String getName();

    /**
     * Get map (ID -> IPeer) of available peers (hosts and targets).
     * The method return cached (currently known to the framework) list of peers.
     * The list is updated according to event received from transport layer
     */
    Map<String,IPeer> getPeers();

    /**
     * Redirect this service channel to given peer using this service as a proxy.
     * @param peer_id - Peer ID.
     */
    IToken redirect(String peer_id, DoneRedirect done);

    /**
     * Redirect this service channel to given peer using this service as a proxy.
     * @param peer - Peer attributes.
     */
    IToken redirect(Map<String,String> peer, DoneRedirect done);

    interface DoneRedirect {
        void doneRedirect(IToken token, Exception error);
    }

    /**
     * Call back after TCF messages sent to this target up to this moment are delivered.
     * 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 channel synchronization and should not call this method.
     *
     * @param done will be executed by dispatch thread after communication
     * messages are delivered to corresponding targets.
     *
     * This is internal API, TCF clients should use {@code org.eclipse.tcf.protocol.Protocol}.
     */
    IToken sync(DoneSync done);

    interface DoneSync {
        void doneSync(IToken token);
    }

    /**
     * Get agent ID of the agent providing the locator service.
     *
     * The agent ID can be used to identify the agent among all the peers
     * returned by {@link #getPeers()}.
     */
    IToken getAgentID(DoneGetAgentID done);

    interface DoneGetAgentID {
        void doneGetAgentID(IToken token, Exception error, String agentID);
    }

    /**
     * Add a listener for ILocator service events.
     */
    void addListener(LocatorListener listener);

    /**
     * Remove a listener for ILocator service events.
     */
    void removeListener(LocatorListener listener);

    /**
     * ILocator service event listener interface
     */
    interface LocatorListener {
        /**
         * A new peer is added into locator peer table.
         * @param peer
         */
        void peerAdded(IPeer peer);

        /**
         * Peer attributes have changed.
         * @param peer
         */
        void peerChanged(IPeer peer);

        /**
         * A peer is removed from locator peer table.
         * @param id - peer ID
         */
        void peerRemoved(String id);

        /**
         * Peer heart beat detected.
         * @param id - peer ID
         */
        void peerHeartBeat(String id);
    }
}