com.inspirel.yami
Class Parameters

java.lang.Object
  com.inspirel.yami.Parameters

All Implemented Interfaces:

YAMISerializable, java.lang.Iterable<Parameters.Entry>

public final class Parameters
extends java.lang.Object
implements YAMISerializable, java.lang.Iterable<Parameters.Entry>

Collection of message parameters.

A collection of message parameters is a list of typed {name, value} pairs.
Each entry in this collection has a unique name and can have one of the following types:

• boolean or boolean array
• int or int array
• long or long array
• double or double array
• String or String array
• byte[] buffers or their arrays
• nested Parameters objects or their arrays, which provides its own scope for naming.

The names of entries are searched for using case-sensitive comparisons.

Note: The instances of this class should not be used from multiple threads without synchronization; it is safe to use separate instances in separate threads.

Note: The entries are ordered - the order in which they are created influences the final serialized form of the message payload.
Newly created entries are appended to the end of the collection unless there is an existing empty slot that can be reused - the appropriate slot is searched for from the beginning to the end of the collection and if no free slot is found the collection is extended at the end.
The above guarantee concerns the user code that relies on predictable serialization.

Nested Class Summary

static class	Parameters.Entry Class representing a single entry in the collection.
static class	Parameters.EntryIterator Iterator class for visiting all entries in the collection.
static class	Parameters.EntryType Enumeration defining all possible entry types.

Constructor Summary

Parameters()
Default constructor, creates an empty collection of parameters.

Method Summary

void	clear() Removes all entries from the collection.
void	deserialize(java.util.List<byte[]> buffers) Deserializes from the given list of buffers.
Parameters.Entry	find(java.lang.String name) Finds the entry by name.
byte[]	getBinary(java.lang.String name) Gets the byte[] value from the given entry.
byte[][]	getBinaryArray(java.lang.String name) Gets the array of byte[] buffers from the given entry.
boolean	getBoolean(java.lang.String name) Gets the boolean value from the given entry.
boolean[]	getBooleanArray(java.lang.String name) Gets the boolean array from the given entry.
double	getDouble(java.lang.String name) Gets the double value from the given entry.
double[]	getDoubleArray(java.lang.String name) Gets the double array from the given entry.
int	getInteger(java.lang.String name) Gets the int value from the given entry.
int[]	getIntegerArray(java.lang.String name) Gets the int array from the given entry.
long	getLong(java.lang.String name) Gets the long value from the given entry.
long[]	getLongArray(java.lang.String name) Gets the long array from the given entry.
Parameters[]	getNestedArray(java.lang.String name) Gets the nested Parameters array from the given entry.
Parameters	getNestedParameters(java.lang.String name) Gets the nested Parameters object from the given entry.
java.lang.String	getString(java.lang.String name) Gets the String value from the given entry.
java.lang.String[]	getStringArray(java.lang.String name) Gets the String array from the given entry.
Parameters.EntryType	getType(java.lang.String name) Gets the type of the given entry.
java.util.Iterator<Parameters.Entry>	iterator() Gets the iterator over the list of entries.
void	remove(java.lang.String name) Removes the given entry from the collection.
java.util.List<byte[]>	serialize(int chunkSize) Serializes the content of the whole collection.
void	setBinary(java.lang.String name, byte[] value) Sets a byte[] value with the given name.
void	setBinaryArray(java.lang.String name, byte[][] array) Sets the byte[] array (note: array of byte arrays) with the given name.
void	setBoolean(java.lang.String name, boolean value) Sets a boolean value with the given name.
void	setBooleanArray(java.lang.String name, boolean[] array) Sets the boolean array with the given name.
void	setDouble(java.lang.String name, double value) Sets a double value with the given name.
void	setDoubleArray(java.lang.String name, double[] array) Sets the double array with the given name.
void	setInteger(java.lang.String name, int value) Sets an int value with the given name.
void	setIntegerArray(java.lang.String name, int[] array) Sets the int array with the given name.
void	setLong(java.lang.String name, long value) Sets a long value with the given name.
void	setLongArray(java.lang.String name, long[] array) Sets the long array with the given name.
void	setNestedArray(java.lang.String name, Parameters[] nested) Sets the nested Parameters array with the given name.
void	setNestedParameters(java.lang.String name, Parameters nested) Sets the nested Parameters object with the given name.
void	setString(java.lang.String name, java.lang.String value) Sets a String value with the given name.
void	setStringArray(java.lang.String name, java.lang.String[] array) Sets the String array with the given name.
int	size() Gets the current size of the collection.
java.lang.String	toString() Returns a string representation of the content.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Parameters

public Parameters()

Default constructor, creates an empty collection of parameters.

Method Detail

setBoolean

