public class Record extends Object implements Serializable
Message Records may be used to facilitate record based String handling of the data within messages.
A message that has been written with Record delimiters may be read as Records or a Message that uses only field delimiters can be interpreted as a single Record.
A Record may be 'free format' or structured with the Record structure defined
by metadata
.
The fields within a Record that has metadata can be set or retrieved by name
(using setField(String, Object...)
or getField(String)
) and
fields defined as 'repeating' can have individual occurrences set or
retrieved using setField(String, int, Object)
or
getField(String, int)
. When metadata is in use then the record is
initialised to the default values indicated by the metadata and any change to
the structure of the record (using addFields(String...)
,
removeField(int)
etc) is not permitted.
Metadata used for Records is constrained in the following ways:
1) A Record can have one or more Fields defined but can not have nested
Records defined for it.
2) Only String data types are permitted for Fields( MDataType.STRING
,
MDataType.DECIMAL_STRING
etc).
3) Repeating Field definitions with fixed multiplicity are permitted anywhere
within the Record but a repeating Field definition with variable multiplicity
is only permitted if it is the last field within the Record.
The fields within a free format Record are simply positional with no concept
of field name or repeating fields. A free format Record can be thought of as
having a single optional repeating field with no name. Fields can be added
(using addFields(String...)
or inserted (using
addField(int, String)
or removed (using removeField(int)
).
After having built Record(s) they can be written to a Message using
DataMessage.putRecords(Record...)
. It should be noted that the Record
is independent of the Message and subsequent changes to the Record have no
effect on the Message.
Records can be read from incoming Messages using
DataMessage.nextRecord()
.
Constructor and Description |
---|
Record(MRecord metadata,
String... fields)
Create a Record with specified record metadata.
|
Record(String... fields)
Create a free format Record with zero or more fields.
|
Modifier and Type | Method and Description |
---|---|
void |
addField(int index,
String field)
Inserts a field at a specified index within the record, moving subsequent
fields along the record.
|
void |
addFields(Collection<?> fields)
Adds one or more fields to the end of the record.
|
void |
addFields(String... fields)
Adds one or more fields to the end of the record.
|
int |
appendToField(String name,
Collection<?> values)
Appends one or more values to a repeating field.
|
int |
appendToField(String name,
Object... values)
Appends one or more values to a repeating field.
|
static Record |
createWithMetadata(MRecord metadata,
String emptyFieldValue,
String... fields)
This special factory method allows a Record with metadata to be created.
|
boolean |
equals(Object obj) |
String |
getField(int index)
Returns a specific field value within the record.
|
String |
getField(String name)
Gets a field value by name.
|
String |
getField(String name,
int index)
Get the value of a specified occurrence of a repeating field.
|
List<String> |
getFields()
Returns the values of all fields occurrences within the record.
|
List<String> |
getFieldValues(String name)
Gets a list of field values.
|
Object |
getMappedField(String name)
Gets a field value as an object.
|
List<Object> |
getMappedFields()
This returns the fields of the record in a format mapped to the Record
Metadata.
|
MRecord |
getMetadata()
Returns the Record metadata.
|
int |
hashCode() |
String |
removeField(int index)
Removes a specified field from the record.
|
void |
setField(int index,
String field)
Replaces a field at a specified index within the record.
|
void |
setField(String name,
int index,
Object value)
Sets a field value by name and index.
|
void |
setField(String name,
Object... values)
Set field value(s) by name.
|
void |
setFieldValues(String name,
Collection<?> values)
As
setField(String, Object...) but allowing a collection of
values to be supplied. |
int |
size()
Returns the number of field values within the record.
|
int |
sizeInBytes()
This returns the number of bytes that this record would occupy in a
Message that uses the default character set for byte encoding. |
int |
sizeInBytes(String charset)
This returns the number of bytes that this record would occupy in a
Message that uses a specified character set for byte
encoding. |
int |
sizeInChars()
Returns the total number of characters within this record (including
delimiters).
|
String |
toString() |
public Record(MRecord metadata, String... fields) throws MessageException
The record will be initialised according to the metadata.
metadata
- defining the layout of the record. This must be a record
defined for a metadata message of type
TopicDataType.RECORD
. If the metadata supplied is a
message and it defines a single record then that single record
will be assumed to be the metadata. If this is specified as null
then a free format record with fields as indicated by the fields
parameter will be createdfields
- optionally specifies the values for the fields. If
specified then the number of values specified must match the
number of field occurrences indicated by the metadataMessageException
- if Metadata of the wrong type is specifiedpublic Record(String... fields)
fields
- optional variable length number of field valuespublic static Record createWithMetadata(MRecord metadata, String emptyFieldValue, String... fields) throws MessageException
This differs from the standard Record(MRecord, String...)
constructor in that it also allows an empty field value to be specified
that will be allowed in non string fields that would normally fail with a
parse exception if a string value was supplied.
metadata
- defining the layout of the record. This must be a record
defined for a metadata message of type
TopicDataType.RECORD
. If the metadata supplied is a
message and it defines a single record then that single record
will be assumed to be the metadata. If this is specified as null
then a free format record with fields as indicated by the fields
parameter will be createdemptyFieldValue
- this may be null but if specified then it will be
permitted to set a non string field to this value if the field
metadata indicates that it allowsEmpty
fields
- optionally specifies the values for the fields. If
specified then the number of values specified must match the
number of field occurrences indicated by the metadataMessageException
- if Metadata of the wrong type is specifiedpublic final MRecord getMetadata()
public final void addFields(String... fields) throws MessageException
This can only be used for free format records (i.e those without metadata).
fields
- a list of fields to addMessageException
- if fields can not be added to the recordpublic final void addFields(Collection<?> fields) throws MessageException
A collection of any type may be supplied and the toString() value of each object will used as the String value.
If any field value is null it will be written as an empty field (i.e. a zero length string).
This can only be used for free format records (i.e those without metadata)
fields
- the collection of field objects to addMessageException
- if unable to add fields to the recordpublic final void addField(int index, String field) throws MessageException
This can only be used for free format records (i.e those without metadata).
index
- the index to add a field atfield
- the field to addMessageException
- if index out of bounds or adding fields is
prohibited by the use of metadatapublic final String removeField(int index) throws MessageException
This can only be used for free format records (i.e. those without metadata).
index
- the index of the field to removeMessageException
- if there was no field at the specified index or
removal is prohibited by the use of metadatapublic final void setField(int index, String field) throws MessageException
This can only be used for free format records (i.e. those without metadata).
index
- the index of the field to replacefield
- the new fieldMessageException
- if index out of bounds or use prohibited for
message with metadatapublic final void setField(String name, Object... values) throws MessageException
This can only be used for a record that has metadata.
When used for a single
multiplicity field
only a single value may be specified. If no value (or null) is specified
then the field will be set to the default value as indicated by the
metadata, except in the case of a single optional field in which case the
value will be removed.
When used for a repeating
multiplicity
field then multiple values may be specified. No more than the
maximum
number of values may be
supplied.
name
- the field namevalues
- the value or values which are parsed according to the data
type as specified in the metadata. Specifying no values will cause
the field to be initialised to defaults (repeating fields will
have the minimum number of occurrences set to default). A null
value is also interpreted as default except for single optional
fields where it will result in the value being removedMessageException
- if the record has no metadata or the metadata
does not specify a field of the given name or the value(s) can
not be parsed or the number of values violates the metadata
definitionpublic final void setFieldValues(String name, Collection<?> values) throws MessageException
setField(String, Object...)
but allowing a collection of
values to be supplied.name
- the field name.values
- the value or values which are parsed according to the data
type as specified in the metadata. Specifying no values will cause
the field to be initialised to defaults (repeating fields will
have the minimum number of occurrences set to default). A null
value is also interpreted as defaultMessageException
- if the record has no metadata or the metadata
does not specify a field of the given name or the value(s) can
not be parsed or the number of values violates the metadata
definitionpublic final int appendToField(String name, Object... values) throws MessageException
This can only be used for a record that has metadata and for a
repeating
multiplicity field.
Adding the values must not cause the maximum
number of values to be exceeded.
name
- the field namevalues
- the value or values which are parsed according to the data
type as specified in the metadata. If null or no values supplied
then this call has no effectMessageException
- if the record has no metadata or the metadata
does not specify a repeating field of the given name or the
value(s) can not be parsed or the number of values causes the
metadata definition to be violatedpublic final int appendToField(String name, Collection<?> values) throws MessageException
This can only be used for a record that has metadata and for a
repeating
multiplicity field.
Adding the values must not cause the maximum
number of values to be exceeded.
name
- the field name.values
- the value or values which are parsed according to the data
type as specified in the metadata. If null or no values supplied
then this call has no effectMessageException
- if the record has no metadata or the metadata
does not specify a repeating field of the given name or the
value(s) can not be parsed or the number of values causes the
metadata definition to be violatedpublic final void setField(String name, int index, Object value) throws MessageException
This can only be used for a record that has metadata and for a
repeating
multiplicity field.
name
- the field name.index
- the index of the field occurrence to setvalue
- the new field value which is parsed according to the data
type indicated by the metadata. null is interpreted as the default
value for the field as indicated by the metadataMessageException
- if the record has no metadata or the metadata
has no field of the given name or the named field is not declared
as repeating or the index is out of bounds or the value can not
be parsedpublic final String getField(int index) throws MessageException
index
- the index of the field to return value for, starting at 0MessageException
- if the index is out of boundspublic final List<String> getFields()
public final List<Object> getMappedFields()
Each entry in the returned list represents a field entry in the Metadata associated with the Record.
If the metadata field has single
multiplicity then the type of the Object returned will be the internal
representation type associated with the Metadata data
type
, for example a MDataType.INTEGER_STRING
would return a
BigInteger
. A single optional field that is not present would
return a value of null.
If the metadata field has repeating
multiplicity then the object returned will be a List
of Objects
(possibly empty).
If the Record does not have Metadata then this will simply return a list of String values representing all of the fields within the Record.
public final Object getMappedField(String name) throws MessageException
This can only be used for record with metadata.
name
- the field name.MessageException
- if the record has no metadata or no field of the
given name is knownpublic final String getField(String name) throws MessageException
This can only be used for record with metadata and for a non repeating field.
name
- the field nameMessageException
- if the record has no metadata or no field of the
given name is known or the specified field is a repeating fieldpublic final List<String> getFieldValues(String name) throws MessageException
This can only be used for record with metadata.
If the field is a repeating field then all of its current values will be returned (this could be empty for a final variable repeating field). If the field is non repeating then a list containing the single value will be returned.
name
- the field nameMessageException
- if the record has no metadata or no field of the
given name is knownpublic final String getField(String name, int index) throws MessageException
This can only be used for a record that has metadata and for a field that is declared as repeating.
name
- the name of the fieldindex
- the index of the field occurrence to return the value forMessageException
- if the record has no metadata or the named field
is not declared in the metadata or the field is not repeating or
the index is out of boundspublic final int size()
public final int sizeInBytes()
Message
that uses the default character set
for byte encoding.public final int sizeInBytes(String charset) throws UnsupportedEncodingException
Message
that uses a specified character set for byte
encoding.charset
- the name of the character set to use for byte encodingUnsupportedEncodingException
- if the specified character set name
is unknownpublic final int sizeInChars()
This can be used as a more efficient way of determining the size that the
record would occupy within a Message
than using
sizeInBytes()
when it is known that the Record only contains
ASCII character.
Copyright © 2016 Push Technology Ltd. All Rights Reserved.