Skip to main content
aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorFrederic Leger2014-03-13 12:28:07 -0400
committerFrederic Leger2014-03-13 12:28:07 -0400
commit6eeeb4d3c9b6bfb4763e2fde59394c0baa283293 (patch)
tree5615e61f49d9220f20e45619d1c6610a73a72731 /python/src/tcf
parentd67e0bec2951e6ef71ea5f35c7a7131b626a0e9d (diff)
downloadorg.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/tcf')
-rw-r--r--python/src/tcf/services/locator.py203
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

Back to the top