Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

Please, send comments, suggestions, complaints about this documentation to Antonio Carzaniga <(firstname.lastname@unisi.ch)>.

Basics

Notifications

string stock "XYZ" int quantity 2500 float price 3.1415

Attribute names must be unique in a notifications.

Selection Mechanisms for Subscriptions

• filters select one event notification at a time. Filters are defined by the class {@link siena.Filter}. A filter is a conjunction (logical and) of constraints on specific attributes of a notification (see {@link siena.AttributeConstraint}). For example:

  string stock = "XYZ" int quantity > 2000 int quantity < 3000 float price > 2.7818

  A filter can have more than one constraint for the same attribute.

• patterns select one or more notifications at a time. patterns are defined by the class {@link siena.Pattern}. The current implementation supports the simple form of pattern given by a sequence of filters.

How Notifications are Delivered to Subscribers

A subscriber must provide both implementations, even if it will never receive sequences of notifications. In this case, the subscriber can implement:

    public void notify(Notification[] s) {};

How to Set Up a Siena Service

How to Access the Siena Service

• local access point through an object that implements the Siena interface. The implementation of the Siena service is provided by the {@link siena.HierarchicalDispatcher} class. An instance of HierarchicalDispatcher must be created, and possibly connected to an external network of Siena servers.

  For example:

  
          HierarchicalDispatcher mySiena = new HierarchicalDispatcher();
  
  	Notifiable subscriber;
  	// ... subscriber = ...
  	Filter f = new Filter();
  	f.addConstraint("message", OP.ANY, null);
  	mySiena.subscribe(f, subscriber);
  
  	// ...
  	Notification n = new Notification();
  	n.putAttribute("message","Hello, World!");
  	mySiena.publish(n);
  	// ...
      

  Notice that many different subscribers and publishers can use the same HierarchicalDispatcher object as their Siena access point. In fact, HierarchicalDispatcher performs some optimizations by exploiting commonalities among local subscriptions, therefore it is best to create and use only one dispatcher per virtual machine.

• remote service through a proxy object that sends every request to an external Siena server, and receives incoming notifications. The implementation of the proxy is provided through the {@link siena.ThinClient} class. A ThinClient object implements the Siena interface, but it does not provide a Siena service itself: it simply forwards every publication and every subscription to the remote server, and passes any incoming notification to its subscriber.

  Clients use a ThinClient just like any other Siena interface. A publisher creates a ThinClient object and publishes notifications to it. A subscriber creates a ThinClient object and subscribes.

  For example:

  
          ThinClient mySiena = new ThinClient("tcp:host.domain:4321");
  	Notifiable subscriber;
  	// ... subscriber = ...
  
  	Filter f = new Filter();
  	f.addConstraint("message", OP.ANY, null);
  	mySiena.subscribe(f, subscriber);
  
  	// ...
  	Notification n = new Notification();
  	n.putAttribute("message","Hello, World!");
  	mySiena.publish(n);
  	// ...
      

How to Set Up a Network of Siena Servers

    java siena.StartServer -port 4321 -master tcp:host.domain:5432

This building block can be used to create a network of servers (with a hierarchical topology). It is important to create the network of Siena servers according to the topology of the underlying network. For example, suppose you have an existing topology of servers, one running in the cs.colorado.edu domain and one running at ics.uci.edu, and suppose you want to run another server at cs.colorado.edu, then the obvious thing to do is to connect it to the server running at cs.colorado.edu.

Examples