public void setBoolean(java.lang.String name,
                       boolean value)

Sets a boolean value with the given name.

Parameters:

name - name of the new entry or the entry to be replaced

value - value to be set

getBoolean

public boolean getBoolean(java.lang.String name)

Gets the boolean value from the given entry.

Parameters:

name - name of the entry to be inspected

Returns:

value from the given entry

Throws:

BadTypeException - if the given entry does not contain boolean value

NoSuchNameException - if the given name is not found

setInteger

public void setInteger(java.lang.String name,
                       int value)

Sets an int value with the given name.

Parameters:

name - name of the new entry or the entry to be replaced

value - value to be set

getInteger

public int getInteger(java.lang.String name)

Gets the int value from the given entry.

Parameters:

name - name of the entry to be inspected

Returns:

value from the given entry

Throws:

BadTypeException - if the given entry does not contain int value

NoSuchNameException - if the given name is not found

setLong

public void setLong(java.lang.String name,
                    long value)

Sets a long value with the given name.

Parameters:

name - name of the new entry or the entry to be replaced

value - value to be set

getLong

public long getLong(java.lang.String name)

Gets the long value from the given entry.

Parameters:

name - name of the entry to be inspected

Returns:

value from the given entry

Throws:

BadTypeException - if the given entry does not contain long value

NoSuchNameException - if the given name is not found

setDouble

public void setDouble(java.lang.String name,
                      double value)

Sets a double value with the given name.

Parameters:

name - name of the new entry or the entry to be replaced

value - value to be set

getDouble

public double getDouble(java.lang.String name)

Gets the double value from the given entry.

Parameters:

name - name of the entry to be inspected

Returns:

value from the given entry

Throws:

BadTypeException - if the given entry does not contain double value

NoSuchNameException - if the given name is not found

setString

public void setString(java.lang.String name,
                      java.lang.String value)

Sets a String value with the given name.

Parameters:

name - name of the new entry or the entry to be replaced

value - value to be set

getString

public java.lang.String getString(java.lang.String name)

Gets the String value from the given entry.

Parameters:

name - name of the entry to be inspected

Returns:

value from the given entry

Throws:

BadTypeException - if the given entry does not contain String value

NoSuchNameException - if the given name is not found

setBinary

public void setBinary(java.lang.String name,
                      byte[] value)

Sets a byte[] value with the given name.

Parameters:

name - name of the new entry or the entry to be replaced

value - value to be set

getBinary

public byte[] getBinary(java.lang.String name)

Gets the byte[] value from the given entry.

Parameters:

name - name of the entry to be inspected

Returns:

value from the given entry

Throws:

BadTypeException - if the given entry does not contain byte[] value

NoSuchNameException - if the given name is not found

setBooleanArray

public void setBooleanArray(java.lang.String name,
                            boolean[] array)

Sets the boolean array with the given name.

Note: the array is not copied internally.

Parameters:

name - name of the new entry or the entry to be replaced

array - value to be set

getBooleanArray

public boolean[] getBooleanArray(java.lang.String name)

Gets the boolean array from the given entry.

Parameters:

name - name of the entry to be inspected

Returns:

array from the given entry

Throws:

BadTypeException - if the given entry does not contain boolean array

NoSuchNameException - if the given name is not found

setIntegerArray

public void setIntegerArray(java.lang.String name,
                            int[] array)

Sets the int array with the given name.

Note: the array is not copied internally.

Parameters:

name - name of the new entry or the entry to be replaced

array - value to be set

getIntegerArray

public int[] getIntegerArray(java.lang.String name)

Gets the int array from the given entry.

Parameters:

name - name of the entry to be inspected

Returns:

array from the given entry

Throws:

BadTypeException - if the given entry does not contain int array

NoSuchNameException - if the given name is not found

setLongArray

public void setLongArray(java.lang.String name,
                         long[] array)

Sets the long array with the given name.

Note: the array is not copied internally.

Parameters:

name - name of the new entry or the entry to be replaced

array - value to be set

getLongArray

public long[] getLongArray(java.lang.String name)

Gets the long array from the given entry.

Parameters:

name - name of the entry to be inspected

Returns:

array from the given entry

Throws:

BadTypeException - if the given entry does not contain long array

NoSuchNameException - if the given name is not found

setDoubleArray

public void setDoubleArray(java.lang.String name,
                           double[] array)

Sets the double array with the given name.

Note: the array is not copied internally.

Parameters:

name - name of the new entry or the entry to be replaced

array - value to be set

getDoubleArray

public double[] getDoubleArray(java.lang.String name)

Gets the double array from the given entry.

Parameters:

name - name of the entry to be inspected

Returns:

array from the given entry

Throws:

BadTypeException - if the given entry does not contain long array

