Siena (v.1.5.5) API documentation

siena
Class ThinClient

java.lang.Object
  extended by 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 tx and ty respectively, with tx < ty, in that order matching a pattern P=(fx fy), might in fact reach the subscriber at times Tx and Ty, with Tx > Ty, 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)

Siena (v.1.5.5) API documentation

Copyright © 2000-2005 University of Colorado.
Copyright © 2005-2008 Antonio Carzaniga.
This documentation is maintained by Antonio Carzaniga