org.avis.client
Class Notification

java.lang.Object
  org.avis.client.Notification

All Implemented Interfaces:

Cloneable, Iterable<Map.Entry<String,Object>>

public final class Notification
extends Object
implements Cloneable, Iterable<Map.Entry<String,Object>>

A notification sent via an Elvin router. A notification is a set of field name/value pairs. Field values may be one of the following types:

• int => Elvin Int32
• long => Elvin Int64
• double => Elvin Real64
• String => Elvin String
• byte [] => Elvin Opaque

Byte Arrays

For efficiency, byte arrays passed in via the set () methods, constuctors, and clone () are not copied before being added to this object, nor are they copied before being returned by the get () methods. Please note that modifying a byte array that is part of a notification can cause undefined behaviour: treat all values of a notification as immutable.

Author:

Matthew Phillips

Constructor Summary

Notification()
Create an empty notification.

Notification(Map<?,?> map)
Create a notification from the values in a map.

Notification(Object... attributes)
Create a notification from an array of name/value pairs.

Notification(Reader in)
Create an instance from an encoded notification read from a stream.

Notification(String ntfnExpr)
Create an instance from an string encoded notification.

Method Summary

Map<String,Object>	asMap() A live, unmodifiable Map view of this notification.
void	clear() Remove all attributes from the notification.
Notification	clone()
Set<Map.Entry<String,Object>>	entrySet() Get the fields/values of this notification as a unmodifiable, live set of java.util.Map.Entry's that can be iterated over.
boolean	equals(Notification ntfn) Compare two notifications.
boolean	equals(Object o)
Object	get(String name) Get a field value.
double	getDouble(String name) Get a double value.
int	getInt(String name) Get an integer value.
long	getLong(String name) Get a long value.
byte[]	getOpaque(String name) Get an opaque byte array value.
String	getString(String name) Get a string value.
boolean	hasField(String name) Test if this notification has a field with a given name.
int	hashCode()
boolean	isEmpty() True if size () == 0.
Iterator<Map.Entry<String,Object>>	iterator() Create an iterator over this notification.
Set<String>	names() The set of names in the notification.
static void	parse(Notification ntfn, Reader in) Parse an expression representing a notification and populate the given notification with the values.
void	remove(String name) Remove (unset) a value.
<E> E	require(String name, Class<E> type) Shortcut to get a non-null value of specified type, or generate an exception.
void	set(String name, byte[] value) Set an opaque byte array value.
void	set(String name, double value) Set a double value.
void	set(String name, int value) Set an integer value.
void	set(String name, long value) Set a long value.
void	set(String name, Object value) Set a field value.
void	set(String name, String value) Set a string value.
void	setAll(Map<?,?> map) Copy all values in a map into this notification.
int	size() The number of name/value pairs in the notification.
String	toString() Generate a string value of the notification.
Collection<Object>	values() The set of values in the notification.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Notification

public Notification()

Create an empty notification.

Notification

public Notification(Object... attributes)
             throws IllegalArgumentException

Create a notification from an array of name/value pairs.

Throws:

IllegalArgumentException - if attributes do not represent a valid notification.

Notification

public Notification(Map<?,?> map)
             throws IllegalArgumentException

Create a notification from the values in a map.

Parameters:

map - The map to copy.

Throws:

IllegalArgumentException - if one of the map values is not a valid type.

Notification

public Notification(String ntfnExpr)
             throws InvalidFormatException

Create an instance from an string encoded notification. See parse(Notification, Reader).

Throws:

InvalidFormatException

Notification

public Notification(Reader in)
             throws IOException,
                    InvalidFormatException

Create an instance from an encoded notification read from a stream. See parse(Notification, Reader).

Throws:

IOException

InvalidFormatException

Method Detail

parse

public static void parse(Notification ntfn,
                         Reader in)
                  throws IOException,
                         InvalidFormatException

Parse an expression representing a notification and populate the given notification with the values. The format of this expression is compatible with that used by the ec and ep utilities. For example:

   An-Int32: 42
   An-Int64: 24L
   A-Real64: 3.14
   String:   "String with a \" in it"
   Opaque:   [01 02 0f ff]
   A field with a \: in it: 1
 

The parser ignores lines starting with "$" and stops on end of stream or "---".

Parameters:

ntfn - The notification to add values to.

in - The source to read the expression from.

