ThinClient (Siena 2.0.4 API Documentation)
Date: 2015-05-17

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

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `int` | `ReceiverThreads` number of threads handling external packets.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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)`

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