PubSubManager
This object allows to take advantage of the pattern "publish/subscribe"
applied to the discovery of nodes
with the DAB.
Note: the underlying technology requires a supported browser; please see
HTML 5 Server-Sent Events
for an updated list.
A subscription can be made with the same set of
constraints
of a DAB discover. Basing on the "publish/subscribe" pattern,
once a subscription is subscribed
to the PubSubManager
,
the DAB ("publisher") performs cyclically a discover
with the specified constraints and options and
the API client ("subscriber") is updated when there are some changes on the result set. The updates are sent until the
subscription expires or it is canceled.
// this function is called when there are some changes
var onUpdates = function(resultSet, timeRange){
// retrieves the paginator
var resultSet = resultSet.paginator;
// prints the result set
document.writeln("- Result set -");
document.writeln("start:"+resultSet.start+"<br>");
// ... other prints
document.writeln('<br><br>');
// the current paginator page (the first of the result set)
var page = paginator.page();
// prints page nodes
while(page.hasNext()){
// retrieves the next page node
var node = page.next();
// retrieves the node report
var report = node.report();
// document.writeln(JSON.stringify(report,null,4));
document.writeln(report.title+'<br>');
}
document.writeln('<br>');
};
// this function is called when the subscription expires
// here the subscription is renewed and submitted again
var onExpiration = function(event){
subscription = subscription.renew();
pubSub.subscribe(subscription, onUpdates, onExpiration, onConnectionError, false);
};
// this function is called in case of connection errors
var onConnectionError = function(error){
var msg = '';
switch(error){
case 'TOO_MANY_CONNECTIONS':
msg = 'There too many subscriptions at the moment, please wait a while for a free slot...';
break;
case 'CONNECTION_LOST':
msg = 'The connection with the server is lost, please try again later';
break;
case 'SUBSCRIPTION_REJECTED':
msg = 'A subscription with the specified label and client identifier already exists';
break;
}
document.writeln('<b>---</b>');
document.writeln('<b>'+msg+'</b>');
document.writeln('<b>---</b>');
};
// creates the DAB object
var dab = GIAPI.DAB(GIAPI.demo.api);
// get the PubSubManager from the DAB
var pubSub = dab.pubSubManager();
// creates some constraints
var constraints = {
"where": {
"south": -10,
"west": -20,
"north": 10,
"east": 20
},
"when": {
"from" : "2000-01-01",
"to": "2013-01-01"
},
"what": ["water"]
};
// creates an ID which identifies this API client
var clientID = 'example-client-ID';
// creates a random label
var subscriptionLabel = 'label-'+GIAPI.random();
// creates a subscription with the above constraints and client id
var subscription = GIAPI.Subscription(subscriptionLabel, constraints, clientID);
// subscribes the subscription to the PubSubManager
pubSub.subscribe(subscription, onUpdates, onExpiration, onConnectionError);
Constructor
PubSubManager
()
Item Index
Methods
Methods
subscribe
-
subscription
-
onUpdates
-
onExpiration
-
onConnectionError
Submits the specified subscription
. If the timeZeroResultSet
parameter is true
, the first result of the
discover is notified to onUpdates.response
,
otherwise only the updates will be notified.
After 1 hour, the specified subscription
expires
and onExpiration
is called; once expired it can optionally be
Subscription/renew:method and submitted again.
Note: Each DAB instance allows a predefined maximum of
subscriptions, and if the maximum is reached onConnectionError
is called
and the API client must wait until a free slot is available.
Parameters:
-
subscription
Subscriptionthe subscription for which to receive updates
-
onUpdates
Functioncallback function for receiving asynchronous subscription updates
-
resultSet
ResultSet -
timeRange
TimePeriodthis object provides the time range in which the updates are included
-
subscription
Subscriptionthe specified Subscription
-
-
onExpiration
Functionthis function is called when
subscription
expires-
subscription
Subscriptionthe expired subscription
-
-
onConnectionError
Functionthis function is called in case of connection problems
-
error
Stringthis field has one of the following values:
CONNECTION_LOST
: the connection with the server is lost and the updates cannot be receivedTOO_MANY_CONNECTIONS
: the maximum number of subscriptions is reached and no free slot is available at the momentSUBSCRIPTION_REJECTED
: a subscription with the given label and client identifier is already subscribed
-
subscriptions
-
clientID
-
onResponse
Retrieves all the subscriptions made with the specified client identifier
Parameters:
-
clientID
Stringthe client identifier
-
onResponse
Functioncallback function for receiving asynchronous request response
-
result
Array/Subscriptionan array of subscriptions
-
clientID
Stringthe client identifier
-
unsubscribe
-
subscriptionID
-
onResponse
Cancels the subscription with the specified
subscriptionID
.
See also onExpiration parameter.
See also Subscription id method
Parameters:
-
subscriptionID
Stringthe subscription identifier
-
onResponse
Functioncallback function for receiving asynchronous request response