org.avis.client
Class ConnectionOptions

java.lang.Object
  org.avis.client.ConnectionOptions

public final class ConnectionOptions
extends Object

Connection options sent by the client to the server.

In addition to the options sent by the client to the router detailed below, the router may also add a "Vendor-Identification" option to its reply with a string identifying the router implementation, e.g. "Avis 1.2" or "elvind 4.4.0".

Standard Elvin Connection Options

See http://elvin.org/specs for details on client connection options.

Packet.Max-Length

Max packet length acceptable from a client.

Subscription.Max-Count

Maximum number of subscriptions allowed by a single client.

Subscription.Max-Length

Maximum length, in bytes, of any subscription expression.

Receive-Queue.Max-Length

The maximum size of the router's per-client incoming packet queue, in bytes. If the queue exceeds this size, the router will throttle the data stream from the client until the queue drops below this value.

TCP.Send-Immediately

Set whether the TCP NO_DELAY flag is enabled for sockets on the server side. 1 = send immediately (TCP NO_DELAY = true), 0 = do not necessarily send immediately, buffer data for optimal throughput (TCP NO_DELAY = false). Set this to 1 if you experience lag with "real time" applications that require minimal delivery latency, but note that this may result in an overall reduction in throughput.

Attribute.Name.Max-Length

The maximum length, in bytes, of an attribute name.

Attribute.Max-Count

The maximum number of attributes on a notification.

Attribute.Opaque.Max-Length

Maximum length, in bytes, for opaque values.

Attribute.String.Max-Length

Maximum length, in bytes, for opaque values. Note that this value is not the number of characters: some characters may take up to 5 bytes to represent using the required UTF-8 encoding.

Receive-Queue.Drop-Policy

This property describes the desired behaviour of the router's packet receive queue if it exceeds the negotitated maximum size. Values: "oldest", "newest", "largest", "fail"

Send-Queue.Drop-Policy

This property describes the desired behaviour of the router's packet send queue if it exceeds the negotitated maximum size. Values: "oldest", "newest", "largest", "fail"

Send-Queue.Max-Length

The maximum length (in bytes) of the routers send queue.

Author:

Matthew Phillips

Field Summary

static ConnectionOptions

EMPTY_OPTIONS An immutable set of empty options.

Constructor Summary

ConnectionOptions()
Create an empty instance.

Method Summary

Map<String,Object>	asMap() Generate an immutable, live map of the current options.
Object	get(String name) Get the value for a connection option, or null if not defined.
boolean	getBoolean(String name) Get a boolean value.
boolean	getBoolean(String name, boolean defaultValue) Get a boolean value.
int	getInt(String name) Get an integer value.
int	getInt(String name, int defaultValue) Get an integer value.
String	getString(String name) Get a string value.
String	getString(String name, String defaultValue) Get a string value.
void	includeLegacy(boolean newValue) Enable legacy connection option compatibility (default is enabled).
void	set(String name, boolean value) Set a boolean value.
void	set(String name, int value) Set an integer value.
void	set(String name, Object value) Set a connection option.
void	set(String name, String value) Set a string value.
void	setAll(Map<String,Object> options) Set a number of options at once.

Methods inherited from class java.lang.Object

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

Field Detail

EMPTY_OPTIONS

public static final ConnectionOptions EMPTY_OPTIONS

An immutable set of empty options.

Constructor Detail

ConnectionOptions

public ConnectionOptions()

Create an empty instance.

Method Detail

includeLegacy

public void includeLegacy(boolean newValue)

Enable legacy connection option compatibility (default is enabled). This enables compatibility with older Mantara Elvin routers, and should be left active unless you are sure the target router supports new-style options. Enabling this adds a small amount of size to the initial connection request, but no further overhead.

See Also:

asMapWithLegacy()

asMap

public Map<String,Object> asMap()

Generate an immutable, live map of the current options.

See Also:

asMapWithLegacy()

set

public void set(String name,
                Object value)
         throws IllegalArgumentException

Set a connection option.

Parameters:

name - The option name.

value - The value. Must be a string or a number. Use null to clear.

Throws:

IllegalArgumentException - if value is not a string or an integer.

set

public void set(String name,
                int value)

Set an integer value.

set

public void set(String name,
                boolean value)

Set a boolean value. Elvin connection options are actually either strings or integers: this is a shortcut for setting an int value to 0 or 1.

See Also:

getBoolean(String)

set

public void set(String name,
                String value)

Set a string value.

setAll

public void setAll(Map<String,Object> options)

Set a number of options at once.

get

public Object get(String name)

Get the value for a connection option, or null if not defined.

getInt

public int getInt(String name)
           throws IllegalArgumentException

Get an integer value.

Parameters:

name - The option name.

Returns:

The option value.

Throws:

IllegalArgumentException - if the option has no value or is not an int.

getInt

public int getInt(String name,
                  int defaultValue)
           throws IllegalArgumentException

Get an integer value.

Parameters:

name - The option name.

defaultValue - The default value. This is returned if there is no value for the option.

Returns:

The option value.

Throws:

IllegalArgumentException - if the option is not an int.

getString

public String getString(String name)
                 throws IllegalArgumentException

Get a string value.

Parameters:

name - The option name.

Returns:

The option value.

Throws:

IllegalArgumentException - if the option has no value or is not a string.

getString

public String getString(String name,
                        String defaultValue)
                 throws IllegalArgumentException

Get a string value.

Parameters:

name - The option name.

defaultValue - The default value. This is returned if there is no value for the option.

Returns:

The option value.

Throws:

IllegalArgumentException - if the option is not a string.

getBoolean

public boolean getBoolean(String name)
                   throws IllegalArgumentException

Get a boolean value. NB: Elvin connection options are either strings or integers: this is actually a shortcut for getting an int value in the range 0 to 1.

Parameters:

name - The option name.

Returns:

The boolean value.

Throws:

IllegalArgumentException - if the option is not an int in the range 0-1.

getBoolean

public boolean getBoolean(String name,
                          boolean defaultValue)
                   throws IllegalArgumentException

Get a boolean value. Elvin connection options are actually either strings or integers: this is a shortcut for getting an int value in the range 0 or 1.

Parameters:

name - The option name.

defaultValue - The value to return if there is no value set.

Returns:

The boolean value.

Throws:

IllegalArgumentException - if the option is not an int in the range 0-1.