Throws:

IOException - If reader throws an IO exception.

InvalidFormatException - If there is an error in the format of the expression. The notification may contain a partial set of values already successfully read.

clear

public void clear()

Remove all attributes from the notification.

clone

public Notification clone()
                   throws CloneNotSupportedException

Overrides:

clone in class Object

Throws:

CloneNotSupportedException

toString

public String toString()

Generate a string value of the notification. The format is compatible with that used by the ec/ep commands. See parse(Notification, Reader) for an example.

Overrides:

toString in class Object

See Also:

Text.formatNotification(Map)

hasField

public boolean hasField(String name)

Test if this notification has a field with a given name.

names

public Set<String> names()

The set of names in the notification. This is a live, unmodifiable set.

values

public Collection<Object> values()

The set of values in the notification. This is a live, unmodifiable collection.

asMap

public Map<String,Object> asMap()

A live, unmodifiable Map view of this notification.

entrySet

public Set<Map.Entry<String,Object>> entrySet()

Get the fields/values of this notification as a unmodifiable, live set of java.util.Map.Entry's that can be iterated over.

See Also:

iterator()

iterator

public Iterator<Map.Entry<String,Object>> iterator()

Create an iterator over this notification.

Specified by:

iterator in interface Iterable<Map.Entry<String,Object>>

equals

public boolean equals(Object o)

Overrides:

equals in class Object

equals

public boolean equals(Notification ntfn)

Compare two notifications.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

isEmpty

public boolean isEmpty()

True if size () == 0.

size

public int size()

The number of name/value pairs in the notification.

setAll

public void setAll(Map<?,?> map)

Copy all values in a map into this notification.

Parameters:

map - The map to copy.

Throws:

IllegalArgumentException - if a key in the map is not a string, or a value is not a string, integer, long, double or byte array. Some values may already have been added to the notification.

set

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

Set a field value.

Parameters:

name - The field name.

value - The value, or null to clear field.

Throws:

IllegalArgumentException - if value is not a string, integer, long, double or byte array.

set

public void set(String name,
                int value)

Set an integer value.

Parameters:

name - The field name.

value - The value.

See Also:

set(String, Object)

set

public void set(String name,
                long value)

Set a long value.

Parameters:

name - The field name.

value - The value.

See Also:

set(String, Object)

set

public void set(String name,
                double value)

Set a double value.

Parameters:

name - The field name.

value - The value.

See Also:

set(String, Object)

set

public void set(String name,
                String value)

Set a string value.

Parameters:

name - The field name.

value - The value.

See Also:

set(String, Object)

set

public void set(String name,
                byte[] value)

Set an opaque byte array value.

Parameters:

name - The field name.

value - The value.

See Also:

set(String, Object)

remove

public void remove(String name)

Remove (unset) a value.

Parameters:

name - the field name.

get

public Object get(String name)

Get a field value.

Parameters:

name - The field name.

Returns:

The value, or null if no value.

getString

public String getString(String name)
                 throws IllegalArgumentException

Get a string value.

Parameters:

name - The field name.

Returns:

The value, or null if no value.

Throws:

IllegalArgumentException - if value is not a string.

getInt

public int getInt(String name)
           throws IllegalArgumentException

Get an integer value.

Parameters:

name - The field name.

Returns:

The value.

Throws:

IllegalArgumentException - if value is not an integer or is null.

getLong

public long getLong(String name)
             throws IllegalArgumentException

Get a long value.

Parameters:

name - The field name.

Returns:

The value.

Throws:

IllegalArgumentException - if value is not a long or is null.

getDouble

public double getDouble(String name)
                 throws IllegalArgumentException

Get a double value.

Parameters:

name - The field name.

Returns:

The value.

Throws:

IllegalArgumentException - if value is not a double or is null.

getOpaque

public byte[] getOpaque(String name)
                 throws IllegalArgumentException

Get an opaque byte array value.

Parameters:

name - The field name.

Returns:

The value, or null for no value.

Throws:

IllegalArgumentException - if value is not a byte array.

require

public <E> E require(String name,
                     Class<E> type)
          throws IllegalArgumentException

Shortcut to get a non-null value of specified type, or generate an exception.

Parameters:

name - The field name.

type - The required type.

Returns:

The value.

Throws:

IllegalArgumentException - if there is no value for the field or the value is not the required type.