diff options
Diffstat (limited to 'docs/TCF Specification.html')
| -rw-r--r-- | docs/TCF Specification.html | 1407 |
1 files changed, 1407 insertions, 0 deletions
diff --git a/docs/TCF Specification.html b/docs/TCF Specification.html new file mode 100644 index 000000000..2aec03f3f --- /dev/null +++ b/docs/TCF Specification.html @@ -0,0 +1,1407 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<html> +<head> + <title>Target Communication Framework Specification</title> +</head> +<body lang='EN-US'> + +<h1>Target Communication Framework Specification</h1> + +<p>Copyright (c) 2007 Wind River Systems, Inc. Made available under the EPL v1.0 +<p>Direct comments, questions to the <a href="mailto:dsdp-tm-dev@eclipse.org">dsdp-tm-dev@eclipse.org</a> mailing list + +<h1>Table of Contents</h1> + +<ul> + <li><a href='#Overview'>Overview</a> + <ul> + <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> + <li><a href='#Concurrency'>Concurrency</a> + <li><a href='#Reflection'>Reflection</a> + <li><a href='#Ordering'>Message ordering</a> + </ul> + <li><a href='#Transport'>Transport Layer</a> + <li><a href='#Protocol'>Communication Protocol</a> + <ul> + <li><a href='#ProtocolCommands'>Commands</a> + <li><a href='#ProtocolResults'>Results</a> + <li><a href='#ProtocolEvents'>Events</a> + <li><a href='#ProtocolFlowControl'>Flow Control</a> + <li><a href='#ProtocolExamples'>Examples</a> + </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> + +<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> + +<h2><a name='Definitions'>Definitions</a></h2> + +<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> + + <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. + 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 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><token>. + </font></i></b>Category name can be followed by colon and a text, which explains 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 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> + <font face=Wingdings>Ø</font> <i><char></i> + <font face=Wingdings>Ø</font> <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 a message bytes. + + <li>The symbol ‘•’ 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 +product. It should be installed as system service and require no configuration for +most common case – 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. +Host discovery is needed to locate hosts able to proxy communications for targets, +which are not accessible otherwise - for example, targets connected with RS232 or +JTAG to a remote host. It should also be possible to add target configuration manually. +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, +implies multithreading. However, systems developed with global multithreading, are +often unreliable and prone to different kinds of thread synchronization problems, +which are often very difficult to locate and resolve. We therefore strongly recommend +that the software is designed to follow the compartment threading model, which simplifies +thread synchronization and promotes reliable software design. In this model each thread +execution path is strictly contained in predefined subset of code (compartment), and +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 +compartment and should be used by a single thread. The same thread is used to dispatch +events and command results. Concurrency is achieved by declaring API functions to +be asynchronous. Asynchronous functions do not have any return value, and returns +immediately, most of the time before the intended job is done. They take additional +arguments to specify a callback function and callback data. In object-oriented languages +such as Java, this is typically done by a single callback object argument containing +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 – a subset of all remote data. Reflection is always delayed – it +represents a remote peer state in the past. Reflection can be updated by polling for +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 + (commands), the reflection will not be coherent at least until such retrieval is complete. + And if such periods of data retrieval overlap, the reflection will never be coherent. + 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 +</pre> + +<p>Now client has to show value of X to a user. If the order of messages is preserved, +the client will know that command was executed <i>after</i> X was assigned 3, the +last message contains last known value of X and 2 is the correct value to show. If +the target is allowed to transmit events and results in arbitrary order, the client +will have no clue what to show – 2 or 3. In fact, the client will have to make a tough +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 + Event X=4 +</pre> + +<p>If order is not preserved, it is still impossible to tell which value of X is the +last one. A client could assume value of X unknown every time it receives a notification +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 – 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 +be well documented, so tools developers are aware and can make the best of the situation. +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 “service” differently +- as an independent communication endpoint (usually a TCP/IP port). In this document +it is called “peer” (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 – devices software often includes implementation +of service discovery protocols as part of application code to support their main functions. +</p> + +<h1><a name='Protocol'>Communication Protocol</a></h1> + +<p>The communication protocol defines data packets properties and roles common for +all services. The communication protocol API provides functions for opening and /closing +of the communication channel for a particular peer, and for sending and receiving +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 – opening multiple channels per peer. + + <li>Proxy – 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><message></i> + <font face=Wingdings>Ø</font> <i><command></i> + <font face=Wingdings>Ø</font> <i><result></i> + <font face=Wingdings>Ø</font> <i><event></i> + <font face=Wingdings>Ø</font> <i><flow control message></i> +</font></b></pre> + +<h2><a name='ProtocolCommands'>Commands</a></h2> + +<pre><b><font face="Courier New" size=2 color=#333399> +<i><command></i> + <font face=Wingdings>Ø</font> C • <i><token> </i>• <i><service name> </i>• <i><command name> </i>• <i><byte array: arguments></i> +</font></b></pre> + +<p>Command packets start with string “C”.</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +<i><token></i> + <font face=Wingdings>Ø</font> <i><chars></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><service name></i> + <font face=Wingdings>Ø</font> <i><chars></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><command name></i> + <font face=Wingdings>Ø</font> <i><chars></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 – it can include an error code, but there always must be one. Since client +cannot detect that a response is missing, if for some reasons peer is not able to +answer a command, it should consider such situation a fatal communication error and +it must shutdown the communication channel. It is not necessary to wait for result +before sending next command. In fact, sending multiple commands in a burst can greatly +improve performance, especially when connection has high latency. At the same time, +clients should be carefully designed to avoid flooding the communication channel with +unlimited number of requests, since this will use resources in forms of memory to +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><result></i> + <font face=Wingdings>Ø</font> R • <i><token></i> • <i><byte array: result data></i> + <font face=Wingdings>Ø</font> P • <i><token></i> • <i><byte array: result data></i> +</font></b></pre> + +<p>Result packets start with string “P” for intermediate result and “R” for final +result. Receiving of “R” result concludes execution of corresponding command. +There should be exactly one “R” result for each command. In addition, command execution can produce any number of +intermediate “P” results. “P” results can be sent before “R”, 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><token></i> + <font face=Wingdings>Ø</font> <i><chars></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><event></i> + <font face=Wingdings>Ø</font> E • <i><service name></i> • <i><event name></i> • <i><byte array: event data></i> +</font></b></pre> + +<p>Event packets start with string “E”.</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +<i><service name></i> + <font face=Wingdings>Ø</font> <i><chars></i> +</font></b></pre> + +<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><event name></i> + <font face=Wingdings>Ø</font> <i><chars></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, +should have a “reflection” (or “model”) of that state and update the reflection by +listening for relevant events. If a service implements a command that changes a particular +aspect of peers state, then, normally, it should also generate notifications event +when that same part of the state changes and it should provide a command to retrieve +current value of the state – to be used by clients to initialize the reflection. Service +events are defined statically, together with commands. The framework does not do any +event processing besides delivering them to clients, however a service can define +additional event related functionality if necessary, for example, commands for event +filtering, enabling, disabling, registration, etc. Care should be taken when designing +events for a service - if events are sent too frequently, they will cause flooding +of the communication channels and degrade performance. However, too few events will +force clients to poll for changes and can also degrade performance. A balanced approach +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 +problem and slow down transmitting side by blocking execution inside sendEvent(), +sendCommand() and sendResult() functions when message buffers are full. However, in +many cases, it is not the best way to handle congestion. For example, it can make +a tool UI appear locked for prolonged time or it can break target software if it is +designed to work in real time. Clients can use flow control events to implement advanced +techniques to handle traffic congestion, for example, message coalescing, switching +to less detailed messages, etc.</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +<i><flow control message></i> + <font face=Wingdings>Ø</font> F • <i><int: traffic congestion level></i> • +</font></b></pre> + +<p>Traffic congestion level value is in range –100..100, where –100 means no pending +messages (no traffic), 0 means optimal load, and positive numbers +indicate level of congestion. When a peer receives flow control message with congestion level > 0 +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> </p> + +<pre> +Send : C 1 RunControl suspend “Thread1” +Receive: E RunControl suspended “Thread1” +Receive: R 1 “Success” +</pre> + +<p>Same command, but target was already suspended:</p> + +<pre> +Receive: E RunControl suspended “Thread1” +… +Send : C 2 RunControl suspend “Thread1” +Receive: R 2 “Already suspended” +</pre> + +<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 “Thread1” +… +Send : C 3 RunControl suspend “Thread1” +Receive: E RunControl suspended “Thread1” +Receive: R 3 “Already suspended” +</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 - + * 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) + * on dispatch thread. + * This method is thread-safe. + * + * <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. + * Runnables are dispatched in same order as queued. + * If invokeLater is called from the dispatching thread + * the <i>runnable.run()</i> will still be deferred until + * all pending events have been processed. + * + * This method can be invoked from any thread. + * + * <font color=#7F9FBF>@param runnable</font> the Runnable whose run + * 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. + * Calling thread is suspended util the method is executed. + * This method is thread-safe. + * + * <font color=#7F9FBF>@param runnable</font> the Runnable whose run + * method should be executed on dispatch thread. + */</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. + */</font> + <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 + */</font> + <font color=#7F0055>public static void</font> addChannelOpenListener(ChannelOpenListener listener); + + <font color=#3F5FBF>/** + * Remove channel opening listener. + * @param listener + */</font> + <font color=#7F0055>public static void</font> removeChannelOpenListener(ChannelOpenListener listener); + + <font color=#3F5FBF>/** + * Transmit TCF event message. + * The message is sent to all open communication channels – 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 + * 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. + * 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. + */</font> +<font color=#7F0055>public interface</font> IChannel { + + <font color=#3F5FBF>/** + * Channel state IDs + */</font> + <font color=#7F0055>static final</font> int + <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 + * communication channel buffers. Calling thread will be blocked until + * enough buffer space is freed up by transmitting pending messages. + */</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. + */</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> + <font color=#7F0055>void</font> result(<font color=#7F0055>byte</font>[] data); + } + + <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 + * buffers. Calling thread will be blocked until enough buffer space is + * freed up by transmitting pending messages. + */</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 –100..100, where –100 means no pending + * messages (no traffic), 0 means optimal load, and positive numbers + * indicate level of congestion. + * + * Note: inbound traffic congestion is detected by framework and reported to + * remote peer without client needed to be involved. + */</font> + int getCongestion(); + + <font color=#3F5FBF>/** + * Channel listener interface. + */</font> + <font color=#7F0055>interface</font> IChannelListener { + + <font color=#3F5FBF>/** + * Notifies listeners about congestion level changes. When level > 0 + * client should delay sending more messages. + */</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> + <font color=#7F0055>void</font> addChannelListener(IChannelListener listener); + + <font color=#3F5FBF>/** + * Remove a channel listener. + */</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> + <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> + <font color=#7F0055>void</font> addCommandServer(IService service, ICommandServer listener); + + <font color=#3F5FBF>/** + * Remove a command server. + */</font> + <font color=#7F0055>void</font> removeCommandServer(IService service, ICommandServer listener); + + <font color=#3F5FBF>/** + * 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. + */</font> + <font color=#7F0055>interface</font> IEventListener { + <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> + <font color=#7F0055>void</font> addEventListener(IService service, IEventListener listener); + + <font color=#3F5FBF>/** + * Unsubscribe an event message listener for given service. + */</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> map of services available on local peer. It maps service names to + * IService implemetations. + */</font> + Map<String, IService> getLocalServices(); + + <font color=#3F5FBF>/** + * <font color=#7F9FBF>@return</font> map of services available on removte peer. It maps service names to + * IService implemetations. + */</font> + Map<String, IService> getRemoteServices(); + + <font color=#3F5FBF>/** + * 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> + */</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_id</font> + */</font> + <font color=#7F0055>void</font> redirect(String peer_id); +} + + +<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(); +} + +</pre> + +<h1><a name='JSON'>Preferred Marshaling</a></h1> + +<p>TCF messages data format is service specific. Since services specifications are +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>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> + <font face=Wingdings>Ø</font> {} + <font face=Wingdings>Ø</font> { <i><members></i> } + +<i><members></i> + <font face=Wingdings>Ø</font> <i><string></i> : <i><value></i> + <font face=Wingdings>Ø</font> <i><members></i> , <i><string></i> : <i><value></i> + +<i><array></i> + <font face=Wingdings>Ø</font> [] + <font face=Wingdings>Ø</font> [ <i><elements></i> ] + +<i><elements></i> + <font face=Wingdings>Ø</font> <i><value></i> + <font face=Wingdings>Ø</font> <i><elements</i>> , <i><value></i> + +<i><value></i> + <font face=Wingdings>Ø</font> <i><string></i> + <font face=Wingdings>Ø</font> <i><number></i> + <font face=Wingdings>Ø</font> <i><object></i> + <font face=Wingdings>Ø</font> <i><array></i> + <font face=Wingdings>Ø</font> <i><boolean></i> + <font face=Wingdings>Ø</font> null + +<i><boolean></i> + <font face=Wingdings>Ø</font> true + <font face=Wingdings>Ø</font> false + +<i><string></i> + <font face=Wingdings>Ø</font> "" + <font face=Wingdings>Ø</font> " <i><chars></i> " + +<i><chars></i> + <font face=Wingdings>Ø</font> <i><char></i> + <font face=Wingdings>Ø</font> <i><chars> <char></i> + +<i><char</i>> + <font face=Wingdings>Ø</font> <i><any Unicode except " or \ or control></i> + <font face=Wingdings>Ø</font> \"<i></i> + <font face=Wingdings>Ø</font> \\<i></i> + <font face=Wingdings>Ø</font> \/<i></i> + <font face=Wingdings>Ø</font> \b<i></i> + <font face=Wingdings>Ø</font> \f<i></i> + <font face=Wingdings>Ø</font> \n<i></i> + <font face=Wingdings>Ø</font> \r<i></i> + <font face=Wingdings>Ø</font> \t<i></i> + <font face=Wingdings>Ø</font> \u <i><four-hex-digits></i> + +<i><number</i>> + <font face=Wingdings>Ø</font> <i><int></i> + <font face=Wingdings>Ø</font> <<i>int> <fraction></i> + <font face=Wingdings>Ø</font> <<i>int> <exponent></i> + <font face=Wingdings>Ø</font> <<i>int> <fraction> <exponent></i> + +<i><int></i> + <font face=Wingdings>Ø</font> <i><digit></i> + <font face=Wingdings>Ø</font> <<i>digit 1-9> <digits></i> + <font face=Wingdings>Ø</font> - <<i>digit></i> + <font face=Wingdings>Ø</font> - <<i>digit 1-9> <digits</i>> + +<i><fraction></i> + <font face=Wingdings>Ø</font> . <i><digits></i> + +<i><exponent></i> + <font face=Wingdings>Ø</font> <i><e></i> <i><digits></i> + +<i><digits></i> + <font face=Wingdings>Ø</font> <i><digit></i> + <font face=Wingdings>Ø</font> <<i>digits></i> <<i>digit></i> + +<i><e></i> + <font face=Wingdings>Ø</font> e + <font face=Wingdings>Ø</font> e+ + <font face=Wingdings>Ø</font> e- + <font face=Wingdings>Ø</font> E + <font face=Wingdings>Ø</font> E+ + <font face=Wingdings>Ø</font> 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> + +<h1><a name='Locator'>Locator Service</a></h1> + +<p>Locator 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 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 Atributes</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> + - ID of the peer. + + <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 dont need to know peer attributes other then ID and Name. Clients are expected to call IPeer.openChannel() +method and let the framework to check peers attributes and create appropriate communication cahnnel that is best suited for +communication with the peer. After a channel is established, a client can learn peer capabilities by looking +at 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><string: peer ID></i> • +</font></b></pre> + +<p>The command redirects the channel to become connected to given peer. +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>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> • +</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 to know capabilities of this peer. + Message data consists of an array of service names that are provided by the peer. + Service names 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. +</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 IPeer.getLocalServices or IPeer.getRemoteServives + */</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 + */</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>, + <i><font color=#0000C0>ATTR_OS_NAME</font></i> = <font color=#2A00FF>"OSName"</font>, + <i><font color=#0000C0>ATTR_TRANSPORT_NAME</font></i> = <font color=#2A00FF>"TransportName"</font>, + <i><font color=#0000C0>ATTR_IP_HOST</font></i> = <font color=#2A00FF>"Host"</font>, + <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<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> 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. + * 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 + * peer’s attributes and capabilities (services). Discovery mechanism depends on + * transport protocol and is part of that protocol handler. Targets, known by other + * 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> + <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; + + <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. + */</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 com.windriver.tcf.api.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=#7F0055>void</font> peerAdded(IPeer peer); + + <font color=#7F0055>void</font> peerRemoved(IPeer peer); + + <font color=#7F0055>void</font> peerChanged(IPeer peer); + } +} +</pre> + +</body> +</html> +
\ No newline at end of file |