1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
|
# *****************************************************************************
# * Copyright (c) 2011, 2013 Wind River Systems, Inc. and others.
# * All rights reserved. This program and the accompanying materials
# * are made available under the terms of the Eclipse Public License v1.0
# * which accompanies this distribution, and is available at
# * http://www.eclipse.org/legal/epl-v10.html
# *
# * Contributors:
# * 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).
.. |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 :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
DATA_RETENTION_PERIOD = 60 * 1000
""" Peer data retention period in milliseconds."""
CONF_VERSION = '2'
""" Auto-configuration protocol version."""
# Auto-configuration command and response codes.
CONF_REQ_INFO = 1
CONF_PEER_INFO = 2
CONF_REQ_SLAVES = 3
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 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
proxy.
: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.
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.
:type done: |DoneSync|
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.
:param listener: Listener to add.
:type listener: |LocatorListener|
"""
raise NotImplementedError("Abstract method")
def removeListener(self, listener):
"""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
|
