Skip to main content
aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat (limited to 'docs/TCF Specification.html')
-rw-r--r--docs/TCF Specification.html530
1 files changed, 265 insertions, 265 deletions
diff --git a/docs/TCF Specification.html b/docs/TCF Specification.html
index e808f0b5e..5b443425c 100644
--- a/docs/TCF Specification.html
+++ b/docs/TCF Specification.html
@@ -4,14 +4,14 @@
<title>Target Communication Framework Specification</title>
</head>
<body lang='EN-US'>
-
+
<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="mailto:dsdp-tcf-dev@eclipse.org">dsdp-tcf-dev@eclipse.org</a> mailing list
<h1>Table of Contents</h1>
-
+
<ul>
<li><a href='#VersionHistory'>Version History</a>
<li><a href='#Overview'>Overview</a>
@@ -70,28 +70,28 @@
<td>2009-03-04
<td>Added N message
</table>
-
+
<h1><a name='Overview'>Overview</a></h1>
-
+
<p>Today almost every device software development tool on the market has its own method
of communication with target system. Communication methods often require individual setup,
configuration and maintenance, impose unnecessary limitations.
Target Communication Framework goal is to establish common ground in
the area of communication protocols between development tools and embedded devices.</p>
-
+
<p>The goal is a single protocol used to communicate between all tools and targets:</p>
<p><img src='TCF Specification Image1.png'></p>
-
+
<h2><a name='Goals'>Goals</a></h2>
-
+
<ul type='disc'>
<li>Universal, simple, lightweight, vendor agnostic framework for tools and targets
to communicate for purpose of debugging, profiling, code patching and other device
software development needs.
-
+
<li>Single configuration per target (not per tool per target as today in most cases),
or no configuration when possible.
-
+
<li>Minimal overhead and footprint on target side.
</ul>
@@ -100,125 +100,125 @@ the area of communication protocols between development tools and embedded devic
<dl>
<dt><b>Peer:</b> <dd>communication endpoint. Both hosts and targets are called peers. A
peer can act as a client or a server depending on services it implements.
-
+
<dt><b>Service:</b> <dd>group of related commands, events and semantic define a service.
A service can be discovered, added or removed as a group at communication endpoint.
-
+
<dt><b>Message:</b> <dd>a packet of data, formatted according to framework specification
and transmitted over communication channel.
-
+
<dt><b>Channel:</b> <dd>communication link connecting two endpoints (peers). 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.
-
+
<dt><b>Command:</b> <dd>command is a message sent to remote peer in order to request some
predefined action there.
-
+
<dt><b>Result:</b> <dd>result is a message sent as a response to a command.
-
+
<dt><b>Event:</b> <dd>event is a message sent to all interested parties in order to notify
them about state changes.
</dl>
<h2><a name='Requirements'>Requirements</a></h2>
-
+
<ul type='disc'>
<li>Simple and extensible protocol.
-
+
<li>Small footprint on the target.
-
+
<li>Fully asynchronous, message based communication.
-
+
<li>Two ways of message routing:
<ul>
<li>Point to point request/response (command/result) communication.
-
+
<li>Subscription based broadcast of notifications (events).
- </ul>
-
+ </ul>
+
<li>Full duplex, symmetric communication: both host and target should be able to send
commands and events at same time, though ability to establish communication channel
can be limited to host only.
-
+
<li>For each communication channel between two peers, the framework should preserve
order of commands, results and events.
-
+
<li>Support for slow and high latency connections.
-
+
<li>Transport protocol agnostic. The framework should work well, at least, on top
of: TCP/IP, UDP, USB, RS232 and JTAG.
-
+
<li>The framework should support multiplexing, that is, single target device shared
between multiple tools at same time. To reduce footprint on the target, multiplexing
can be implemented on host if needed.
-
+
<li>Dynamic discovery of participating targets and hosts. No configuration when possible.
-
+
<li>Dynamic discovery of available services (high level protocols, command sets).
Clients can query for available services.
-
+
<li>Services can be added and removed dynamically.
-
+
<li>Framework should define a set of common high level interfaces (services). For
example: flow control, memory access, registers access, up-load mechanism, kernel
awareness, run control, target file system, console, flash programming. Implementation
of these interfaces is optional, but if provided it will support much wider compatibility
with various tools.
-
+
<li>Framework should be layered in such a way so it is possible to use different transport
- medias (e.g. TCP/IP, RS232, USB, etc) without any changes to individual services.
+ medias (e.g. TCP/IP, RS232, USB, etc) without any changes to individual services.
In other words, transport implementation should be services agnostic, and services
implementation should be transport agnostic.
-
+
<li>Each service defines how marshalling is done for command, result and event arguments.
This allows existing target agents to remain unchanged.
-
+
<li>Framework should define a preferred marshalling mechanism that new services can
use.
-
+
<li>The definition of services (groups of related commands and events) is separate
from the definition of the framework itself. The framework provides unified communication
mechanism, while services use it to communicate with its clients.
-
+
<li>Anybody (including 3rd parties) can add services without having to modify communication
protocol or framework software.
-
+
<li>The framework should support tunneling through a proxy. Proxy may be used, for
example:
-
+
<ul type='circle'>
- <li>to bridge different transport protocols, like TCP and RS232;
-
- <li>to make a RS232 or USB target connection accessible from multiple hosts;
-
+ <li>to bridge different transport protocols, like TCP and RS232;
+
+ <li>to make a RS232 or USB target connection accessible from multiple hosts;
+
<li>to access targets behind firewalls or otherwise not directly accessible
</ul>
-
+
<li>A proxy should be able to provide services in addition to those implemented by
a target. Such distribution of services allows target services to be implemented on
a host, thereby reducing the footprint on the target. For example, debug information,
stack back trace or OS awareness can be implemented by a proxy on a host. To provide
this functionality, proxy services would typically use low-level target services,
like memory access.
-
+
<li>Supports of concurrent requests. Maximum number of concurrent requests (window
size) can be limited on target side. Simple agents only have to support window size
of 1. Framework should maintain a queue of additional requests, so tools don't need
to know the window size. This may only be relevant for certain transport protocols
e.g. UDP.
-
+
<li>Events can be broadcasted at any time, i.e. no polling should be required.
-
+
<li>Protocol should support a standard mechanism of sending data larger than MTU.
</ul>
-
+
<h2><a name='Syntax'>Syntax Rules Notation</a></h2>
-
+
<p>Format of the protocol messages is defined by syntax rules. 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>&lt;token&gt;.
@@ -226,7 +226,7 @@ using a simple variant of Backus-Naur Form. In particular:</p>
of the category, for example: <b><i><font face="Courier New" size=2 color=#333399>&lt;int:
error code&gt;</font></i></b> has same meaning as <b><i><font face="Courier New" size=2 color=#333399>&lt;int&gt;</font></i></b>,
but denotes that the integer number used to indicate an &ldquo;error code&rdquo;.
-
+
<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:
@@ -237,13 +237,13 @@ using a simple variant of Backus-Naur Form. In particular:</p>
</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 a message bytes.
-
- <li>The symbol &lsquo;&bull;&rsquo; designates a zero byte.
+
+ <li>The symbol &lsquo;&bull;&rsquo; designates a zero byte.
</ul>
-
+
<h1><a name='Design'>Framework Software Design Considerations</a></h1>
<p>The framework will be packaged, distributed and installed on a host as separate
@@ -251,7 +251,7 @@ product. It should be installed as system service and require no configuration f
most common case &ndash; target connected over TCP or UDP on a local network. For more complicated
setup, framework should have easily accessible and user friendly GUI with all relevant
configuration options.</p>
-
+
<p>Framework should use a dynamic discovery protocol to locate targets and other hosts
running instances of the framework when possible, and maintain a dynamic list of available
communication endpoints, as well as lists of services available at each endpoint.
@@ -261,49 +261,49 @@ JTAG to a remote host. It should also be possible to add target configuration ma
Development tools will access this data through the Locator Service API and use it,
for example, to present a user a list of available targets that have capabilities
needed by a particular tool.</p>
-
+
<p>Framework should provide software libraries to be used by tools and target agents
developers. The libraries should be available at least for ANSI C and Java. On host
side, at least Windows, Solaris and Linux must be supported. Libraries will provide
APIs for low-level communication protocol, Locator Service, preferred marshaling and
predefined common services.</p>
-
+
<p>The proposed target communication protocol is text-based. It allows extensions,
which define messages with blocks of binary data, but it is not a recommended data
formatting, and its usage is supposed to be limited. Text-based protocols have both
advantages and disadvantages in compare with binary protocols.</p>
-
+
<p>Advantages:</p>
-
+
<ul type='disc'>
<li>The software for text-based protocols is easier to develop and debug since they
use a relatively human-friendly communication.
-
+
<li>It is possible to use huge selection of existing tools and library routines to
view, edit, validate, and transform text-based data.
-
+
<li>Text based definition is in line with current trend in Internet protocols: most
popular protocols such as SMTP and HTTP are text-based.
</ul>
-
+
<p>Disadvantages:</p>
-
+
<ul type='disc'>
<li>Text-based protocols usually need more bytes to store numerical data than binary
protocols do.
-
+
<li>Parsing of text-based data is not efficient compared to parsing of binary data
since text-based data is usually not stored in a way similar to how it is stored in
computer memory.
-
+
<li>It is seldom possible to read only part of a text-based message since the exact
byte offset to a data item is generally not known.
</ul>
-
+
<p>A possible alternative to consider is binary, variable length encoding like BaseStream.</p>
-
+
<h2><a name='Concurrency'>Concurrency</a></h2>
-
+
<p>Concurrent asynchronous communication is much faster then synchronous, because
it alleviates communication channel latency and allows better bandwidth utilization.
But it also requires proper design of framework software. Concurrency, in general,
@@ -316,7 +316,7 @@ execution path is strictly contained in predefined subset of code (compartment),
no code, except for reentrant libraries, is executed by multiple threads. Each compartment
has a message queue and other threads communicate with the compartment thread by posting
messages to the queue.</p>
-
+
<p>Framework APIs are designed to be compatible with the compartment threading model.
Hence the API functions do not contain any thread synchronization primitives to protect
against multiple threads using the functions. All framework APIs belong to a single
@@ -329,15 +329,15 @@ such as Java, this is typically done by a single callback object argument contai
both the data and the function. The result listener is called asynchronously when
the job is done. This approach is commonly known as asynchronous<b>, </b>event-driven<b>
</b>or<b> </b>callback-based<b> </b>programming<b>.</b></p>
-
+
<p>One important characteristic of an asynchronous code is that the methods defined
by the user will often be called from within the framework itself, rather than from
the user's application code. The framework often plays the role of the main program
in coordinating and sequencing application activity. This phenomenon is called Inversion
of Control (also known as the Hollywood Principle - "Don't call us, we'll call you").</p>
-
+
<h2><a name='Reflection'>Reflection</a></h2>
-
+
<p>Communication between development tools and embedded devices must allow a host
to collect target side data and build a reflection of target state. Reflection is
usually incomplete &ndash; a subset of all remote data. Reflection is always delayed &ndash; it
@@ -345,36 +345,36 @@ represents a remote peer state in the past. Reflection can be updated by polling
data changes or by listening to events (event is communication message that is sent
asynchronously by a peer to notify others about state change). Reflection is correct
if it represents a state that actually did happen on remote peer.</p>
-
+
<p>Reflection is coherent if it is exactly equal to subset of peer state at a single
moment of time and that moment of time is not too far in the past. Non-coherent reflection
can have parts of data representing peer state at different moments of time. Coherent
reflection is more valuable for a user, because non-coherent reflection can have logically
conflicting data if that data was collected at different time.</p>
-
+
<p>Traditionally, debuggers would ensure coherence of state reflection by collecting
data only while target is suspended, and flushing all (or most) reflection data (reducing
observed subset to zero) when target is resumed. This approach does not work well
for multithreaded, multicore or real time targets. Maintaining correctness and coherence
of a non-empty reflection while target is running requires additional support from
target agent, communication software and debugger itself.</p>
-
+
<p>Since remote peer state is changing over time, coherent reflection can be built
only if:</p>
-
+
<ul type='disc'>
<li>Observed subset of state is properly selected and dynamically re-selected. Observing
too much can overflow communication channel. Observing too little has little value
for a user.
-
+
<li>Observer is listening to all relevant events.
-
+
<li>Events are coming in exactly same order as corresponding changes happen.
-
+
<li>Events are properly ordered relative to other messages that carry state data.
-
+
<li>All changes in observed subset of peer state are reported by events.
-
+
<li>All event messages must either contain a complete description of a change or they
all should not contain any state data at all. If client is getting some data from
events and required to retrieve new values of other changed data by using other means
@@ -383,24 +383,24 @@ only if:</p>
Sending deltas with events is usually more efficient then using data retrieval commands
to update reflection.
</ul>
-
+
<h2><a name='Ordering'>Message ordering</a></h2>
-
+
<p>The transmission order of commands, results and events is important, it coveys
valuable information about target state transitions and it should be preserved when
possible. Consider an example:</p>
-
+
<p>Client transmits: </p>
-
+
<pre>
Command X=2
</pre>
<p>Then, as result of some activity of another client or the target itself, X is assigned
value 3.</p>
-
+
<p>Target transmits:</p>
-
+
<pre>
Event X=3
Result X=2
@@ -414,12 +414,12 @@ will have no clue what to show &ndash; 2 or 3. In fact, the client will have to
decision about each message it receives: either trust message data as correct last
known target state, or assume the message came in out-of-order and ignore it, or re-request
the information from the target.</p>
-
+
<p>Note that re-requesting data from the target, in general, does not solve the problem
of interpretation of messages when order is not preserved. For example, after sending
a request to read value of X, X could change at about the same time, and client could
receive:</p>
-
+
<pre>
Event X=2
Result X=3
@@ -431,10 +431,10 @@ last one. A client could assume value of X unknown every time it receives a noti
of X change, and then re-request the data again. But this is expensive and, if events
coming in frequently, client can end up in infinite loop re-requesting the data again
and again, and it will never have trustworthy data about current target state.</p>
-
+
<p>Developers should be careful when using multithreading or multiple queues in software
design &ndash; it can easily cause message reordering.</p>
-
+
<p>The framework itself is required to preserve message order. However, if for whatever
reason a target agent cannot preserve message order, the result will be that clients
of the service can receive messages in the wrong order. When this is the case it should
@@ -442,57 +442,57 @@ be well documented, so tools developers are aware and can make the best of the s
In most cases it will not cause any trouble, but there is no perfect way to restore
actual sequence of events and maintain data coherency after ordering was lost, and
in some cases it can severely impact tool functionality and user experience.</p>
-
+
<h1><a name='Transport'>Transport Layer</a></h1>
-
+
<p>Tools are required to be transport protocol agnostic, so most of the layer functionality
is used internally by framework and is not exposed to clients. This layer maintains
a collection of transport protocol handlers. Each handler is designed to provide:</p>
-
+
<ul type='disc'>
<li>Enumeration of available peers, including both automatically discovered and manually
configured peers. Handler fires notification events when peers are added or removed.
Enumeration can be implemented by scanning JTAG chain, by broadcasting special UDP
packet and waiting for responses, by communicating with ICE hardware, or by any other
suitable means.
-
+
<li>Bidirectional point-to-point communication of data packets. Packets are arrays
of bytes of arbitrary size.
Transport handler and underlying protocol are responsible for adding all necessary
control data, headers, error checking bits, addresses, fragmentation/defragmentation,
flow control, transmission retries and whatever necessary to ensure lossless, order-preserving
delivery of packets.
-
+
<li>Configuration UI should allow user to inspect and modify properties of both manually
configured and automatically discovered peers, setup new peers, view connections status
and statistics.
</ul>
-
+
<p>Existing service discovery protocols can be used together with the framework, for
example:</p>
-
+
<ul type='disc'>
<li>Zero Configuration Networking (Zeroconf), see <a href='http://www.zeroconf.org/'>http://www.zeroconf.org</a>;
-
+
<li>Service Location Protocol (SLP), developed by the IETF;
-
+
<li>Jini, which is Sun's Java-base approach to service discovery, see <a href='http://www.sun.com/jini'>http://www.sun.com/jini</a>;
-
+
<li>Salutation, developed by an open industry consortium, called the Salutation Consortium;
-
+
<li>Microsoft's Universal Plug and Play (UPnP), see <a href='http://www.upnp.org/'>http://www.upnp.org</a>;
-
+
<li>Bluetooth Service Discovery Protocol (SDP).
</ul>
-
+
<p>Service discovery protocols, as well as transport protocols will be supported by
framework plug-ins, they are not part of framework code itself, and they can be developed
by 3rd parties. Note that existing discovery protocols define term &ldquo;service&rdquo; differently
- as an independent communication endpoint (usually a TCP/IP port). In this document
it is called &ldquo;peer&rdquo; (host, target, communication endpoint), and a peer can provide
multiple services over single communication channel.</p>
-
+
<p>Using of standard discovery protocols should be optional, because it can potentially
cause conflict or interference between development tools and application being developed
over a use of same standard protocol &ndash; devices software often includes implementation
@@ -507,19 +507,19 @@ of the communication channel for a particular peer, and for sending and receivin
data packets. The protocol define contents of a part of a packet, the rest of the
packet is treated as array of bytes at this level. The communication protocol implementation
also provides:</p>
-
+
<ul type='disc'>
<li>Multiplexing &ndash; opening multiple channels per peer.
-
+
<li>Proxy &ndash; packet forwarding in behalf of other hosts.
</ul>
-
+
<p>Protocol defines three packet types: commands (requests), results (responses),
and events. Each packet consists of several protocol defined control fields followed
by byte array of data. Binary representation of control fields is a sequence of zero
terminated ASCII strings. Format of data array depends on a service. We recommend
using framework preferred marshaling for data formatting.</p>
-
+
<p>Syntax:</p>
<pre><b><font face="Courier New" size=2 color=#333399>
<i>&lt;message&gt;</i>
@@ -530,37 +530,37 @@ using framework preferred marshaling for data formatting.</p>
</font></b></pre>
<h2><a name='ProtocolCommands'>Commands</a></h2>
-
+
<pre><b><font face="Courier New" size=2 color=#333399>
<i>&lt;command&gt;</i>
&rArr; C &bull; <i>&lt;token&gt; </i>&bull; <i>&lt;service name&gt; </i>&bull; <i>&lt;command name&gt; </i>&bull; <i>&lt;byte array: arguments&gt;</i>
</font></b></pre>
<p>Command packets start with string &ldquo;C&rdquo;.</p>
-
+
<pre><b><font face="Courier New" size=2 color=#333399>
<i>&lt;token&gt;</i>
&rArr; <i>&lt;chars&gt;</i>
</font></b></pre>
-
+
<p>Token is unique string generated by framework for each command. It is used to match
results to commands.</p>
-
+
<pre><b><font face="Courier New" size=2 color=#333399>
<i>&lt;service name&gt;</i>
&rArr; <i>&lt;chars&gt;</i>
</font></b></pre>
-
+
<p>Service name is used to identify a service that handles the command, it is same
string as returned by Service.getName().</p>
-
+
<pre><b><font face="Courier New" size=2 color=#333399>
<i>&lt;command name&gt;</i>
&rArr; <i>&lt;chars&gt;</i>
</font></b></pre>
-
+
<p>Command name interpretation depends on a service.</p>
-
+
<p>A command should always be answered with result packed. Result does not have to
be positive &ndash; it can include an error code, or it can be special "N" result that indicates that command was not recognized,
but there always must be one. Since client
@@ -574,7 +574,7 @@ unlimited number of requests, since this will use resources in forms of memory t
store the requests and time to process them.</p>
<h2><a name='ProtocolResults'>Results</a></h2>
-
+
<pre><b><font face="Courier New" size=2 color=#333399>
<i>&lt;result&gt;</i>
&rArr; N &bull; <i>&lt;token&gt;</i> &bull;
@@ -587,23 +587,23 @@ result, and &ldquo;N&rdquo; if command is not recognized. Receiving of &ldquo;R&
There should be exactly one &ldquo;R&rdquo; or &ldquo;N&rdquo; result for each command. In addition, command execution can produce any number of
intermediate &ldquo;P&rdquo; results. &ldquo;P&rdquo; results can be sent before &ldquo;R&rdquo;, and it can serve, for
example, as command execution progress report when execution takes long time.</p>
-
+
<pre><b><font face="Courier New" size=2 color=#333399>
<i>&lt;token&gt;</i>
&rArr; <i>&lt;chars&gt;</i>
</font></b></pre>
-
+
<p>Token should match token field of one of the pending commands that produced the result.</p>
<h2><a name='ProtocolEvents'>Events</a></h2>
-
+
<pre><b><font face="Courier New" size=2 color=#333399>
<i>&lt;event&gt;</i>
&rArr; E &bull; <i>&lt;service name&gt;</i> &bull; <i>&lt;event name&gt;</i> &bull; <i>&lt;byte array: event data&gt;</i>
</font></b></pre>
<p>Event packets start with string &ldquo;E&rdquo;.</p>
-
+
<pre><b><font face="Courier New" size=2 color=#333399>
<i>&lt;service name&gt;</i>
&rArr; <i>&lt;chars&gt;</i>
@@ -611,14 +611,14 @@ example, as command execution progress report when execution takes long time.</p
<p>Service name identifies a service that fired event, same string as returned by
Service.getName().</p>
-
+
<pre><b><font face="Courier New" size=2 color=#333399>
<i>&lt;event name&gt;</i>
&rArr; <i>&lt;chars&gt;</i>
</font></b></pre>
-
+
<p>Event name meaning depends on a service.</p>
-
+
<p>Events are used to notify clients about changes in peer state. Services should
provide sufficient variety of events for clients to track remote peer state without
too much of polling. Clients, interested in a particular aspect of the target state,
@@ -637,7 +637,7 @@ force clients to poll for changes and can also degrade performance. A balanced a
is the best.</p>
<h2><a name='ProtocolFlowControl'>Flow Control</a> </h2>
-
+
<p>It often happens that one side of communication channel produces messages faster
then they can be transmitted over the channel or can be consumed by another side.
This will cause channel traffic congestion (flooding). Framework will deal with the
@@ -660,14 +660,14 @@ indicate level of congestion. When a peer receives flow control message with con
it should try to reduce its transmition speed.</p>
<h2><a name='ProtocolExamples'>Message Examples</a></h2>
-
+
<p>Examples use simplified command arguments and result data. See service description
for actual data formats.</p>
-
+
<p>Executing <b><i>suspend</i></b> command from <b><i>RunControl</i></b> service:</p>
-
+
<p>&nbsp;</p>
-
+
<pre>
Send : C 1 RunControl suspend &ldquo;Thread1&rdquo;
Receive: E RunControl suspended &ldquo;Thread1&rdquo;
@@ -675,7 +675,7 @@ Receive: R 1 &ldquo;Success&rdquo;
</pre>
<p>Same command, but target was already suspended:</p>
-
+
<pre>
Receive: E RunControl suspended &ldquo;Thread1&rdquo;
&hellip;
@@ -685,7 +685,7 @@ Receive: R 2 &ldquo;Already suspended&rdquo;
<p>Same command, but target was suspended (by another client) after sending the command,
but before command was executed: </p>
-
+
<pre>
Receive: E RunControl running &ldquo;Thread1&rdquo;
&hellip;
@@ -695,40 +695,40 @@ Receive: R 3 &ldquo;Already suspended&rdquo;
</pre>
<h2><a name='API'>Framework API</a></h2>
-
+
<pre>
<font color=#3F5FBF>/**
- *
+ *
* 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.
*/</font>
<font color=#7F0055>public class</font> Protocol {
-
+
<font color=#7F0055>private static</font> IEventQueue <i>event_queue</i>;
-
+
<font color=#3F5FBF>/**
* 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 <code>run</code> 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 <code>run</code> 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 -
+ * 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.
- *
+ *
* <font color=#7F9FBF>@param</font> event_queue - IEventQueue implementation.
*/</font>
<font color=#7F0055>public static void</font> setEventQueue(IEventQueue event_queue);
-
+
<font color=#3F5FBF>/**
* <font color=#7F9FBF>@return</font> instance of IEventQueue that should be used for TCF events.
*/</font>
<font color=#7F0055>public static</font> IEventQueue getEventQueue();
-
+
<font color=#3F5FBF>/**
* 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)
@@ -738,7 +738,7 @@ Receive: R 3 &ldquo;Already suspended&rdquo;
* <font color=#7F9FBF>@return</font> true if running on the dispatch thread.
*/</font>
<font color=#7F0055>public static boolean</font> isDispatchThread();
-
+
<font color=#3F5FBF>/**
* Causes runnable to have its run
* method called in the dispatch thread of the framework.
@@ -753,7 +753,7 @@ Receive: R 3 &ldquo;Already suspended&rdquo;
* method should be executed asynchronously.</font>
*/</font>
<font color=#7F0055>public static void</font> invokeLater(Runnable runnable);
-
+
<font color=#3F5FBF>/**
* Causes runnable to have its run
* method called in the dispatch thread of the framework.
@@ -765,21 +765,21 @@ Receive: R 3 &ldquo;Already suspended&rdquo;
*/</font>
<font color=#7F0055>public static void</font> invokeAndWait(Runnable runnable)
<font color=#7F0055>throws</font> InterruptedException;
-
+
<font color=#3F5FBF>/**
* Get instance of the framework locator service.
* The service can be used to discover available remote peers.
- *
+ *
* @return instance of ILocator.
*/</font>
<font color=#7F0055>public static</font> ILocator getLocator();
-
+
<font color=#3F5FBF>/**
* Return an array of all open channels.
* @return an array of IChannel
*/</font>
<font color=#7F0055>public static</font> IChannel[] getOpenChannels();
-
+
<font color=#3F5FBF>/**
* Interface to be implemented by clients willing to be notified when
* new TCF communication channel is opened.
@@ -787,7 +787,7 @@ Receive: R 3 &ldquo;Already suspended&rdquo;
<font color=#7F0055>public interface</font> ChannelOpenListener {
<font color=#7F0055>public void</font> onChannelOpen(IChannel channel);
}
-
+
<font color=#3F5FBF>/**
* Add a listener that will be notified when new channel is opened.
* @param listener
@@ -805,21 +805,21 @@ Receive: R 3 &ldquo;Already suspended&rdquo;
* The message is sent to all open communication channels &ndash; broadcasted.
*/</font>
<font color=#7F0055>public static void</font> sendEvent(String service, String name, byte[] data);
-
+
<font color=#3F5FBF>/**
* 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
+ * 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.
*/</font>
<font color=#7F0055>public static void</font> sync(Runnable done);
}
-
+
<font color=#3F5FBF>/**
* IChannel represents communication link connecting two endpoints (peers).
* The channel asynchroniously transmits messages: commands, results and events.
@@ -828,7 +828,7 @@ Receive: R 3 &ldquo;Already suspended&rdquo;
* ordering is guaranteed across channels.
*/</font>
<font color=#7F0055>public interface</font> IChannel {
-
+
<font color=#3F5FBF>/**
* Channel state IDs
*/</font>
@@ -836,12 +836,12 @@ Receive: R 3 &ldquo;Already suspended&rdquo;
<i><font color=#0000C0>STATE_OPENNING</font></i> = 0,
<i><font color=#0000C0>STATE_OPEN</font></i> = 1,
<i><font color=#0000C0>STATE_CLOSED</font></i> = 2;
-
+
<font color=#3F5FBF>/**
* <font color=#7F9FBF>@return</font> channel current state, see STATE_*
*/</font>
int getState();
-
+
<font color=#3F5FBF>/**
* Send command message to remote peer for execution. Commands can be queued
* locally before transmission. Sending commands too fast can fill up
@@ -851,17 +851,17 @@ Receive: R 3 &ldquo;Already suspended&rdquo;
* <font color=#7F9FBF>@param</font> name - command name
* <font color=#7F9FBF>@param</font> args - command arguments encoded into array of bytes
* <font color=#7F9FBF>@param</font> done - call back object
- * <font color=#7F9FBF>@return</font> pending command handle
+ * <font color=#7F9FBF>@return</font> pending command handle
*/</font>
IToken sendCommand(IService service, String name, <font color=#7F0055>byte</font>[] args,
ICommandListener done);
-
+
<font color=#3F5FBF>/**
* Command listener interface. Clients implement this interface
* to receive command results.
*/</font>
<font color=#7F0055>interface</font> ICommandListener {
-
+
<font color=#3F5FBF>/**
* Called when progress message (intermediate result) is received
* from remote peer.
@@ -869,7 +869,7 @@ Receive: R 3 &ldquo;Already suspended&rdquo;
* <font color=#7F9FBF>@param</font> data - progress message arguments encoded into array of bytes
*/</font>
<font color=#7F0055>void</font> progress(<font color=#7F0055>byte</font>[] data);
-
+
<font color=#3F5FBF>/**
* Called when command result received from remote peer.
* <font color=#7F9FBF>@param</font> token - command handle
@@ -884,7 +884,7 @@ Receive: R 3 &ldquo;Already suspended&rdquo;
*/</font>
<font color=#7F0055>void</font> terminated(IToken token, Exception error);
}
-
+
<font color=#3F5FBF>/**
* Send result message to remote peer. Messages can be queued locally before
* transmission. Sending messages too fast can fill up communication channel
@@ -894,26 +894,26 @@ Receive: R 3 &ldquo;Already suspended&rdquo;
* <font color=#7F9FBF>@param</font> results - result message arguments encoded into array of bytes
*/</font>
<font color=#7F0055>void</font> sendResult(IToken token, <font color=#7F0055>byte</font>[] results);
-
+
<font color=#3F5FBF>/**
* Get current level of outbound traffic congestion.
- *
+ *
* <font color=#7F9FBF>@return</font> integer value in range &ndash;100..100, where &ndash;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().
*/</font>
int getCongestion();
-
+
<font color=#3F5FBF>/**
* Channel listener interface.
*/</font>
<font color=#7F0055>interface</font> IChannelListener {
-
+
<font color=#3F5FBF>/**
* Called when a channel is opened.
*/</font>
@@ -934,26 +934,26 @@ Receive: R 3 &ldquo;Already suspended&rdquo;
*/</font>
<font color=#7F0055>void</font> congestionLevel(int level);
}
-
+
<font color=#3F5FBF>/**
* Subscribe a channel listener. The listener will be notified about changes of
* outbound traffic congestion level.
* <font color=#7F9FBF>@param</font> listener - channel listener implementation
*/</font>
<font color=#7F0055>void</font> addChannelListener(IChannelListener listener);
-
+
<font color=#3F5FBF>/**
* Remove a channel listener.
* <font color=#7F9FBF>@param</font> listener - channel listener implementation
*/</font>
<font color=#7F0055>void</font> removeChannelListener(IChannelListener listener);
-
+
<font color=#3F5FBF>/**
* Command server interface.
* This interface is to be implemented by service providers.
*/</font>
<font color=#7F0055>interface</font> ICommandServer {
-
+
<font color=#3F5FBF>/**
* Called every time a command is received from remote peer.
* <font color=#7F9FBF>@param</font> token - command handle
@@ -962,19 +962,19 @@ Receive: R 3 &ldquo;Already suspended&rdquo;
*/</font>
<font color=#7F0055>void</font> command(IToken token, String name, <font color=#7F0055>byte</font>[] data);
}
-
+
<font color=#3F5FBF>/**
* Subscribe a command server. The server will be notified about command
* messages received through this channel for given service.
* <font color=#7F9FBF>@param</font> service - local service implementation
- * <font color=#7F9FBF>@param</font> server - implementation of service commands listener
+ * <font color=#7F9FBF>@param</font> server - implementation of service commands listener
*/</font>
<font color=#7F0055>void</font> addCommandServer(IService service, ICommandServer listener);
-
+
<font color=#3F5FBF>/**
* Remove a command server.
* <font color=#7F9FBF>@param</font> service - local service implementation
- * <font color=#7F9FBF>@param</font> server - implementation of service commands listener
+ * <font color=#7F9FBF>@param</font> server - implementation of service commands listener
*/</font>
<font color=#7F0055>void</font> removeCommandServer(IService service, ICommandServer listener);
@@ -993,31 +993,31 @@ Receive: R 3 &ldquo;Already suspended&rdquo;
*/</font>
<font color=#7F0055>void</font> event(String name, <font color=#7F0055>byte</font>[] data);
}
-
+
<font color=#3F5FBF>/**
* Subscribe an event message listener for given service.
* <font color=#7F9FBF>@param</font> service - remote service proxy
- * <font color=#7F9FBF>@param</font> server - implementation of service event listener
+ * <font color=#7F9FBF>@param</font> server - implementation of service event listener
*/</font>
<font color=#7F0055>void</font> addEventListener(IService service, IEventListener listener);
-
+
<font color=#3F5FBF>/**
* Unsubscribe an event message listener for given service.
* <font color=#7F9FBF>@param</font> service - remote service proxy
- * <font color=#7F9FBF>@param</font> server - implementation of service event listener
+ * <font color=#7F9FBF>@param</font> server - implementation of service event listener
*/</font>
<font color=#7F0055>void</font> removeEventListener(IService service, IEventListener listener);
-
+
<font color=#3F5FBF>/**
* <font color=#7F9FBF>@return</font> IPeer object representing local endpoint of communication channel.
*/</font>
IPeer getLocalPeer();
-
+
<font color=#3F5FBF>/**
* <font color=#7F9FBF>@return</font> IPeer object representing remote endpoint of communication channel.
*/</font>
IPeer getRemotePeer();
-
+
<font color=#3F5FBF>/**
* <font color=#7F9FBF>@return</font> collection of services available on local peer.
*/</font>
@@ -1054,14 +1054,14 @@ Receive: R 3 &ldquo;Already suspended&rdquo;
* Return null if implementation of the interface is not available.
*/</font>
&lt;V <font color=#7F0055>extends</font> IService> V getRemoteService(Class&lt;V> service_interface);
-
+
<font color=#3F5FBF>/**
* 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.
+ * It is not allowed to register more then one proxy for a given service interface.
*/</font>
&lt;V <font color=#7F0055>extends</font> IService&gt; <font color=#7F0055>void</font> setServiceProxy(Class&lt;V&gt; service_interface, IService service_proxy);
@@ -1069,34 +1069,34 @@ Receive: R 3 &ldquo;Already suspended&rdquo;
* Close communication channel.
*/</font>
<font color=#7F0055>void</font> close();
-
+
<font color=#3F5FBF>/**
* Close channel in case of communication error.
* <font color=#7F9FBF>@param error</font> - cause of channel termination
*/</font>
<font color=#7F0055>void</font> terminate(Throwable error);
-
+
<font color=#3F5FBF>/**
* Redirect this channel to given peer using this channel remote peer locator service as a proxy.
* <font color=#7F9FBF>@param peer_</font> - peer that will become new remote communication endpoint of this channel
*/</font>
<font color=#7F0055>void</font> redirect(IPeer peer);
}
-
-
+
+
<font color=#3F5FBF>/**
* 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.
*/</font>
<font color=#7F0055>public</font> interface IToken {
-
+
<font color=#3F5FBF>/**
* 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.
- *
+ *
* <font color=#7F9FBF>@return</font> true if successful.
*/</font>
<font color=#7F0055>boolean</font> cancel();
@@ -1110,55 +1110,55 @@ Receive: R 3 &ldquo;Already suspended&rdquo;
separate from 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 to use <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>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>
+
+ <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>&lt;object&gt;</i>
&rArr; {}
&rArr; { <i>&lt;members&gt;</i> }
-
+
<i>&lt;members&gt;</i>
&rArr; <i>&lt;string&gt;</i> : <i>&lt;value&gt;</i>
&rArr; <i>&lt;members&gt;</i> , <i>&lt;string&gt;</i> : <i>&lt;value&gt;</i>
-
+
<i>&lt;array&gt;</i>
&rArr; []
&rArr; [ <i>&lt;elements&gt;</i> ]
-
+
<i>&lt;elements&gt;</i>
&rArr; <i>&lt;value&gt;</i>
&rArr; <i>&lt;elements</i>&gt; , <i>&lt;value&gt;</i>
-
+
<i>&lt;value&gt;</i>
&rArr; <i>&lt;string&gt;</i>
&rArr; <i>&lt;number&gt;</i>
@@ -1167,14 +1167,14 @@ using UTF-8 encoding.</p>
&rArr; <i>&lt;boolean&gt;</i>
&rArr; null
-<i>&lt;boolean&gt;</i>
+<i>&lt;boolean&gt;</i>
&rArr; true
&rArr; false
<i>&lt;string&gt;</i>
&rArr; ""
&rArr; " <i>&lt;chars&gt;</i> "
-
+
<i>&lt;chars&gt;</i>
&rArr; <i>&lt;char&gt;</i>
&rArr; <i>&lt;chars&gt; &lt;char&gt;</i>
@@ -1196,23 +1196,23 @@ using UTF-8 encoding.</p>
&rArr; &lt;<i>int&gt; &lt;fraction&gt;</i>
&rArr; &lt;<i>int&gt; &lt;exponent&gt;</i>
&rArr; &lt;<i>int&gt; &lt;fraction&gt; &lt;exponent&gt;</i>
-
+
<i>&lt;int&gt;</i>
&rArr; <i>&lt;digit&gt;</i>
- &rArr; &lt;<i>digit 1-9&gt; &lt;digits&gt;</i>
+ &rArr; &lt;<i>digit 1-9&gt; &lt;digits&gt;</i>
&rArr; - &lt;<i>digit&gt;</i>
&rArr; - &lt;<i>digit 1-9&gt; &lt;digits</i>&gt;
-
-<i>&lt;fraction&gt;</i>
- &rArr; . <i>&lt;digits&gt;</i>
-
-<i>&lt;exponent&gt;</i>
- &rArr; <i>&lt;e&gt;</i> <i>&lt;digits&gt;</i>
-
-<i>&lt;digits&gt;</i>
+
+<i>&lt;fraction&gt;</i>
+ &rArr; . <i>&lt;digits&gt;</i>
+
+<i>&lt;exponent&gt;</i>
+ &rArr; <i>&lt;e&gt;</i> <i>&lt;digits&gt;</i>
+
+<i>&lt;digits&gt;</i>
&rArr; <i>&lt;digit&gt;</i>
- &rArr; &lt;<i>digits&gt;</i> &lt;<i>digit&gt;</i>
-
+ &rArr; &lt;<i>digits&gt;</i> &lt;<i>digit&gt;</i>
+
<i>&lt;e&gt;</i>
&rArr; e
&rArr; e+
@@ -1224,11 +1224,11 @@ using UTF-8 encoding.</p>
</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>
[
{
@@ -1251,7 +1251,7 @@ using UTF-8 encoding.</p>
}
]
</pre>
-
+
<h1><a name='Locator'>Locator Service</a></h1>
<p>Locator Service uses transport layer to search for peers and to collect data about
@@ -1304,7 +1304,7 @@ at services it implements (use IChannel.getRemoteServices() method to get a map
<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 &bull; <i>&lt;token&gt;</i> &bull; Locator &bull; redirect &bull; <i>&lt;string: peer ID&gt;</i> &bull;
</font></b></pre>
@@ -1317,9 +1317,9 @@ Locator service starts acting as a proxy.</p>
<pre><b><font face="Courier New" size=2 color=#333399>
R &bull; <i>&lt;token&gt;</i> &bull; <i>&lt;error report&gt;</i> &bull;
</font></b></pre>
-
+
<h3><a name='LocatorCommandSync'>sync</a></h3>
-
+
<pre><b><font face="Courier New" size=2 color=#333399>
C &bull; <i>&lt;token&gt;</i> &bull; Locator &bull; sync &bull;
</font></b></pre>
@@ -1333,7 +1333,7 @@ for sync result a client makes sure that all commands, that were issued before s
<pre><b><font face="Courier New" size=2 color=#333399>
R &bull; <i>&lt;token&gt;</i> &bull;
</font></b></pre>
-
+
<h2><a name='LocatorEvents'>Locator Service Events</a></h2>
<pre><b><font face="Courier New" size=2 color=#333399>
@@ -1366,20 +1366,20 @@ E &bull; Locator &bull; peerRemoved &bull; <i>&lt;string: peer ID&gt;</i> &bull;
<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().
+ * 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
@@ -1388,7 +1388,7 @@ E &bull; Locator &bull; peerRemoved &bull; <i>&lt;string: peer ID&gt;</i> &bull;
* calling ILocator.getPeers
*/</font>
<font color=#7F0055>public interface</font> IPeer {
-
+
<font color=#7F0055>static final</font> String
<i><font color=#0000C0>ATTR_ID</font></i> = <font color=#2A00FF>"ID"</font>,
<i><font color=#0000C0>ATTR_NAME</font></i> = <font color=#2A00FF>"Name"</font>,
@@ -1398,33 +1398,33 @@ E &bull; Locator &bull; peerRemoved &bull; <i>&lt;string: peer ID&gt;</i> &bull;
<i><font color=#0000C0>ATTR_IP_ALIASES</font></i> = <font color=#2A00FF>"Aliases"</font>,
<i><font color=#0000C0>ATTR_IP_ADDRESSES</font></i> = <font color=#2A00FF>"Addresses"</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&lt;String, String&gt; 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> peer name, same as getAttributes().get(ATTR_NAME)
*/</font>
String getName();
-
+
<font color=#3F5FBF>/**
* Same as getAttributes().get(ATTR_OS_NAME)
*/</font>
String getOSName();
-
+
<font color=#3F5FBF>/**
* 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.
@@ -1433,7 +1433,7 @@ E &bull; Locator &bull; peerRemoved &bull; <i>&lt;string: peer ID&gt;</i> &bull;
*/</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
* peer's attributes and capabilities (services). Discovery mechanism depends on
@@ -1441,14 +1441,14 @@ E &bull; Locator &bull; peerRemoved &bull; <i>&lt;string: peer ID&gt;</i> &bull;
* hosts, are added to local list of peers.
* 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 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>
@@ -1460,38 +1460,38 @@ E &bull; Locator &bull; peerRemoved &bull; <i>&lt;string: peer ID&gt;</i> &bull;
* <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&lt;String,IPeer&gt; getPeers();
-
+
<font color=#3F5FBF>/**
* Redirect this service channel to given peer using this service as a proxy.
*/</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
+ * 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);
}
@@ -1500,17 +1500,17 @@ E &bull; Locator &bull; peerRemoved &bull; <i>&lt;string: peer ID&gt;</i> &bull;
* 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=#7F0055>void</font> peerAdded(IPeer peer);
-
+
<font color=#7F0055>void</font> peerRemoved(IPeer peer);
-
+
<font color=#7F0055>void</font> peerChanged(IPeer peer);
}
}
@@ -1518,4 +1518,4 @@ E &bull; Locator &bull; peerRemoved &bull; <i>&lt;string: peer ID&gt;</i> &bull;
</body>
</html>
-
+

Back to the top