siena
Class ThinClient

java.lang.Object
  siena.ThinClient

All Implemented Interfaces:

java.lang.Runnable, Siena

public class ThinClient
extends java.lang.Object
implements Siena, java.lang.Runnable

thin interface to the Siena event notification service. ThinClient does not provide an event notification service by itself, but rather functions as a connection to an external Siena server. Therefore, a ThinClient object must be configured (constructed) with the handler of its external Siena server.

In the simplest case, a ThinClient can be used only to publish notifications. For example:

      ThinClient siena;
      siena = new ThinClient("ka:siena.dot.org:2345");
      Notification n = new Notification();
      n.putAttribute("name", "Antonio");
      siena.publish(n);
  

ThinClient implements the Siena interface, so it can also be used to subscribe and unsubscribe. ThinClient uses a PacketReceiver to receive notifications from the server.

See Also:

HierarchicalDispatcher, Siena, PacketReceiver

Field Summary

int	ReceiverThreads number of threads handling external packets.

Constructor Summary

ThinClient(java.lang.String server)
creates a thin client connected to a Siena server.

ThinClient(java.lang.String server, java.lang.String id)
creates a thin client connected to a given Siena server, with the given Siena identity.

Method Summary

void	advertise(Filter f, java.lang.String id) advertises a set of notifications.
java.lang.String	getIdentity() returns the identity of this client.
java.lang.String	getServer() returns the handler of the Siena server associated with this Siena interface.
void	publish(Notification n) publish a notification.
void	resume(Notifiable n) resumes the delivery of notifications for a subscriber.
void	run()
static void	setDefaultPacketSenderFactory(PacketSenderFactory f) default packet-sender factory for ThinClient interfaces every new ThinClient uses this factory to create its connection to its master server
void	setReceiver(PacketReceiver r) sets the packet receiver for this server.
void	setReceiver(PacketReceiver r, int threads) sets the packet receiver for this server.
void	shutdown() closes this dispatcher.
void	subscribe(Filter f, Notifiable n) subscribes for events matching Filter f.
void	subscribe(Pattern p, Notifiable n) subscribes for sequences of events matching pattern p.
void	suspend(Notifiable n) suspends the delivery of notifications for a subscriber.
void	unadvertise(Filter f, java.lang.String id) cancel previous advertisements.
void	unadvertise(java.lang.String id) cancel all previous advertisements for object id.
void	unsubscribe(Filter f, Notifiable n) cancels the subscriptions, posted by n, whose filter f' is covered by filter f.
void	unsubscribe(Notifiable n) cancels all the subscriptions posted by n.
void	unsubscribe(Pattern p, Notifiable n) cancels the subscriptions, posted by n, whose pattern p' is covered by pattern p.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ReceiverThreads

public int ReceiverThreads

number of threads handling external packets. The default value of ReceiverThreads is 4. This value is used as the default number of receiver threads.

See Also:

setReceiver(PacketReceiver)

Constructor Detail

ThinClient

public ThinClient(java.lang.String server)
           throws InvalidSenderException

creates a thin client connected to a Siena server.

Parameters:

server - the uri of the server to connect to (e.g., "ka:host.domain.net:7654")

Throws:

InvalidSenderException

ThinClient

public ThinClient(java.lang.String server,
                  java.lang.String id)
           throws InvalidSenderException

creates a thin client connected to a given Siena server, with the given Siena identity. Notice that the string "\000" is a reserved identity, and therefore should never be used with this method. See HierarchicalDispatcher.HierarchicalDispatcher(String) for more information

Parameters:

server - the uri of the server to connect to (e.g., "ka:host.domain.net:7654")

id - the identity of this client. Note that it is necessary that Siena identities be unique within a Siena network. Here the client is responsible to make sure that the given identity does not conflicts with others.

Throws:

InvalidSenderException

Method Detail

setDefaultPacketSenderFactory

public static void setDefaultPacketSenderFactory(PacketSenderFactory f)

default packet-sender factory for ThinClient interfaces every new ThinClient uses this factory to create its connection to its master server

getIdentity

public java.lang.String getIdentity()

returns the identity of this client. every object in a Siena network has a unique identifier. This method returns the identifier of this client.

setReceiver

public void setReceiver(PacketReceiver r)

sets the packet receiver for this server. A packet receiver accepts notifications, subscriptions, and other requests on some communication channel. setReceiver will shut down any previously activated receiver for this dispatcher. This method does not guarantee a transactional switch to a new receiver. This means that some requests might get lost while the server has closed the old port and before it reopens the new port.

This method simply calls setReceiver(PacketReceiver, int) using ReceiverThreads as a default value.

Parameters:

r - is the receiver

See Also:

shutdown(), setReceiver(PacketReceiver, int)

setReceiver

public void setReceiver(PacketReceiver r,
                        int threads)

sets the packet receiver for this server. A packet receiver accepts notifications, subscriptions, and other requests on some communication channel. setReceiver will shut down any previously activated receiver for this dispatcher. This method does not guarantee a transactional switch to a new receiver. This means that some requests might get lost while the server has closed the old port and before it reopens the new port.

Parameters:

r - is the receiver

threads - is the number of threads associated with the receiver, and therefore to the whole server.

See Also:

shutdown()

run

public void run()

Specified by:

run in interface java.lang.Runnable

suspend

public void suspend(Notifiable n)
             throws SienaException

suspends the delivery of notifications for a subscriber. This causes the Siena server to stop sending notification to the given subscriber. The server correctly maintains all the existing subscriptions so that the flow of notification can be later resumed (with resume(Notifiable)).

Specified by:

suspend in interface Siena

