Elvin (Avis Client Library For Elvin)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.avis.client
Class Elvin

java.lang.Object
  org.avis.client.Elvin

All Implemented Interfaces:: Closeable

public final class Elvin
extends Object
implements Closeable
extends Object
implements Closeable

The core class in the Avis client library which manages a client's connection to an Elvin router. Typically a client creates a connection and then subscribes to notifications and/or sends them.

Example:

 Elvin elvin = new Elvin ("elvin://elvinhostname");
 
 // subscribe to some notifications
 elvin.subscribe ("Foo == 42 || begins-with (Bar, 'baz')");
 
 // add a handler for notifications
 elvin.addSubscriptionListener (new GeneralSubscriptionListener ()
 {
   public void notificationReceived (GeneralNotificationEvent e)
   {
     System.out.println ("Got a notification:\n" + e.notification);
   }
 });
 
 // send a notification that we will get back from the router
 Notification notification = new Notification ();
 notification.set ("Foo", 42);
 notification.set ("Bar", "bar");
 notification.set ("Data", new byte []{0x00, 0xff});
 
 elvin.send (notification);
 
 elvin.close ();

Threading And Synchronisation Notes

This class is thread safe and may be accessed from any number of client threads.
All changes requiring a response from the router, such as subscribing, are synchronous.
Callbacks to the client initiated by a message from the router, such as notifications, are done from a separate thread managed by this connection. No guarantees on the callback thread are given, in particular the same thread may not be used each time.
Clients have full access to the connection during a callback: changing subscriptions and sending notifications from a callback is fully supported.
Clients should not take a lot of time in a callback since all other operations are blocked during this time (the client mutex is automatically pre-acquired during callback execution in order to avoid possible deadlock in callbacks that access the client connection). Callbacks should execute long running or blocking operations on another thread, e.g. via an ExecutorService.

Author:: Matthew Phillips

Constructor Summary
`Elvin(ElvinURI routerUri)` Create a new connection to an Elvin router.
`Elvin(ElvinURI routerUri, ConnectionOptions options)` Create a new connection to an Elvin router.
`Elvin(ElvinURI routerUri, ConnectionOptions options, Keys notificationKeys, Keys subscriptionKeys)` Create a new connection to an Elvin router.
`Elvin(ElvinURI routerUri, ElvinOptions options)` Create a new connection to an Elvin router.
`Elvin(ElvinURI routerUri, Keys notificationKeys, Keys subscriptionKeys)` Create a new connection to an Elvin router.
`Elvin(String elvinUri)` Create a new connection to an Elvin router.
`Elvin(String elvinUri, ConnectionOptions options)` Create a new connection to an Elvin router.
`Elvin(String routerUri, ElvinOptions options)` Create a new connection to an Elvin router.

Method Summary
`void`	`addCloseListener(CloseListener listener)` Add listener to the close event sent when the client's connection to the router is disconnected.
`void`	`addLogListener(ElvinLogListener listener)` Add a listener for log events emitted by the client.
`void`	`addNotificationListener(GeneralNotificationListener listener)` Add a listener to all notifications received by all subscriptions of this connection.
`void`	`close()` Close the connection to the router.
`void`	`closeOnExit()` Signal that this connection should be automatically closed when the VM exits.
`ConnectionOptions`	`connectionOptions()` The connection options established with the router.
`boolean`	`hasSubscription(Subscription subscription)` Test if a given subscription is part of this connection.
`boolean`	`isOpen()` Test if this connection is open i.e.
`long`	`livenessTimeout()`
`Object`	`mutex()` Return the mutex used to synchronize access to this connection.
`Keys`	`notificationKeys()`
`ElvinOptions`	`options()` Return the current options for the connection.
`long`	`receiveTimeout()`
`void`	`removeCloseListener(CloseListener listener)` Remove a previously added close listener.
`void`	`removeLogListener(ElvinLogListener listener)` Remove a previously added log listener.
`void`	`removeNotificationListener(GeneralNotificationListener listener)` Remove a listener to all notifications received by all subscriptions of this connection.
`ElvinURI`	`routerUri()` The router's URI.
`void`	`send(Notification notification)` Send a notification.
`void`	`send(Notification notification, Keys keys)` Send a notification with a set of keys but with no requirement for secure delivery: use `send (notification, REQUIRE_SECURE_DELIVERY, keys)` if you want only subscriptions with matching keys to receive a notification.
`void`	`send(Notification notification, Keys keys, SecureMode secureMode)` Send a notification.
`void`	`send(Notification notification, SecureMode secureMode)` Send a notification with a specified security mode.
`void`	`setKeys(Keys newNotificationKeys, Keys newSubscriptionKeys)` Change the connection-wide keys used to secure the receipt and delivery of notifications.
`void`	`setLivenessTimeout(long livenessTimeout)` Set the liveness timeout period (default is 60 seconds).
`void`	`setNotificationKeys(Keys newNotificationKeys)` Set the connection-wide notification keys used to secure delivery of notifications.
`void`	`setReceiveTimeout(long receiveTimeout)` Set the amount of time that must pass before the router is assumed not to be responding to a request message (default is 10 seconds).
`void`	`setSubscriptionKeys(Keys newSubscriptionKeys)` Set the connection-wide subscription keys used to secure receipt of notifications.
`Subscription`	`subscribe(String subscriptionExpr)` Create a new subscription.
`Subscription`	`subscribe(String subscriptionExpr, Keys keys)` Create a new subscription with a given set of security keys to enable secure delivery, but also allowing insecure notifications.
`Subscription`	`subscribe(String subscriptionExpr, Keys keys, SecureMode secureMode)` Create a new subscription.
`Subscription`	`subscribe(String subscriptionExpr, SecureMode secureMode)` Create a new subscription with a given security mode but with an empty key set.
`Keys`	`subscriptionKeys()`

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail