org.fudgemsg
Interface FudgeFieldContainer

All Superinterfaces:

Iterable<FudgeField>

All Known Subinterfaces:

ImmutableFudgeFieldContainer, MutableFudgeFieldContainer

All Known Implementing Classes:

FudgeMsg, FudgeMsgBase, ImmutableFudgeMsg

public interface FudgeFieldContainer
extends Iterable<FudgeField>

A container of Fudge fields providing simple access to principal types.

The Fudge specification is built around messages containing a list of fields. This interface is the high-level representation of the list of fields.

Each field may be referenced by a name or by an ordinal. All four combinations are possible - from both present to both absent. Methods provide the ability to lookup a field by both name or ordinal.

Applications working with messages should use this interface rather than FudgeMsg directly where possible for flexibility.

This interface makes no guarantees about the mutability or thread-safety of implementations.

Method Summary

List<FudgeField>	getAllByName(String name) Gets the list of all fields with the given name.
List<FudgeField>	getAllByOrdinal(int ordinal) Gets the list of all fields with the given ordinal.
Set<String>	getAllFieldNames() Gets the set of all unique field names in this container.
List<FudgeField>	getAllFields() Gets the list of all the fields in this container.
Boolean	getBoolean(int ordinal) Gets the value of the first field with the given ordinal as a Boolean.
Boolean	getBoolean(String name) Gets the value of the first field with the given name as a Boolean.
FudgeField	getByIndex(int index) Gets the field in the container with the given index offset.
FudgeField	getByName(String name) Gets the first field with the given name.
FudgeField	getByOrdinal(int ordinal) Gets the first field with the given ordinal.
Byte	getByte(int ordinal) Gets the value of the first field with the given ordinal as a Byte.
Byte	getByte(String name) Gets the value of the first field with the given name as a Byte.
Double	getDouble(int ordinal) Gets the value of the first field with the given ordinal as a Double.
Double	getDouble(String name) Gets the value of the first field with the given name as a Double.
<T> T	getFieldValue(Class<T> clazz, FudgeField field) Gets the value of a field converted to a specific type.
Float	getFloat(int ordinal) Gets the value of the first field with the given ordinal as a Float.
Float	getFloat(String name) Gets the value of the first field with the given name as a Float.
Integer	getInt(int ordinal) Gets the value of the first field with the given ordinal as an Integer.
Integer	getInt(String name) Gets the value of the first field with the given name as an Integer.
Long	getLong(int ordinal) Gets the value of the first field with the given ordinal as a Long.
Long	getLong(String name) Gets the value of the first field with the given name as a Long.
FudgeFieldContainer	getMessage(int ordinal) Gets the value of the first field with the given ordinal as a FudgeFieldContainer.
FudgeFieldContainer	getMessage(String name) Gets the value of the first field with the given name as a FudgeFieldContainer.
short	getNumFields() Gets the size of the container.
Short	getShort(int ordinal) Gets the value of the first field with the given ordinal as a Short.
Short	getShort(String name) Gets the value of the first field with the given name as a Short.
String	getString(int ordinal) Gets the value of the first field with the given ordinal as a String.
String	getString(String name) Gets the value of the first field with the given name as a String.
<T> T	getValue(Class<T> clazz, int ordinal) Gets the value of the first field with the given ordinal.
<T> T	getValue(Class<T> clazz, String name) Gets the value of the first field with the given name.
Object	getValue(int ordinal) Gets the value of the first field with the given ordinal as an Object.
Object	getValue(String name) Gets the value of the first field with the given name as an Object.
boolean	hasField(int ordinal) Checks whether this container has any field which matches the given ordinal.
boolean	hasField(String name) Checks whether this container has any field which matches the given name.
boolean	isEmpty() Checks if the container is empty.
Iterator<FudgeField>	iterator() Gets an iterator over the list of fields in this container.

Method Detail

getNumFields

short getNumFields()

Gets the size of the container.

This returns the total number of fields.

Returns:

number of fields

isEmpty

boolean isEmpty()

Checks if the container is empty.

This checks to see if there are any fields present.

Returns:

true if the container is empty

iterator

Iterator<FudgeField> iterator()

Gets an iterator over the list of fields in this container.

A container is ordered and the returned iterator reflects that order.

Specified by:

iterator in interface Iterable<FudgeField>

Returns:

the iterator of fields, may be unmodifiable, not null

getAllFields

List<FudgeField> getAllFields()

Gets the list of all the fields in this container.

A container is ordered and the returned list reflects that order.

Returns:

the unmodifiable list of fields, not null

getAllFieldNames

Set<String> getAllFieldNames()

Gets the set of all unique field names in this container.

Returns:

the unmodifiable set of names, not null

getByIndex

FudgeField getByIndex(int index)

Gets the field in the container with the given index offset.

Parameters:

index - the zero-based offset into the message of the field, valid

Returns:

the field

Throws:

IndexOutOfBoundsException - if the index is invalid

hasField

boolean hasField(String name)

Checks whether this container has any field which matches the given name.

Parameters:

name - the field name to check, null returns false

Returns:

true if this container has at least one field with the specified name

getAllByName

List<FudgeField> getAllByName(String name)

Gets the list of all fields with the given name.

A container is ordered and may contain multiple fields with the same name. This method returns all matching fields in the order of the container.

Parameters:

name - the field name, null matches fields without a name

Returns:

the unmodifiable list of matching fields, not null

getByName

FudgeField getByName(String name)

Gets the first field with the given name.

A container is ordered and may contain multiple fields with the same name. This method returns the first that matches.

Parameters:

name - the field name, null matches fields without a name

Returns:

the first matching field, null if not found

hasField

boolean hasField(int ordinal)

Checks whether this container has any field which matches the given ordinal.

Parameters:

ordinal - the field ordinal to check

Returns:

true if this container has at least one field with the specified ordinal

getAllByOrdinal

List<FudgeField> getAllByOrdinal(int ordinal)

Gets the list of all fields with the given ordinal.

A container is ordered and may contain multiple fields with the same ordinal. This method returns all matching fields in the order of the container.

Parameters:

ordinal - the field ordinal

Returns:

the unmodifiable list of matching fields, not null

getByOrdinal

FudgeField getByOrdinal(int ordinal)

Gets the first field with the given ordinal.

A container is ordered and may contain multiple fields with the same ordinal. This method returns the first that matches.

Parameters:

ordinal - the field ordinal

Returns:

the first matching field, null if not found

getFieldValue

<T> T getFieldValue(Class<T> clazz,
                    FudgeField field)

Gets the value of a field converted to a specific type.

This attempts to convert the given field to a specific value type. Depending on the underlying implementation this may use a FudgeTypeDictionary.

This conversion logic is at the message level as the field itself does not contain sufficient information. For example, the underlying FudgeFieldType may be shared between a number of encoding strategies. If an implementation does not have the ability to convert, it must return null for a null field value and the field value unchanged if it is assignable to the type requested.

Type Parameters:

T - the class to convert to

Parameters:

clazz - the type to convert to, not null

field - the field whose data to convert, null returns null

Returns:

the converted field value, null if the field value was null

Throws:

IllegalArgumentException - if the requested target class is not appropriate for the field

getValue

<T> T getValue(Class<T> clazz,
               String name)

Gets the value of the first field with the given name.

A container is ordered and may contain multiple fields with the same name. This method returns the value of the first that matches.

Type Parameters:

T - the class to convert to

Parameters:

clazz - the type to convert to, not null

name - the field name, null matches fields without a name

Returns:

the first matching field converted as requested, null if not found

getValue

<T> T getValue(Class<T> clazz,
               int ordinal)

Gets the value of the first field with the given ordinal.

A container is ordered and may contain multiple fields with the same ordinal. This method returns the value of the first that matches.

Type Parameters:

T - the class to convert to

Parameters:

clazz - the type to convert to, not null

ordinal - the field ordinal

Returns:

the converted field value, null if the field value was null

Throws:

IllegalArgumentException - if the requested target class is not appropriate for the field

getValue

Object getValue(String name)

Gets the value of the first field with the given name as an Object.

A container is ordered and may contain multiple fields with the same name. This method returns the value of the first that matches.

Parameters:

name - the field name, null matches fields without a name

Returns:

the first matching field, null if not found

getValue

Object getValue(int ordinal)

Gets the value of the first field with the given ordinal as an Object.

A container is ordered and may contain multiple fields with the same ordinal. This method returns the value of the first that matches.

Parameters:

ordinal - the field ordinal

Returns:

the first matching field, null if not found

getDouble

Double getDouble(String name)

Gets the value of the first field with the given name as a Double.

A container is ordered and may contain multiple fields with the same name. This method returns the value of the first that matches with a type that can be converted to a double.

Parameters:

name - the field name, null matches fields without a name

Returns:

the first matching field, null if not found

getDouble

Double getDouble(int ordinal)

Gets the value of the first field with the given ordinal as a Double.

A container is ordered and may contain multiple fields with the same ordinal. This method returns the value of the first that matches with a type that can be converted to a double.

Parameters:

ordinal - the field ordinal

Returns:

the first matching field, null if not found

getFloat

Float getFloat(String name)

Gets the value of the first field with the given name as a Float.

A container is ordered and may contain multiple fields with the same name. This method returns the value of the first that matches with a type that can be converted to a float.

Parameters:

name - the field name, null matches fields without a name

Returns:

the first matching field, null if not found

getFloat

Float getFloat(int ordinal)

Gets the value of the first field with the given ordinal as a Float.

A container is ordered and may contain multiple fields with the same ordinal. This method returns the value of the first that matches with a type that can be converted to a float.

Parameters:

ordinal - the field ordinal

Returns:

the first matching field, null if not found

getLong

Long getLong(String name)

Gets the value of the first field with the given name as a Long.

A container is ordered and may contain multiple fields with the same name. This method returns the value of the first that matches with a type that can be converted to a long.

Parameters:

name - the field name, null matches fields without a name

Returns:

the first matching field, null if not found

getLong

Long getLong(int ordinal)

Gets the value of the first field with the given ordinal as a Long.

A container is ordered and may contain multiple fields with the same ordinal. This method returns the value of the first that matches with a type that can be converted to a long.

Parameters:

ordinal - the field ordinal

Returns:

the first matching field, null if not found

getInt

Integer getInt(String name)

Gets the value of the first field with the given name as an Integer.

A container is ordered and may contain multiple fields with the same name. This method returns the value of the first that matches with a type that can be converted to an integer.

Parameters:

name - the field name, null matches fields without a name

Returns:

the first matching field, null if not found

getInt

Integer getInt(int ordinal)

Gets the value of the first field with the given ordinal as an Integer.

A container is ordered and may contain multiple fields with the same ordinal. This method returns the value of the first that matches with a type that can be converted to an integer.

Parameters:

ordinal - the field ordinal

Returns:

the first matching field, null if not found

getShort

Short getShort(String name)

Gets the value of the first field with the given name as a Short.

A container is ordered and may contain multiple fields with the same name. This method returns the value of the first that matches with a type that can be converted to a short.

Parameters:

name - the field name, null matches fields without a name

Returns:

the first matching field, null if not found

getShort

Short getShort(int ordinal)

Gets the value of the first field with the given ordinal as a Short.

A container is ordered and may contain multiple fields with the same ordinal. This method returns the value of the first that matches with a type that can be converted to a short.

Parameters:

ordinal - the field ordinal

Returns:

the first matching field, null if not found

getByte

Byte getByte(String name)

Gets the value of the first field with the given name as a Byte.

A container is ordered and may contain multiple fields with the same name. This method returns the value of the first that matches with a type that can be converted to a byte.

Parameters:

name - the field name, null matches fields without a name

Returns:

the first matching field, null if not found

getByte

Byte getByte(int ordinal)

Gets the value of the first field with the given ordinal as a Byte.

A container is ordered and may contain multiple fields with the same ordinal. This method returns the value of the first that matches with a type that can be converted to a byte.

Parameters:

ordinal - the field ordinal

Returns:

the first matching field, null if not found

getString

String getString(String name)

Gets the value of the first field with the given name as a String.

A container is ordered and may contain multiple fields with the same name. This method returns the value of the first that matches with a type that can be converted to a string.

Parameters:

name - the field name, null matches fields without a name

Returns:

the first matching field, null if not found

getString

String getString(int ordinal)

Gets the value of the first field with the given ordinal as a String.

A container is ordered and may contain multiple fields with the same ordinal. This method returns the value of the first that matches with a type that can be converted to a string.

Parameters:

ordinal - the field ordinal

Returns:

the first matching field, null if not found

getBoolean

Boolean getBoolean(String name)

Gets the value of the first field with the given name as a Boolean.

A container is ordered and may contain multiple fields with the same name. This method returns the value of the first that matches with a type that can be converted to a boolean.

Parameters:

name - the field name, null matches fields without a name

Returns:

the first matching field, null if not found

getBoolean

Boolean getBoolean(int ordinal)

Gets the value of the first field with the given ordinal as a Boolean.

A container is ordered and may contain multiple fields with the same ordinal. This method returns the value of the first that matches with a type that can be converted to a boolean.

Parameters:

ordinal - the field ordinal

Returns:

the first matching field, null if not found

getMessage

FudgeFieldContainer getMessage(String name)

Gets the value of the first field with the given name as a FudgeFieldContainer.

A container is ordered and may contain multiple fields with the same name. This method returns the value of the first that matches with a type that can be converted to a message.

Parameters:

name - the field name, null matches fields without a name

Returns:

the first matching field, null if not found

getMessage

FudgeFieldContainer getMessage(int ordinal)

Gets the value of the first field with the given ordinal as a FudgeFieldContainer.

A container is ordered and may contain multiple fields with the same ordinal. This method returns the value of the first that matches with a type that can be converted to a message.

Parameters:

ordinal - the field ordinal

Returns:

the first matching field, null if not found