The GEOSS Discovery And Access Broker APIs
Authors: Fabrizio Papeschi, Mattia Santoro, Stefano Nativi
API version: 1.4.3-beta

PubSubManager

Module: PubSub

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

subscribe

(
  • subscription
  • onUpdates
  • onExpiration
  • onConnectionError
)
async

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:

subscriptions

(
  • clientID
  • onResponse
)
async

Retrieves all the subscriptions made with the specified client identifier

Parameters:

unsubscribe

(
  • subscriptionID
  • onResponse
)
async

Cancels the subscription with the specified subscriptionID.

See also onExpiration parameter.
See also Subscription id method

Parameters:

  • subscriptionID String

    the subscription identifier

  • onResponse Function

    callback function for receiving asynchronous request response

    • message String

      a message with one of the following values:

      • OK: the subscription is canceled
      • NOT_FOUND: a subscription with the specified subscriptionID does not exist
    • subscriptionID String

      the subscription subscriptionID