This is the documentation of the Java^TM implementation of Siena.

Copyright © 2000 University of Colorado.
Author: Antonio Carzaniga.

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 <carzanig@cs.colorado.edu>.

Basics

Siena is a publish/subscribe service. The abstract interface of Siena is embodied in the {@link siena.Siena} interface. An application typically uses an implementation of the Siena interface to {@link siena.Siena#publish(siena.Notification) publish} {@link siena.Notification}s or to {@link siena.Siena#subscribe(siena.Filter, siena.Notifiable) subscribe} for some notifications of interest.

Notifications

An event notifications is a set of named attributes. Each attribute has a type and a value (see {@link siena.AttributeValue}). For example:

string stock "XYZ"
int quantity 2500
float price 3.1415

Attribute names must be unique in a notifications.

Selection Mechanisms for Subscriptions

Siena offers two kinds of selection mechanisms:

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 implement the {@link siena.Notifiable} interface. Siena delivers notifications to a subscriber by calling the notify method on the subscriber object. Notifiable has two variants of the notify method: {@link siena.Notifiable#notify(siena.Notification) notify(Notification n)} is called to notify a single notification, while {@link siena.Notifiable#notify(siena.Notification[]) notify(Notification s[])} is called to notify a sequence of notifications.

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

Objects can publish or subscribe by accessing an implementation of Siena. Their Siena access point can also be connected to a larger network of Siena servers. There are two ways 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 does not provide a Siena service itself, it simply acts as a proxy to an external Siena service. A publisher creates a ThinClient object and publishes notifications to it. A subscriber creates a ThinClient object, registers itself as the subscriber, and then subscribes.
For example:
```
        ThinClient mySiena = new ThinClient("senp://host.domain:4321");
	Notifiable subscriber;
	// ... subscriber = ...
	mySiena.setSubscriber(subscriber);

	Filter f = new Filter();
	f.addConstraint("message", OP.ANY, null);
	mySiena.subscribe(f);

	// ...
	Notification n = new Notification();
	n.putAttribute("message","Hello, World!");
	mySiena.publish(n);
	// ...
    
```
Notice that a ThinClient object can act as the proxy of a single subscriber. The ThinClient simply forwards every publication and every subscription to the remote server, and passes any incoming notification to its subscriber.

How to Set Up a Network of Siena Servers

You can run a stand-alone Siena server with {@link siena.StartServer}. For example:

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

starts up a Siena server, on the local host, using port 4321, and connecting it to another Siena server running on host "host.domain" on port 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.