Parameters:

n - subscriber to be suspended

Throws:

SienaException

See Also:

resume(Notifiable)

resume

public void resume(Notifiable n)
            throws SienaException

resumes the delivery of notifications for a subscriber. This causes the Siena (master) server to resume sending notification to the given subscriber.

Specified by:

resume in interface Siena

Parameters:

n - subscriber to be resumed

Throws:

SienaException

See Also:

suspend(Notifiable)

getServer

public java.lang.String getServer()

returns the handler of the Siena server associated with this Siena interface.

Returns:

URI of the master server.

See Also:

ThinClient(String)

publish

public void publish(Notification n)
             throws SienaException

Description copied from interface: Siena

publish a notification.

Specified by:

publish in interface Siena

Parameters:

n - The notification to publish.

Throws:

SienaException

See Also:

Notification

subscribe

public void subscribe(Filter f,
                      Notifiable n)
               throws SienaException

Description copied from interface: Siena

subscribes for events matching Filter f.

Notice that given the distributed nature of some implementations of Siena, there exist race conditions that might affect the semantics of subscriptions. Specifically, a subscriber might miss some notifications published before (or while) the subscription is processed by Siena.

Specified by:

subscribe in interface Siena

Parameters:

f - is the subscription

n - is the subscriber

Throws:

SienaException

See Also:

Siena.unsubscribe(siena.Filter, siena.Notifiable)

subscribe

public void subscribe(Pattern p,
                      Notifiable n)
               throws SienaException

Description copied from interface: Siena

subscribes for sequences of events matching pattern p.

Notice that given the distributed nature of some implementations of Siena interface, there exist race conditions that might affect the semantics of subscriptions. A subscriber might miss some notifications published before or while the subscription is processed by Siena.

Also, keep in mind that the current implementation of Siena does not enforce any temporal order for the delivery of notifications. This limitation might affect the recognition of patterns. For example, two notifications x and y, generated at time t_x and t_y respectively, with t_x < t_y, in that order matching a pattern P=(f_x f_y), might in fact reach the subscriber at times T_x and T_y, with T_x > T_y, in which case pattern P would not be matched.

Specified by:

subscribe in interface Siena

Parameters:

p - is the subscription pattern

n - is the subscriber

Throws:

SienaException

See Also:

Siena.unsubscribe(siena.Filter, siena.Notifiable)

unsubscribe

public void unsubscribe(Filter f,
                        Notifiable n)
                 throws SienaException

Description copied from interface: Siena

cancels the subscriptions, posted by n, whose filter f' is covered by filter f.

Unsubscriptions might incurr in the same kind of race conditions as subscriptions. Siena will stop sending notifications to the subscriber only after it has completed the processing of the unsubscriptions. Due to the distributed nature of some implementations of Siena, this might result in some additional ``unsolicited'' notifications.

Specified by:

unsubscribe in interface Siena

n - is the subscriber

Throws:

SienaException

See Also:

Siena.subscribe(siena.Filter, siena.Notifiable)

unsubscribe

public void unsubscribe(Pattern p,
                        Notifiable n)
                 throws SienaException

Description copied from interface: Siena

cancels the subscriptions, posted by n, whose pattern p' is covered by pattern p.

Unsubscriptions might incurr in the same kind of race conditions as subscriptions. Siena will stop sending notifications to the subscriber only after it has completed the processing of the unsubscription. Due to the distributed nature of some implementations of Siena, this might result in some additional ``unsolicited'' notifications.

Specified by:

unsubscribe in interface Siena

n - is the subscriber

Throws:

SienaException

See Also:

Siena.subscribe(siena.Filter, siena.Notifiable)

shutdown

public void shutdown()

closes this dispatcher. If this dispatcher has an active listener then closes the active listener. It also unsubscribes everything with its master server.

Specified by:

shutdown in interface Siena

See Also:

setReceiver(PacketReceiver)

advertise

public void advertise(Filter f,
                      java.lang.String id)
               throws SienaException

Description copied from interface: Siena

advertises a set of notifications. Tells Siena that the object identified by id might publish notifications matching the advertisement filter f.

Specified by:

advertise in interface Siena

Parameters:

f - advertisement filter. Notice that this filter is interpreted differently than a subscription filter. For more information, consult the Siena documentation.

id - identifier of the publisher

Throws:

SienaException

See Also:

Siena.unadvertise(siena.Filter, java.lang.String)

unadvertise

public void unadvertise(Filter f,
                        java.lang.String id)
                 throws SienaException

Description copied from interface: Siena

cancel previous advertisements. Cancels those regarding publisher id, whose advertisement filter f' is covered by advertisement filter f.

Specified by:

unadvertise in interface Siena

Parameters:

f - advertisement filter. Notice that this filter is interpreted differently than a subscription filter. For more information, consult the Siena documentation.

id - identifier of the publisher

Throws:

SienaException

See Also:

Siena.unadvertise(siena.Filter, java.lang.String)

unadvertise

public void unadvertise(java.lang.String id)
                 throws SienaException

Description copied from interface: Siena

cancel all previous advertisements for object id.

Specified by:

unadvertise in interface Siena

Parameters:

id - identifier of the publisher

Throws:

SienaException

See Also:

Siena.unadvertise(siena.Filter, java.lang.String)

unsubscribe

public void unsubscribe(Notifiable n)
                 throws SienaException

Description copied from interface: Siena

cancels all the subscriptions posted by n.

Specified by:

unsubscribe in interface Siena

Parameters:

n - is the subscriber

Throws:

SienaException

See Also:

Siena.subscribe(siena.Filter, siena.Notifiable)