NoSuchNameException - if the given name is not found

setStringArray

public void setStringArray(java.lang.String name,
                           java.lang.String[] array)

Sets the String array with the given name.

Note: the array is not copied internally.

Parameters:

name - name of the new entry or the entry to be replaced

array - value to be set

getStringArray

public java.lang.String[] getStringArray(java.lang.String name)

Gets the String array from the given entry.

Parameters:

name - name of the entry to be inspected

Returns:

array from the given entry

Throws:

BadTypeException - if the given entry does not contain String array

NoSuchNameException - if the given name is not found

setBinaryArray

public void setBinaryArray(java.lang.String name,
                           byte[][] array)

Sets the byte[] array (note: array of byte arrays) with the given name.

Note: the arrays are not copied internally.

Parameters:

name - name of the new entry or the entry to be replaced

array - value to be set

getBinaryArray

public byte[][] getBinaryArray(java.lang.String name)

Gets the array of byte[] buffers from the given entry.

Parameters:

name - name of the entry to be inspected

Returns:

array from the given entry

Throws:

BadTypeException - if the given entry does not contain byte[] array

NoSuchNameException - if the given name is not found

setNestedParameters

public void setNestedParameters(java.lang.String name,
                                Parameters nested)

Sets the nested Parameters object with the given name.

Note: the nested object is not cloned internally.

Parameters:

name - name of the new entry or the entry to be replaced

nested - object to nest

getNestedParameters

public Parameters getNestedParameters(java.lang.String name)

Gets the nested Parameters object from the given entry.

Parameters:

name - name of the entry to be inspected

Returns:

nested object from the given entry

Throws:

BadTypeException - if the given entry does not contain nested Parameters object

NoSuchNameException - if the given name is not found

setNestedArray

public void setNestedArray(java.lang.String name,
                           Parameters[] nested)

Sets the nested Parameters array with the given name.

Note: the nested objects are not cloned internally.

Parameters:

name - name of the new entry or the entry to be replaced

nested - array of objects to nest

getNestedArray

public Parameters[] getNestedArray(java.lang.String name)

Gets the nested Parameters array from the given entry.

Parameters:

name - name of the entry to be inspected

Returns:

nested array of objects from the given entry

Throws:

BadTypeException - if the given entry does not contain nested Parameters array

NoSuchNameException - if the given name is not found

remove

public void remove(java.lang.String name)

Removes the given entry from the collection.

Note: The removed entry leaves a hole (empty slot) in the collection that can be reused by newly added entries.

Parameters:

name - the name of the entry to be removed

clear

public void clear()

Removes all entries from the collection.

size

public int size()

Gets the current size of the collection.

Returns:

size of the collection

getType

public Parameters.EntryType getType(java.lang.String name)

Gets the type of the given entry.

Parameters:

name - name of the given entry

Returns:

the type of the entry

Throws:

NoSuchNameException - if the given name is not found

iterator

public java.util.Iterator<Parameters.Entry> iterator()

Gets the iterator over the list of entries.

The iterator visits only those entries which are used (in other words, it skips unused slots).

Specified by:

iterator in interface java.lang.Iterable<Parameters.Entry>

Returns:

iterator to the list of entries

find

public Parameters.Entry find(java.lang.String name)

Finds the entry by name.

Parameters:

name - the name of entry

Returns:

Entry or null if the given name was not found

serialize

public java.util.List<byte[]> serialize(int chunkSize)

Serializes the content of the whole collection.

The content is serialized into chunks of the given size, after serialization only the last chunk can be smaller than the requested size.

Specified by:

serialize in interface YAMISerializable

Parameters:

chunkSize - chunk size, should be a multiple of 4 or Integer.MAX_VALUE

Returns:

list of buffers (chunks) with serialized data

Throws:

java.lang.IllegalArgumentException - if requested chunk size is not a multiple of 4 and is not Integer.MAX_VALUE

deserialize

public void deserialize(java.util.List<byte[]> buffers)

Deserializes from the given list of buffers.

Note: The current content of this object is not cleared before attempting deserialization and each retrieved data element is merged into the current content as if done by individual calls to appropriate setXYZ functions.
In most cases deserialization will be performed to the empty Parameters object (to reconstruct it to the form that was used for serialization), but deserialization onto non-empty object might be occasionally useful as a way of merging two collections.

Parameters:

buffers - each buffer should have a size that is multiple of 4

Throws:

java.lang.IllegalArgumentException - if any of the given buffers has a size that is not a multiple of 4 or when the given data cannot be properly deserialized

toString

public java.lang.String toString()

Returns a string representation of the content.

This function is supposed to be used by unit tests and for simple debugging.

Overrides:

toString in class java.lang.Object

Returns:

String representation of the collection