diff options
author | Frederic Leger | 2014-03-13 16:28:07 +0000 |
---|---|---|
committer | Frederic Leger | 2014-03-13 16:28:07 +0000 |
commit | 6eeeb4d3c9b6bfb4763e2fde59394c0baa283293 (patch) | |
tree | 5615e61f49d9220f20e45619d1c6610a73a72731 /python/src | |
parent | d67e0bec2951e6ef71ea5f35c7a7131b626a0e9d (diff) | |
download | org.eclipse.tcf-6eeeb4d3c9b6bfb4763e2fde59394c0baa283293.tar.gz org.eclipse.tcf-6eeeb4d3c9b6bfb4763e2fde59394c0baa283293.tar.xz org.eclipse.tcf-6eeeb4d3c9b6bfb4763e2fde59394c0baa283293.zip |
Python - locator service update.
Locator service can now be documented using sphinx.
The getAgentID() service method has been added too.
Diffstat (limited to 'python/src')
-rw-r--r-- | python/src/tcf/services/locator.py | 203 |
1 files changed, 175 insertions, 28 deletions
diff --git a/python/src/tcf/services/locator.py b/python/src/tcf/services/locator.py index 424fe6605..f080e6024 100644 --- a/python/src/tcf/services/locator.py +++ b/python/src/tcf/services/locator.py @@ -9,26 +9,93 @@ # * Wind River Systems - initial API and implementation # ***************************************************************************** -""" -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 to other hosts, can be found through remote instances of Locator service. +"""Locator service uses transport layer to search for peers and to collect data +about peer's attributes and capabilities (services). + +.. |getAgentID| replace:: :meth:`~LocatorService.getAgentID` +.. |redirect| replace:: :meth:`~LocatorService.redirect` +.. |sync| replace:: :meth:`~LocatorService.sync` +.. |DoneGetAgentID| replace:: :class:`DoneGetAgentID` +.. |DoneRedirect| replace:: :class:`DoneRedirect` +.. |DoneSync| replace:: :class:`DoneSync` +.. |LocatorListener| replace:: :class:`LocatorListener` +.. |Peer| replace:: :class:`~tcf.peer.Peer` + +Discovery mechanism depends on transport protocol and is part of that protocol +handler. Targets, known to other hosts, can be found through remote instances +of Locator service. + Automatically discovered targets require no further configuration. Additional targets can be configured manually. -Clients should use protocol.getLocator() to obtain local instance of locator, -then locator.getPeers() can be used to get list of available peers (hosts and -targets). +Clients should use :meth:`tcf.protocol.getLocator` to obtain local instance of +locator, then :meth:`LocatorService.getPeers` can be used to get list of +available peers (hosts and targets). + +Service Methods +--------------- +.. autodata:: NAME +.. autoclass:: LocatorService + +addListener +^^^^^^^^^^^ +.. automethod:: LocatorService.addListener + +getAgentID +^^^^^^^^^^ +.. automethod:: LocatorService.getAgentID + +getName +^^^^^^^ +.. automethod:: LocatorService.getName + +getPeers +^^^^^^^^ +.. automethod:: LocatorService.getPeers + +redirect +^^^^^^^^ +.. automethod:: LocatorService.redirect + +removeListener +^^^^^^^^^^^^^^ +.. automethod:: LocatorService.removeListener + +sync +^^^^ +.. automethod:: LocatorService.sync + +Callback Classes +---------------- +DoneGetAgentID +^^^^^^^^^^^^^^ +.. autoclass:: DoneGetAgentID + :members: + +DoneRedirect +^^^^^^^^^^^^ +.. autoclass:: DoneRedirect + :members: + +DoneSync +^^^^^^^^ +.. autoclass:: DoneSync + :members: + +Listener +-------- +LocatorListener +^^^^^^^^^^^^^^^ +.. autoclass:: LocatorListener + :members: """ from .. import services -# Peer data retention period in milliseconds. DATA_RETENTION_PERIOD = 60 * 1000 - -# Auto-configuration protocol version. +""" Peer data retention period in milliseconds.""" CONF_VERSION = '2' +""" Auto-configuration protocol version.""" # Auto-configuration command and response codes. CONF_REQ_INFO = 1 @@ -38,77 +105,157 @@ CONF_SLAVES_INFO = 4 CONF_PEERS_REMOVED = 5 NAME = "Locator" +"""Locator service name.""" class LocatorService(services.Service): + """TCF Locator service interface.""" + + def getAgentID(self, done): + """Get agent ID of the agent providing the locator service. + + :param done: Call back interface called when operation is completed. + :type done: |DoneGetAgentID| + """ + raise NotImplementedError("Abstract method") def getName(self): + """Get this service name. + + :returns: The value of string :const:`NAME` + """ return NAME def getPeers(self): - """ - Get map (ID -> IPeer) of available peers (hosts and targets). - The method return cached (currently known to the framework) list of + """Get map (ID -> IPeer) of available peers (hosts and targets). + + The method returns cached (currently known to the framework) list of peers. The list is updated according to event received from transport layer. + + :returns: A |dict| of Peer ID -> |Peer| association. """ raise NotImplementedError("Abstract method") def redirect(self, peer, done): - """ - Redirect this service channel to given peer using this service as a + """Redirect this service channel to given peer using this service as a proxy. - @param peer - Peer ID or attributes map. + + :param peer: Peer ID or attributes map. + :type peer: |basestring| + :param done: Call back interface called when operation is completed. + :type done: |DoneRedirect| """ raise NotImplementedError("Abstract method") def sync(self, done): - """ - Call back after TCF messages sent to this target up to this moment are - delivered. + """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. + .. 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. + :param done: Will be executed by dispatch thread after communication + messages are delivered to corresponding targets. + :type done: |DoneSync| - This is internal API, TCF clients should use module 'tcf.protocol'. + This is internal API, TCF clients should use module + :mod:`tcf.protocol`. """ raise NotImplementedError("Abstract method") def addListener(self, listener): - "Add a listener for Locator service events." + """Add a listener for Locator service events. + + :param listener: Listener to add. + :type listener: |LocatorListener| + """ raise NotImplementedError("Abstract method") def removeListener(self, listener): - "Remove a listener for Locator service events." + """Remove a listener for Locator service events. + + :param listener: Listener to remove. + :type listener: |LocatorListener| + """ raise NotImplementedError("Abstract method") +class DoneGetAgentID(object): + """Client call back interface for |getAgentID|.""" + + def doneGetAgentID(self, token, error, agentID): + """Called when a peer agent ID request is done. + + :param token: TCF request token corresponding to this done getAgentID + call. + :param error: error description if operation failed, **None** if + succeeded. + :param agentID: Retrieved agent ID. + :type agentID: |basestring| + """ + pass + + class DoneRedirect(object): + """Client call back interface for |redirect|.""" + def doneRedirect(self, token, error): + """Called when a peer redirection request has been done. + + :param token: TCF request token corresponding to this done redirect + call. + :param error: error description if operation failed, **None** if + succeeded. + """ pass class DoneSync(object): + """Client call back interface for |sync|.""" def doneSync(self, token): + """Called when a peer sync request has been done. + + :param token: TCF request token corresponding to this done sync call. + """ pass class LocatorListener(object): + """TCF peer locator listener.""" def peerAdded(self, peer): + """Called when a new peer has been added to the known peers. + + :param peer: New peer description. + :type peer: |Peer| + """ pass def peerChanged(self, peer): + """Called when one of the known peers has been modified. + + :param peer: New peer description. + :type peer: |Peer| + """ pass def peerRemoved(self, peerID): + """Called when one of the peers has been shut down. + + :param peerId: Id of the peer which shut down. + :type peerId: |basestring| + """ pass def peerHeartBeat(self, peerID): + """Called when one of the peers says he is alive. + + :param peerId: Id of the peer which sent a heartbeat + :type peerId: |basestring| + """ pass |