diff options
| author | Eugene Tarassov | 2019-07-24 20:04:23 +0000 |
|---|---|---|
| committer | Eugene Tarassov | 2019-07-24 20:20:07 +0000 |
| commit | e86b66160bab3e7742350b0b5790fe57f772d655 (patch) | |
| tree | a78a19cded95ba70d1e50071d4cbdd90d5c1ebb0 /docs/TCF Specification.html | |
| parent | e1b87d42fd5d2d309fc39bc282765b794484de9a (diff) | |
| download | org.eclipse.tcf-e86b66160bab3e7742350b0b5790fe57f772d655.tar.gz org.eclipse.tcf-e86b66160bab3e7742350b0b5790fe57f772d655.tar.xz org.eclipse.tcf-e86b66160bab3e7742350b0b5790fe57f772d655.zip | |
TCF Docs: improved specifications of TCF services
Diffstat (limited to 'docs/TCF Specification.html')
| -rw-r--r-- | docs/TCF Specification.html | 531 |
1 files changed, 7 insertions, 524 deletions
diff --git a/docs/TCF Specification.html b/docs/TCF Specification.html index b1fac7593..6306f54db 100644 --- a/docs/TCF Specification.html +++ b/docs/TCF Specification.html @@ -7,8 +7,9 @@ <h1>Target Communication Framework Specification</h1> -<p>Copyright (c) 2007, 2008 Wind River Systems, Inc. Made available under the EPL v1.0 -<p>Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list +<p>Copyright (c) 2007-2019 Wind River Systems, Inc. and others. Made available under the EPL v1.0<br/> +Agent portion made available under your choice of EPL v1.0 or EDL v1.0 dual-license.</p> +<p>Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list</p> <h1>Table of Contents</h1> @@ -19,7 +20,6 @@ <li><a href='#Goals'>Goals</a> <li><a href='#Definitions'>Definitions</a> <li><a href='#Requirements'>Requirements</a> - <li><a href='#Syntax'>Syntax Rules Notation</a> </ul> <li><a href='#Design'>Framework Software Design Considerations</a> <ul> @@ -38,16 +38,7 @@ </ul> <li><a href='#API'>API</a> <li><a href='#JSON'>JSON - Preferred Marshaling</a> - <ul> - <li><a href='#JSONExamples'>JSON - Examples</a> - </ul> <li><a href='#Locator'>Locator Service</a> - <ul> - <li><a href='#LocatorPeer'>Peer Attributes</a> - <li><a href='#LocatorCommands'>Locator Service Commands</a> - <li><a href='#LocatorEvents'>Locator Service Events</a> - <li><a href='#LocatorAPI'>Locator Service API</a> - </ul> </ul> <h2><a name='VersionHistory'>Version History</a></h2> @@ -212,36 +203,9 @@ them about state changes. <li>Events can be broadcasted at any time, i.e. no polling should be required. <li>The protocol should support a standard mechanism of sending data larger than MTU. -</ul> - -<h2><a name='Syntax'>Syntax Rules Notation</a></h2> -<p>The protocol message format is defined by syntax rules. The syntax is described -using a simple variant of Backus-Naur Form. In particular:</p> - -<ul type='disc'> - <li>Italic lower case words in a courier font, enclosed into angular brackets, are - used to denote syntactic categories, for example: <b><i><font face="Courier New" size=2 color=#333399><token>. - </font></i></b>Category name can be followed by colon and a text, which explains the semantics - of the category, for example: <b><i><font face="Courier New" size=2 color=#333399><int: - error code></font></i></b> has same meaning as <b><i><font face="Courier New" size=2 color=#333399><int></font></i></b>, - but denotes that the integer number is used to indicate an “error code”. - - <li>A syntax rule consists of a category designation followed by one or more syntax - definitions for the category. The category name and each definition are placed on - separate lines, bullets are used to denote definitions, for example: - <pre><b><font face="Courier New" size=2 color=#333399> - <i><chars></i> - ⇒ <i><char></i> - ⇒ <i><chars> <char></i> - </font></b></pre> - - <li>Spaces are added for readability only and they are not part of the syntax. - - <li>All text in the category definition, other then categories and spaces, is UTF-8 - based representation of message bytes. - - <li>The symbol ‘•’ designates a zero byte. + <li>Format of the protocol messages is defined by syntax rules, see + <a href='TCF Syntax Rules Notation.html'>Syntax Rules Notation</a>. </ul> <h1><a name='Design'>Framework Software Design Considerations</a></h1> @@ -1109,493 +1073,12 @@ Receive: R 3 “Already suspended” <p>The TCF message data format is service specific. Since service specifications are separate from the protocol specification, a service designer can choose any data format that suits the service requirements best. However, to promote better compatibility and to -simplify service design and implementation, we recommend using <b>JSON</b> for data formatting.</p> - -<p><b>JSON</b> (pronounced like the -English given name <i>Jason</i>), which stands for "<b>J</b>ava<b>S</b>cript <b>O</b>bject -<b>N</b>otation", is a lightweight, text-based, language-independent computer data -interchange format. <b>JSON</b> is a subset of the object literal notation of JavaScript -but its use does not require JavaScript.</p> - -<p><b>JSON</b> represents data with the same basic types that programming languages -use. <b>JSON</b>'s basic types are:</p> - -<ul type='disc'> - <li>Number (integer, real, or floating-point) - - <li>String (double-quoted with backslash escapement) - - <li>Boolean (<code>true</code> and <code>false</code>) - - <li>Array (an ordered sequence of values) - - <li>Object (collection of key/value pairs) - - <li><code>null</code> - </ul> - -<p>The structures used in most programming languages easily map directly onto JSON's -structures, and back again.</p> - -<p>JSON maps data onto Unicode string. Then the string is mapped onto array of bytes -using UTF-8 encoding.</p> - -<p>JSON specification:</p> - -<pre><b><font face="Courier New" size=2 color=#333399> -<i><object></i> - ⇒ {} - ⇒ { <i><members></i> } - -<i><members></i> - ⇒ <i><string></i> : <i><value></i> - ⇒ <i><members></i> , <i><string></i> : <i><value></i> - -<i><array></i> - ⇒ [] - ⇒ [ <i><elements></i> ] - -<i><elements></i> - ⇒ <i><value></i> - ⇒ <i><elements</i>> , <i><value></i> - -<i><value></i> - ⇒ <i><string></i> - ⇒ <i><number></i> - ⇒ <i><object></i> - ⇒ <i><array></i> - ⇒ <i><boolean></i> - ⇒ null - -<i><boolean></i> - ⇒ true - ⇒ false - -<i><string></i> - ⇒ "" - ⇒ " <i><chars></i> " - -<i><chars></i> - ⇒ <i><char></i> - ⇒ <i><chars> <char></i> - -<i><char</i>> - ⇒ <i><any Unicode except " or \ or control></i> - ⇒ \"<i></i> - ⇒ \\<i></i> - ⇒ \/<i></i> - ⇒ \b<i></i> - ⇒ \f<i></i> - ⇒ \n<i></i> - ⇒ \r<i></i> - ⇒ \t<i></i> - ⇒ \u <i><four-hex-digits></i> - -<i><number</i>> - ⇒ <i><int></i> - ⇒ <<i>int> <fraction></i> - ⇒ <<i>int> <exponent></i> - ⇒ <<i>int> <fraction> <exponent></i> - -<i><int></i> - ⇒ <i><digit></i> - ⇒ <<i>digit 1-9> <digits></i> - ⇒ - <<i>digit></i> - ⇒ - <<i>digit 1-9> <digits</i>> - -<i><fraction></i> - ⇒ . <i><digits></i> - -<i><exponent></i> - ⇒ <i><e></i> <i><digits></i> - -<i><digits></i> - ⇒ <i><digit></i> - ⇒ <<i>digits></i> <<i>digit></i> - -<i><e></i> - ⇒ e - ⇒ e+ - ⇒ e- - ⇒ E - ⇒ E+ - ⇒ E- - -</font></b></pre> - -<p>See <a href='http://www.json.org/'>www.json.org</a> for more details.</p> - -<h2><a name='JSONExamples'>Examples</a></h2> - -<p>This is a JSON array containing two objects:</p> - -<pre> - [ - { - "Precision": "zip", - "Latitude": 37.7668, - "Longitude": -122.3959, - "City": "SAN FRANCISCO", - "State": "CA", - "Zip": "94107", - "Country": "US" - }, - { - "Precision": "zip", - "Latitude": 37.371991, - "Longitude": -122.026020, - "City": "SUNNYVALE", - "State": "CA", - "Zip": "94085", - "Country": "US" - } - ] -</pre> +simplify service design and implementation, we recommend using <a href='TCF JSON.html'>JSON</a> for data formatting.</p> <h1><a name='Locator'>Locator Service</a></h1> <p>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. <font color=red>Security? </font>Automatically discovered -targets require no further configuration. Additional targets can be configured manually.</p> - -<p>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.</p> - -<h2><a name='LocatorPeer'>Peer Attributes</a></h2> - -<p><i><object: peer data></i> is collection of peer attributes. It should, at least, contain member -<b><font face="Courier New" size=2 color=#333399>"ID" : <i><string></i></font></b>. -It can also contain a number of components describing peer properties and capabilities. -Predefined attributes are:</p> - -<ul> - <li><code><b><font face="Courier New" size=2 color=#333399>"ID" : <i><string></i></font></b></code> - - unique ID of the peer. - - <li><code><b><font face="Courier New" size=2 color=#333399>"ServiceManagerID" : <i><string></i></font></b></code> - - unique ID of service manager that is represented by this peer. - - <li><code><b><font face="Courier New" size=2 color=#333399>"AgentID" : <i><string></i></font></b></code> - - agent unique ID. - - <li><code><b><font face="Courier New" size=2 color=#333399>"Name" : <i><string></i></font></b></code> - - human readable peer name. - - <li><code><b><font face="Courier New" size=2 color=#333399>"OSName" : <i><string></i></font></b></code> - - peer OS name, if applicable. - - <li><code><b><font face="Courier New" size=2 color=#333399>"TransportName" : <i><string></i></font></b></code> - - name of a trasport protocol to use to connect to this peer, for example: TCP. - - <li><code><b><font face="Courier New" size=2 color=#333399>"Host" : <i><string></i></font></b></code> - - peer host name, if transport is TCP or UDP. - - <li><code><b><font face="Courier New" size=2 color=#333399>"Aliases" : <i><string></i></font></b></code> - - peer host name aliases, if transport is TCP or UDP. - - <li><code><b><font face="Courier New" size=2 color=#333399>"Addresses" : <i><string></i></font></b></code> - - peer IP addresses, if transport is TCP or UDP. - - <li><code><b><font face="Courier New" size=2 color=#333399>"Port" : <i><string></i></font></b></code> - - peer port number, if transport is TCP or UDP. -</ul> - -<p>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).</p> - -<h2><a name='LocatorCommands'>Locator Service Commands</a></h2> - -<h3><a name='LocatorCommandRedirect'>redirect</a></h3> - -<pre><b><font face="Courier New" size=2 color=#333399> -C • <i><token></i> • Locator • redirect • <i><peer></i> • - -<i><peer></i> - ⇒ <i><string: peer ID></i> - ⇒ <i><object: peer data></i> -</font></b></pre> - -<p>The command redirects the channel to become connected to the given peer. -The Locator service starts acting as a proxy.</p> - -<p>Reply:</p> - -<pre><b><font face="Courier New" size=2 color=#333399> -R • <i><token></i> • <i><error report></i> • -</font></b></pre> - -<h3><a name='LocatorCommandSync'>sync</a></h3> - -<pre><b><font face="Courier New" size=2 color=#333399> -C • <i><token></i> • Locator • sync • -</font></b></pre> - -<p>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.</p> - -<p>Reply:</p> - -<pre><b><font face="Courier New" size=2 color=#333399> -R • <i><token></i> • -</font></b></pre> - -<h2><a name='LocatorEvents'>Locator Service Events</a></h2> - -<pre><b><font face="Courier New" size=2 color=#333399> -E • Locator • Hello • <i><array: service names></i> • -E • Locator • peerAdded • <i><object: peer data></i> • -E • Locator • peerChanged • <i><object: peer data></i> • -E • Locator • peerRemoved • <i><string: peer ID></i> • -E • Locator • peerHeartBeat • <i><string: peer ID></i> • -</font></b></pre> - -<dl> - <dt><b>Hello</b> - <dd>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. - <dt><b>peerAdded</b> - <dd>is sent when the service discovers a new peer. - <dt><b>peerChanged</b> - <dd>is sent when peer attributes change. - <dt><b>peerRemoved</b> - <dd>is sent when the service deletes information about a peer. - <dt><b>peerHeartBeat</b> - <dd>is sent periodically when the service receives a communication from the peer - that confirms that the peer is still alive. -</dl> - -<h2><a name='LocatorAPI'>Locator Service API</a></h2> - -<pre> -<font color=#3F5FBF>/** - * 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(). - */</font> -<font color=#7F0055>public</font> interface IService { - - <font color=#3F5FBF>/** - * Get unique name of this service. - */</font> - String getName(); -} - -<font color=#3F5FBF>/** - * 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. - */</font> -<font color=#7F0055>public interface</font> IPeer { - - <font color=#3F5FBF>/** - * Peer property names. Implementation can define additional properties. - */</font> - <font color=#7F0055>static final</font> String - <font color=#3F5FBF>/** Peer unique ID */</font> - <i><font color=#0000C0>ATTR_ID</font></i> = <font color=#2A00FF>"ID"</font>, - - <font color=#3F5FBF>/** Unique ID of service manager that is represented by this peer */</font> - <i><font color=#0000C0>ATTR_SERVICE_MANGER_ID</font></i> = <font color=#2A00FF>"ServiceManagerID"</font>, - - <font color=#3F5FBF>/** Agent unique ID */</font> - <i><font color=#0000C0>ATTR_AGENT_ID</font></i> = <font color=#2A00FF>"AgentID"</font>, - - <font color=#3F5FBF>/** Peer name */</font> - <i><font color=#0000C0>ATTR_NAME</font></i> = <font color=#2A00FF>"Name"</font>, - - <font color=#3F5FBF>/** Name of the peer operating system */</font> - <i><font color=#0000C0>ATTR_OS_NAME</font></i> = <font color=#2A00FF>"OSName"</font>, - - <font color=#3F5FBF>/** Transport name, for example TCP, SSL */</font> - <i><font color=#0000C0>ATTR_TRANSPORT_NAME</font></i> = <font color=#2A00FF>"TransportName"</font>, - - <font color=#3F5FBF>/** If present, indicates that the peer can forward traffic to other peers */</font> - <i><font color=#0000C0>ATTR_PROXY</font></i> = <font color=#2A00FF>"Proxy"</font>, - - <font color=#3F5FBF>/** Host DNS name or IP address */</font> - <i><font color=#0000C0>ATTR_IP_HOST</font></i> = <font color=#2A00FF>"Host"</font>, - - <font color=#3F5FBF>/** Optional list of host aliases */</font> - <i><font color=#0000C0>ATTR_IP_ALIASES</font></i> = <font color=#2A00FF>"Aliases"</font>, - - <font color=#3F5FBF>/** Optional list of host addresses */</font> - <i><font color=#0000C0>ATTR_IP_ADDRESSES</font></i> = <font color=#2A00FF>"Addresses"</font>, - - <font color=#3F5FBF>/** IP port number, must be decimal number */</font> - <i><font color=#0000C0>ATTR_IP_PORT</font></i> = <font color=#2A00FF>"Port"</font>; - - - <font color=#3F5FBF>/** - * <font color=#7F9FBF>@return</font> map of peer attributes - */</font> - Map<String, String> getAttributes(); - - <font color=#3F5FBF>/** - * <font color=#7F9FBF>@return</font> peer unique ID, same as getAttributes().get(ATTR_ID) - */</font> - String getID(); - - <font color=#3F5FBF>/** - * <font color=#7F9FBF>@return</font> service manager unique ID, same as getAttributes().get(ATTR_SERVICE_MANAGER_ID) - */</font> - String getServiceManagerID(); - - <font color=#3F5FBF>/** - * <font color=#7F9FBF>@return</font> agent unique ID, same as getAttributes().get(ATTR_AGENT_ID) - */</font> - String getAgentID(); - - <font color=#3F5FBF>/** - * <font color=#7F9FBF>@return</font> peer name, same as getAttributes().get(ATTR_NAME) - */</font> - String getName(); - - <font color=#3F5FBF>/** - * <font color=#7F9FBF>@return</font> agent OS name, same as getAttributes().get(ATTR_OS_NAME) - */</font> - String getOSName(); - - <font color=#3F5FBF>/** - * <font color=#7F9FBF>@return</font> transport name, same as getAttributes().get(ATTR_TRANSPORT_NAME) - */</font> - String getTransportName(); - - <font color=#3F5FBF>/** - * 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. - */</font> - IChannel openChannel() <font color=#7F0055>throws</font> IOException; -} - -<font color=#3F5FBF>/** - * ILocator service uses transport layer to search for peers and to collect data about - * peers 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). - */</font> -<font color=#7F0055>public interface</font> ILocator <font color=#7F0055>extends</font> IService { - - <font color=#7F0055>static final</font> String <i><font color=#0000C0>NAME</font></i> = <font color=#2A00FF>"Locator"</font>; - - <font color=#3F5FBF>/** - * Auto-configuration command and response codes. - */</font> - <font color=#7F0055>static final int</font> - <i><font color=#0000C0>CONF_REQ_INFO</font></i> = 1, - <i><font color=#0000C0>CONF_PEER_INFO</font></i> = 2, - <i><font color=#0000C0>CONF_REQ_SLAVES</font></i> = 3, - <i><font color=#0000C0>CONF_SLAVES_INFO</font></i> = 4; - - <font color=#3F5FBF>/** - * <font color=#7F9FBF>@return</font> Locator service name: "Locator" - */</font> - String getName(); - - <font color=#3F5FBF>/** - * 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 - */</font> - Map<String,IPeer> getPeers(); - - <font color=#3F5FBF>/** - * Redirect this service channel to given peer using this service as a proxy. - * @param peer_id - Peer ID. - */</font> - IToken redirect(String peer_id, DoneRedirect done); - - <font color=#7F0055>interface</font> DoneRedirect { - <font color=#7F0055>void</font> doneRedirect(IToken token, Exception error); - } - - <font color=#3F5FBF>/** - * 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.tm.tcf.protocol.Protocol}. - */</font> - IToken sync(DoneSync done); - - <font color=#7F0055>interface</font> DoneSync { - <font color=#7F0055>void</font> doneSync(IToken token); - } - - <font color=#3F5FBF>/** - * Add a listener for locator service events. - */</font> - <font color=#7F0055>void</font> addListener(Listener listener); - - <font color=#3F5FBF>/** - * Remove a listener for locator service events. - */</font> - <font color=#7F0055>void</font> removeListener(Listener listener); - - <font color=#7F0055>interface</font> Listener { - <font color=#3F5FBF>/** - * A new peer is added into locator peer table. - * @param peer - */</font> - <font color=#7F0055>void</font> peerAdded(IPeer peer); - - <font color=#3F5FBF>/** - * Peer attributes have changed. - * @param peer - */</font> - <font color=#7F0055>void</font> peerChanged(IPeer peer); - - <font color=#3F5FBF>/** - * A peer is removed from locator peer table. - * @param id - peer ID - */</font> - <font color=#7F0055>void</font> peerRemoved(String id); - - <font color=#3F5FBF>/** - * Peer heart beat detected. - * @param id - peer ID - */</font> - <font color=#7F0055>void</font> peerHeartBeat(String id); - } -} -</pre> +the peer's attributes and capabilities (services), see <a href='TCF Service - Locator.html'>Locator Service</a>.</p> </body> </html> |