Message (OBCOM NetClient v2.138)

java.lang.Object
- cl.obcom.netclient.Message

All Implemented Interfaces:

Serializable, Cloneable
```
public final class Message
extends Object
implements Serializable, Cloneable
```
Used to exchange information with a NetServer. This information is represented by a fixed set of codes, a list of zero or more labels, and a sequence of zero or more characters that encode the message data. The codes and labels of a Message are used to implement the details of the NetServer Communication Protocol (ECP). They specify, among other things, the type, sequence number and the destination of the data of a Message. A Message must be serialized in order to transfer it through a communication channel (socket). A serialized Message looks as follows:
```
 +-+-----+-+-+----------------------------------------------------+
 |V|12345|F|T|QOI<FS>KVVV...V<FS>KVVV...V<GS>SSIRMMPDDD......DDXXX|
 +-+-----+-+-+----------------------------------------------------+

 Message Header (8 Bytes)
      V: Version Code (0x1E)
      L: Length (12345)
      F: Filler Count (X)
      T: Type Code
 Message Data (L-8 Bytes)
      Q: Sequence Number
      O: Operation Code
      I: Session ID (Links Only)
   <FS>: Field Separator (0x1C)
      K: Label Name
      V: Label Data Bytes
   <GS>: Group Separator (0x1D)
      S: Server Code
      I: Session ID Code
      R: Request/Reply Code
      M: Form Code
      P: Protection Code
      D: Data Bytes
      X: Filler Bytes (F)
```
The meaning of all these Message elements is explained in the different getter and setter methods provided by this class.
See Also:

Layout, LayoutField, Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static interface`	`Message.Label` Defines the possible labels of a `Message`.
`static interface`	`Message.Oper` Defines the operation codes of a `Message`.
`static interface`	`Message.Prot` Defines the protection codes of a `Message`.
`static interface`	`Message.Reply` Defines the reply codes of a `Message`.
`static interface`	`Message.Type` Defines the possible types of a `Message`.

Constructor Summary

Constructors
Constructor and Description

Message()
Creates a new Message instance with zero length data.

Message(String data)
Creates a new Message with the supplied data.

Constructors
Constructor and Description
`Message()` Creates a new `Message` instance with zero length data.
`Message(String data)` Creates a new `Message` with the supplied `data`.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Object`	`clone()` Returns a "deep" copy of this `Message`.
`boolean`	`exists(String fieldName)` Returns `true` if the field indexed by `fieldName` exists in the `Layout` of this `Message`.
`char`	`getChar(String fieldName)` Returns the character value of the field identified by `fieldName` .
`char`	`getChar(String fieldName, int index)` Returns the character value of the field identified by `fieldName` and `index`.
`String`	`getData()` Returns the text data of this `Message` with trailing space characters removed (right trimmed).
`String`	`getData(String fieldName)` Returns the internal character sequence of the field identified by `fieldName`.
`String`	`getData(String fieldName, int index)` Returns the internal character sequence of the field identified by `fieldName` and `index`.
`String`	`getDataAll()` Returns all text data of this `Message`.
`byte[]`	`getDataBytes()` Returns the binary data of this `Message`.
`Date`	`getDate(String fieldName)` Returns the date value of the field identified by `fieldName`.
`Date`	`getDate(String fieldName, int index)` Returns the date value of the field identified by `fieldName` and `index`.
`static boolean`	`getDefaultSignANSI()` Returns `true` if, by default, numeric fields are stored in messages using the ANSI mechanism.
`double`	`getDouble(String fieldName)` Returns the double value of the field identified by `fieldName`.
`double`	`getDouble(String fieldName, int index)` Returns the double value of the field identified by `fieldName` and `index`.
`LayoutField`	`getField(String fieldName)` Returns the field identified by `fieldName`.
`int`	`getFormCode()` Returns the form code of this `Message`.
`int`	`getInteger(String fieldName)` Returns the integer value of the field identified by `fieldName`.
`int`	`getInteger(String fieldName, int index)` Returns the integer value of the field identified by `fieldName` and `index`.
`String`	`getLabel(int key)` Returns the string value of the label identified by `key`.
`Layout`	`getLayout()` Returns the current layout of this `Message`.
`int`	`getMaxLabelKey()` Returns the maximum label key of all Message labels.
`int`	`getMinLabelKey()` Returns the minimum label key of all Message labels.
`String`	`getMulticastName()` Returns the multicast name of this `Message`.
`BigDecimal`	`getNumber(String fieldName)` Returns the decimal value of the field identified by `fieldName`.
`BigDecimal`	`getNumber(String fieldName, int index)` Returns the decimal value of the field identified by `fieldName` and `index`.
`int`	`getOccurs(String fieldName)` Returns the number of occurrences of the field identified by `fieldName`.
`int`	`getOperCode()` Returns the operation code of the `Message` (`Message.Oper`).
`int`	`getProtCode()` Returns the protection code of this `Message` (`Message.Prot`).
`int`	`getReplyCode()` Returns the reply code of this `Message` (`Message.Reply`).
`int`	`getSequence()` Returns the sequence number of the `Message`.
`int`	`getServerCode()` Returns the server code of this `Message`.
`int`	`getSessionID()` Returns the session ID of this `Message`.
`boolean`	`getSignANSI()` Returns `true` if numeric fields are stored in this `Message` using the ANSI mechanism.
`String`	`getString(String fieldName)` Returns the string value of the field identified by `fieldName`.
`String`	`getString(String fieldName, int index)` Returns the string value of the field identified by `fieldName` and `index`.
`int`	`getTranCode()` Returns the transaction code of this `Message`.
`int`	`getType()` Returns the type of the `Message` (`Message.Type`).
`boolean`	`hasLabel(int key)` Returns `true` if the label indexed by `key` exists.
`void`	`initFields()` Set the value of each field of this `Message` to its default value.
`void`	`initFields(Message source)` Set the value of each field of this `Message` to the value of its corresponding field in `source`.
`boolean`	`isDataOnly()` Returns `true` if this is a data-only `Message`.
`boolean`	`isNull(String fieldName)` Returns `true` if the value of the field identified by `fieldName` is NULL.
`boolean`	`isNull(String fieldName, int index)` Returns `true` if the value of the field identified by `fieldName` and `index` is NULL.
`boolean`	`isStrict()` Returns `true` if this `Message` is strict.
`void`	`removeLabel(int key)` Removes the label identified by `key` from this `Message`.
`void`	`removeLabels()` Removes all the labels defined in this `Message`.
`void`	`replace(int start, int end, String value)` Replaces the characters in a substring of the message data with characters in the specified String.
`byte[]`	`serialize()` Returns a serialized version of this `Message`.
`byte[]`	`serialize(boolean withType)` Returns a serialized version of this `Message` with optional type code.
`void`	`setChar(String fieldName, char value)` Updates the character value of the field identified by `fieldName`.
`void`	`setChar(String fieldName, int index, char value)` Updates the character value of the field identified by `fieldName` and `index`.
`void`	`setData(String data)` Changes the text data of this `Message`.
`void`	`setData(String fieldName, int index, String value)` Updates the internal character sequence of the field identified by `fieldName` and `index`.
`void`	`setData(String fieldName, String value)` Updates the internal character sequence of the field identified by `fieldName`.
`void`	`setDataBytes(byte[] bytes)` Changes the binary data of this `Message`.
`void`	`setDataOnly(boolean value)` Changes whether this is a data-only `Message`.
`void`	`setDate(String fieldName, Date value)` Updates the date value of the field identified by `fieldName`.
`void`	`setDate(String fieldName, int index, Date value)` Updates the date value of the field identified by `fieldName` and `index`.
`static void`	`setDefaultSignANSI(boolean signANSI)` Defines if, by default, numeric fields are stored in messages using the ANSI or the TANDEM mechanism.
`void`	`setDouble(String fieldName, double value)` Updates the double value of the field identified by `fieldName`.
`void`	`setDouble(String fieldName, int index, double value)` Updates the double value of the field identified by `fieldName` and `index`.
`void`	`setFormCode(int formCode)` Changes the form code of this `Message`.
`void`	`setInteger(String fieldName, int value)` Updates the integer value of the field identified by `fieldName`.
`void`	`setInteger(String fieldName, int index, int value)` Updates the integer value of the field identified by `fieldName` and `index`.
`void`	`setLabel(int key, String value)` Changes the string value of the label identified by `key`.
`void`	`setLayout(Layout layout)` Changes the layout of this `Message`.
`void`	`setNull(String fieldName)` Updates the value of the field identified by `fieldName` to NULL.
`void`	`setNull(String fieldName, int index)` Changes the value of the field identified by `fieldName` and `index` to NULL.
`void`	`setNumber(String fieldName, BigDecimal value)` Updates the decimal value of the field identified by `fieldName`.
`void`	`setNumber(String fieldName, int index, BigDecimal value)` Updates the decimal value of the field identified by `fieldName` and `index`.
`void`	`setOperCode(int opcode)` Changes the operation code of the `Message` (`Message.Oper`).
`void`	`setProtCode(int protCode)` Changes the protection code of this `Message` (`Message.Prot`).
`void`	`setReplyCode(int replyCode)` Changes the reply code of this `Message` (`Message.Reply`).
`void`	`setSequence(int sequence)` Changes the sequence number of the `Message`.
`void`	`setServerCode(int serverCode)` Changes the server code of this `Message`.
`void`	`setSessionID(int sessionID)` Changes the session ID of this `Message`.
`void`	`setSignANSI(boolean signANSI)` Defines whether numeric fields are stored in this `Message` using the ANSI or the TANDEM mechanism.
`void`	`setStrict(boolean strict)` Defines whether this `Message` is strict or not strict.
`void`	`setString(String fieldName, int index, String value)` Updates the string value of the field identified by `fieldName` and `index`.
`void`	`setString(String fieldName, String value)` Updates the string value of the field identified by `fieldName`.
`void`	`setTranCode(int tranCode)` Changes the transaction code of this `Message`.
`void`	`setType(int type)` Changes the type of the `Message` (`Message.Type`).
`String`	`substring(int start, int end)` Returns a new string that is a substring of this Message.
`static Message`	`toMessage(Object value)` Converts the supplied object `value` to a `Message`.
`String`	`toString()` Returns a string representation of this `Message`.
`String`	`toTagString(String separator)` Returns a string with the TAG representation of the data stored in this `Message`.
`String`	`toXml(boolean indent)` Returns the XML string representation of the data stored in this `Message`.
`static Message`	`unserialize(byte[] bytes, int offset, int length)` Creates a new `Message` by unserializing the supplied byte array.
`static Message`	`unserialize(byte[] bytes, int offset, int length, boolean withType)` Creates a new `Message` by unserializing the supplied byte array with optional type code.
`Layout`	`verifyLayout(String layoutName)` Verifies that the name of the layout of this `Message` matches the supplied `layoutName`.

Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail
- Message
```
public Message()
```
  Creates a new Message instance with zero length data. The message codes are set to default values, and no message labels are defined.
- Message
```
public Message(String data)
```
  Creates a new Message with the supplied data. The codes of the new message are set to default values, and no message labels are defined.
  
  Parameters:
  
  data - the initial data of the Message (can be null).

Method Detail

isStrict
```
public boolean isStrict()
```
Returns true if this Message is strict. See description of the setString method for further details about Message strictness.

Returns:

true if this Message is strict.

See Also:

setStrict(boolean)

setStrict

public void setStrict(boolean strict)

Defines whether this Message is strict or not strict. By default all messages are not strict when created. If a Message is strict then any attempt to assign an invalid field value generates (throws) an exception. If a Message is not strict then certain invalid field values are permitted as described in the following table:

Invalid Field Value	Action Taken
RUT value with incorrect parity character	The RUT value is stored as supplied
Numeric value longer than the length of the field	The numeric value is silently truncated on the left
Text value longer than the length of the field	The text value is silently truncated on the right
Negative value applied to an unsigned numeric field	The numeric value is stored ignoring its sign

Parameters:: strict - new strict value.
See Also:: isStrict()

getSignANSI
```
public boolean getSignANSI()
```
Returns true if numeric fields are stored in this Message using the ANSI mechanism. Otherwise, it returns false, meaning numeric fields are stored using the TANDEM mechanism.

Returns:

true if numeric fields are stored using the ANSI mechanism. Otherwise, the TANDEM mechanism is being used.

See Also:

setSignANSI(boolean), getDefaultSignANSI(), setDefaultSignANSI(boolean)

setSignANSI
```
public void setSignANSI(boolean signANSI)
```
Defines whether numeric fields are stored in this Message using the ANSI or the TANDEM mechanism. If signANSI is true, numeric fields will be stored using the ANSI mechanism. Otherwise, numeric fields will be stored using the TANDEM mechanism. Important: this method does not! change the representation of the numeric fields that are currently stored in this Message. It defines how numeric fields will be stored in future calls to the setNumber or the setString methods.

Parameters:

signANSI - if true numeric fields will be stored using the ANSI mechanism. Otherwise, the TANDEM mechanism will be used.

See Also:

getSignANSI(), getDefaultSignANSI(), setDefaultSignANSI(boolean)

getDefaultSignANSI
```
public static boolean getDefaultSignANSI()
```
Returns true if, by default, numeric fields are stored in messages using the ANSI mechanism. Otherwise, numeric fields are stored using the TANDEM mechanism. When a new Message is created it uses this global value to initialize its behavior. This default behavior can be changed on individual messages using the setSignANSI method.

Returns:

true if, by default, numeric fields are stored using the ANSI mechanism. Otherwise, the TANDEM mechanism is used.

See Also:

setDefaultSignANSI(boolean), getSignANSI(), setSignANSI(boolean)

setDefaultSignANSI
```
public static void setDefaultSignANSI(boolean signANSI)
```
Defines if, by default, numeric fields are stored in messages using the ANSI or the TANDEM mechanism. If signANSI is true, numeric fields will be stored using the ANSI mechanism. Otherwise, numeric fields will be stored using the TANDEM mechanism. When a new Message is created it uses this global value to initialize its behavior. This default behavior can be changed on individual messages using the setSignANSI method.

Parameters:

signANSI - if true numeric fields will be stored, by default, using the ANSI mechanism. Otherwise, the TANDEM mechanism will be used.

See Also:

getDefaultSignANSI(), getSignANSI(), setSignANSI(boolean)

getType
```
public int getType()
```
Returns the type of the Message (Message.Type).

Returns:

the type of the Message (Message.Type).

setType
```
public void setType(int type)
```
Changes the type of the Message (Message.Type).

Parameters:

type - the new type of the Message (Message.Type).

getSequence
```
public int getSequence()
```
Returns the sequence number of the Message.

Returns:

the sequence number of the Message.

See Also:

setSequence(int)

setSequence
```
public void setSequence(int sequence)
```
Changes the sequence number of the Message.

Parameters:

sequence - the new sequence number of the Message.

See Also:

getSequence()

getOperCode
```
public int getOperCode()
```
Returns the operation code of the Message (Message.Oper).

Returns:

the operation code of the Message (Message.Oper).

See Also:

setOperCode(int)

setOperCode
```
public void setOperCode(int opcode)
```
Changes the operation code of the Message (Message.Oper).

Parameters:

opcode - the new operation code (Message.Oper).

See Also:

getOperCode()

getSessionID
```
public int getSessionID()
```
Returns the session ID of this Message.

Returns:

the session ID of this Message.

See Also:

setSessionID(int)

setSessionID
```
public void setSessionID(int sessionID)
```
Changes the session ID of this Message.

Parameters:

sessionID - new Message session ID.

See Also:

getSessionID()

getTranCode
```
public int getTranCode()
```
Returns the transaction code of this Message.

Returns:

the transaction code of this Message.

See Also:

setTranCode(int)

setTranCode
```
public void setTranCode(int tranCode)
```
Changes the transaction code of this Message.

Parameters:

tranCode - new Message transaction code.

See Also:

getTranCode()

getReplyCode
```
public int getReplyCode()
```
Returns the reply code of this Message (Message.Reply).

Returns:

the reply code of this Message (Message.Reply).

See Also:

setReplyCode(int)

setReplyCode
```
public void setReplyCode(int replyCode)
```
Changes the reply code of this Message (Message.Reply).

Parameters:

replyCode - new Message reply code (Message.Reply).

See Also:

getReplyCode()

getProtCode
```
public int getProtCode()
```
Returns the protection code of this Message (Message.Prot).

Returns:

the protection code of this Message (Message.Prot).

See Also:

setProtCode(int)

setProtCode
```
public void setProtCode(int protCode)
```
Changes the protection code of this Message (Message.Prot).

Parameters:

protCode - new Message protection code (Message.Prot).

See Also:

getProtCode()

getServerCode
```
public int getServerCode()
```
Returns the server code of this Message.

Returns:

the server code of this Message.

See Also:

setServerCode(int)

setServerCode
```
public void setServerCode(int serverCode)
```
Changes the server code of this Message.

Parameters:

serverCode - new Message server code.

See Also:

getServerCode()

getFormCode
```
public int getFormCode()
```
Returns the form code of this Message.

Returns:

the form code of this Message.

See Also:

setFormCode(int)

setFormCode
```
public void setFormCode(int formCode)
```
Changes the form code of this Message.

Parameters:

formCode - new Message form code.

See Also:

getFormCode()

getMulticastName
```
public String getMulticastName()
```
Returns the multicast name of this Message. If this is not a multicast Message, it returnes null.

Returns:

the multicast name of this Message or null.

getMinLabelKey
```
public int getMinLabelKey()
```
Returns the minimum label key of all Message labels.

Returns:

the minimum label key of all Message labels.

getMaxLabelKey
```
public int getMaxLabelKey()
```
Returns the maximum label key of all Message labels.

Returns:

the maximum label key of all Message labels.

hasLabel
```
public boolean hasLabel(int key)
```
Returns true if the label indexed by key exists.

Parameters:

key - the index of the label (Message.Label).

Returns:

true if the label indexed by key exists.

getLabel
```
public String getLabel(int key)
```
Returns the string value of the label identified by key. If the required label is not defined, it returns null. There is not way to know if the value of a label was actually null or if the label was undefined.

Parameters:

key - the index of the label (Message.Label).

Returns:

the string value of the required label.

Throws:

IndexOutOfBoundsException - if key is out-of-bounds.

See Also:

setLabel(int, String), removeLabel(int), removeLabels()

setLabel
```
public void setLabel(int key,
                     String value)
```
Changes the string value of the label identified by key. Setting the value of the label to null has the effect as removing the label from this Message. That is, it has exactly the same effect as calling the removeLabel method with the same key.

Parameters:

key - the index of the label (Message.Label).

value - new value of the label or null.

Throws:

IndexOutOfBoundsException - if key is out-of-bounds.

See Also:

getLabel(int), removeLabel(int), removeLabels()

removeLabel
```
public void removeLabel(int key)
```
Removes the label identified by key from this Message. Nothing happens if the label is not defined in this Message.

Parameters:

key - the index of the label (Message.Label).

Throws:

IndexOutOfBoundsException - if key is out-of-bounds.

See Also:

getLabel(int), setLabel(int, String), removeLabels()

removeLabels
```
public void removeLabels()
```
Removes all the labels defined in this Message.

See Also:

getLabel(int), setLabel(int, String), removeLabel(int)

isDataOnly
```
public boolean isDataOnly()
```
Returns true if this is a data-only Message.

Returns:

true if this is a data-only Message.

setDataOnly
```
public void setDataOnly(boolean value)
```
Changes whether this is a data-only Message.

Parameters:

value - the new value of the property.

getDataBytes
```
public byte[] getDataBytes()
```
Returns the binary data of this Message.

Returns:

the binary data of this Message.

See Also:

setDataBytes(byte[])

setDataBytes
```
public void setDataBytes(byte[] bytes)
```
Changes the binary data of this Message.

Parameters:

bytes - the new binary data of this Message.

See Also:

getDataBytes()

getDataAll
```
public String getDataAll()
```
Returns all text data of this Message.

Returns:

all text data of this Message.

See Also:

getData(), setData(String)

getData
```
public String getData()
```
Returns the text data of this Message with trailing space characters removed (right trimmed).

Returns:

the text data of this Message right trimmed.

See Also:

getDataAll(), setData(String)

setData
```
public void setData(String data)
```
Changes the text data of this Message.

Parameters:

data - the new text data of this Message.

See Also:

getData(), getDataAll()

substring
```
public String substring(int start,
                        int end)
```
Returns a new string that is a substring of this Message. The substring begins at the specified start and extends to the character at index end-1. Thus the length of the substring is end-start. If the first character of the substring is NO-DATA (0x1a) it returns null. The trailing space characters of the the substring are removed (right trimmed).

Parameters:

start - the start index of the substring.

end - the end index of the substring.

Returns:

the substring defined by start and end.

replace
```
public void replace(int start,
                    int end,
                    String value)
```
Replaces the characters in a substring of the message data with characters in the specified String. The substring begins at the specified start and extends to the character at index end-1. If needed, the capacity of the data is extended so the entire substring can be stored. If the String is null the substring is filled with NO-DATA (0x1a). If the String is shorter than the substring, the rest is filled with spaces.

Parameters:

start - the start index of the substring.

end - the end index of the substring.

value - the value that will replace the substring.

getLayout
```
public Layout getLayout()
```
Returns the current layout of this Message. It returns null if the Message has no defined layout.

Returns:

the layout of this Message or null.

See Also:

setLayout(Layout), verifyLayout(String), Layout

setLayout
```
public void setLayout(Layout layout)
```
Changes the layout of this Message. If layout is null, the Message will have no defined layout.

Parameters:

layout - new layout of this Message.

See Also:

getLayout(), verifyLayout(String), Layout

getField
```
public LayoutField getField(String fieldName)
```
Returns the field identified by fieldName. It returns null if this Message does not have a defined layout, or if the field is not defined in the layout.

Parameters:

fieldName - name of the layout field.

Returns:

the field identified by fieldName or null.

See Also:

Layout.getField(String)

exists
```
public boolean exists(String fieldName)
```
Returns true if the field indexed by fieldName exists in the Layout of this Message. If returns false if this Message does not have a defined layout, or if the field is not defined in the layout.

Parameters:

fieldName - the name of the layout field.

Returns:

true if the field is defined.

See Also:

Layout.exists(String)

getOccurs
```
public int getOccurs(String fieldName)
```
Returns the number of occurrences of the field identified by fieldName. It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout.

Parameters:

fieldName - name of the required field.

Returns:

the number of occurrences of the specified field.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

See Also:

LayoutField.getOccurs()

isNull
```
public boolean isNull(String fieldName)
```
Returns true if the value of the field identified by fieldName is NULL. The value of a field is NULL when the first character of it's data sequence is NO-DATA (0x1a). It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. This method has exactly the same effect as calling isNull(fieldName, 0).

Parameters:

fieldName - name of the required field.

Returns:

true if the specified field is NULL.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

See Also:

isNull(String, int), setNull(String)

isNull
```
public boolean isNull(String fieldName,
                      int index)
```
Returns true if the value of the field identified by fieldName and index is NULL. The value of a field is NULL when the first character of it's data sequence is NO-DATA (0x1a). It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. It also throws an exception if index is out of bounds.

Parameters:

fieldName - name of the required field.

index - index of the required field occurrence.

Returns:

true if the specified field is NULL.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

IndexOutOfBoundsException - if index is out of bounds.

See Also:

setNull(String, int)

setNull
```
public void setNull(String fieldName)
```
Updates the value of the field identified by fieldName to NULL. A field is NULL if the first character of it's data sequence is NO-DATA (0x1a). This method has exactly the same effect as calling setNull(fieldName, 0).

Parameters:

fieldName - name of the required field.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

See Also:

isNull(String), setNull(String, int)

setNull
```
public void setNull(String fieldName,
                    int index)
```
Changes the value of the field identified by fieldName and index to NULL. A field is NULL if the first character of it's data sequence is NO-DATA (0x1a). It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. It also throws an exception if index is out of bounds.

Parameters:

fieldName - name of the required field.

index - index of the required field occurrence.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

IndexOutOfBoundsException - if index is out of bounds.

See Also:

isNull(String, int)

verifyLayout
```
public Layout verifyLayout(String layoutName)
```
Verifies that the name of the layout of this Message matches the supplied layoutName. If this Message has no defined layout, or if the layout names do not match, then an IllegalArgumentException is thrown. This convenience method is normally used in the implementation of methods that process transaction requests whose data must be sent from a client application with a particular structure (or layout).

Parameters:

layoutName - the name of the required layout.

Returns:

the layout of this Message.

Throws:

NullPointerException - if layoutName is null.

IllegalArgumentException - if the layout names do not match.

See Also:

getLayout(), setLayout(Layout), Layout

initFields
```
public void initFields()
```
Set the value of each field of this Message to its default value. The default value of a layout field is obtained using the getDefault method. If this Message has no defined layout, nothing happens.

See Also:

LayoutField.getDefault(), initFields(Message)

initFields
```
public void initFields(Message source)
```
Set the value of each field of this Message to the value of its corresponding field in source. Two fields are said to correspond if they have the same name and type. If a field has no corresponding field in source, then its value is set to its default value. If source is null or if source has no defined layout, then this methods operates exactly as the initFields() method. If this Message has no defined layout, nothing happens.

Parameters:

source - the Message with corresponding fields.

See Also:

initFields(), LayoutField.getDefault()

getData
```
public String getData(String fieldName)
```
Returns the internal character sequence of the field identified by fieldName. It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. This method has exactly the same effect as calling getData(fieldName, 0).

Parameters:

fieldName - name of the required field.

Returns:

the internal character sequence of the specified field or null.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

See Also:

getData(String, int), setData(String, String)

getData
```
public String getData(String fieldName,
                      int index)
```
Returns the internal character sequence of the field identified by fieldName and index. If this sequence starts with NO-DATA (0x1a) it returns null. The trailing space characters of the returned string are removed (right trim). It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. It also throws an exception if index is out of bounds.

Parameters:

fieldName - name of the required field.

index - index of the required field occurrence.

Returns:

the internal character sequence of the specified field or null.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

IndexOutOfBoundsException - if index is out of bounds.

See Also:

setData(String, int, String)

setData
```
public void setData(String fieldName,
                    String value)
```
Updates the internal character sequence of the field identified by fieldName. It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. This method has exactly the same effect as calling setData(fieldName, 0, value).

Parameters:

fieldName - name of the required field.

value - the new internal character sequence of the specified field.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

See Also:

getString(String), setString(String, int, String)

setData
```
public void setData(String fieldName,
                    int index,
                    String value)
```
Updates the internal character sequence of the field identified by fieldName and index. If value is null the sequence is filled with NO-DATA (0x1a). It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. It also throws an exception if index is out of bounds.

Parameters:

fieldName - name of the required field.

index - index of the required field occurrence.

value - the new internal character sequence of the specified field.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

IndexOutOfBoundsException - if index is out of bounds.

See Also:

getData(String, int)

getString
```
public String getString(String fieldName)
```
Returns the string value of the field identified by fieldName. If the value of the field is NULL (see isNull for details) it returns null. It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. This method has exactly the same effect as calling getString(fieldName, 0).

Parameters:

fieldName - name of the required field.

Returns:

the string value of the specified field or null.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

See Also:

getString(String, int), setString(String, String), isNull(String)

getString
```
public String getString(String fieldName,
                        int index)
```
Returns the string value of the field identified by fieldName and index. If the value of the field is NULL (see isNull for details) it returns null. If the field is a LayoutField.LIST and the index value is -1, then a string containing all the occurrences of the list is returned. It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. It also throws an exception if index is out of bounds.

Parameters:

fieldName - name of the required field.

index - index of the required field occurrence.

Returns:

the string value of the specified field or null.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

IndexOutOfBoundsException - if index is out of bounds.

See Also:

setString(String, int, String), isNull(String, int)

setString
```
public void setString(String fieldName,
                      String value)
```
Updates the string value of the field identified by fieldName. If value is null then the field's data is set to NULL (see isNull for details). It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. This method has exactly the same effect as calling setString(fieldName, 0, value).

Parameters:

fieldName - name of the required field.

value - the new string value of the specified field.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

See Also:

getString(String), setString(String, int, String), isNull(String, int)

setString
```
public void setString(String fieldName,
                      int index,
                      String value)
```
Updates the string value of the field identified by fieldName and index. If value is null then the field's data is set to NULL (see isNull for details). If the field is a LayoutField.LIST and the index value is -1, then the string containing all the occurrences of this list field is updated with the supplied value. It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. It also throws an exception if index is out of bounds.

Parameters:

fieldName - name of the required field.

index - index of the required field occurrence.

value - the new string value of the specified field.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

IndexOutOfBoundsException - if index is out of bounds.

See Also:

getString(String, int), isNull(String, int)

getChar
```
public char getChar(String fieldName)
```
Returns the character value of the field identified by fieldName . If the value of the field is NULL (see isNull for details) it returns ' '. It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. This method has exactly the same effect as calling getChar(fieldName, 0).

Parameters:

fieldName - name of the required field.

Returns:

the character value of the specified field or ' '.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

See Also:

getChar(String, int), setChar(String, char), isNull(String)

getChar
```
public char getChar(String fieldName,
                    int index)
```
Returns the character value of the field identified by fieldName and index. If the value of the field is NULL (see isNull for details) it returns ' '. It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. It also throws an exception if index is out of bounds. This is a utility method that returns the first character of the string returned by the getString method.

Parameters:

fieldName - name of the required field.

index - index of the required field occurrence.

Returns:

the character value of the specified field or ' '.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

IndexOutOfBoundsException - if index is out of bounds.

See Also:

setChar(String, int, char), isNull(String, int), getString(String, int)

setChar
```
public void setChar(String fieldName,
                    char value)
```
Updates the character value of the field identified by fieldName. It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. This method has exactly the same effect as calling setChar(fieldName, 0, value).

Parameters:

fieldName - name of the required field.

value - the new character value of the specified field.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

See Also:

getChar(String), setChar(String, int, char)

setChar
```
public void setChar(String fieldName,
                    int index,
                    char value)
```
Updates the character value of the field identified by fieldName and index. It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. It also throws an exception if index is out of bounds. This is a utility method that calls the setString method with a string containing just the supplied character value.

Parameters:

fieldName - name of the required field.

index - index of the required field occurrence.

value - the new character value of the specified field.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

IndexOutOfBoundsException - if index is out of bounds.

See Also:

getChar(String, int), setString(String, int, String)

getNumber
```
public BigDecimal getNumber(String fieldName)
```
Returns the decimal value of the field identified by fieldName. If the value of the field is NULL (see isNull for details) it returns null. It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. This method has exactly the same effect as calling getNumber(fieldName, 0).

Parameters:

fieldName - name of the required field.

Returns:

the decimal value of the specified field or null.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

See Also:

getNumber(String, int), setNumber(String, BigDecimal), isNull(String)

getNumber
```
public BigDecimal getNumber(String fieldName,
                            int index)
```
Returns the decimal value of the field identified by fieldName and index. If the value of the field is NULL (see isNull for details) it returns null. It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. It also throws an exception if index is out of bounds.

Parameters:

fieldName - name of the required field.

index - index of the required field occurrence.

Returns:

the decimal value of the specified field or null.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

IndexOutOfBoundsException - if index is out of bounds.

See Also:

setNumber(String, int, BigDecimal), isNull(String, int)

setNumber
```
public void setNumber(String fieldName,
                      BigDecimal value)
```
Updates the decimal value of the field identified by fieldName. If value is null then the field's data is set to NULL (see isNull for details). It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. This method has exactly the same effect as calling setNumber(fieldName, 0, value).

Parameters:

fieldName - name of the required field.

value - the new decimal value of the specified field.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

See Also:

getNumber(String), setNumber(String, int, BigDecimal), isNull(String)

setNumber
```
public void setNumber(String fieldName,
                      int index,
                      BigDecimal value)
```
Updates the decimal value of the field identified by fieldName and index. If value is null then the field's data is set to NULL (see isNull for details). It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. It also throws an exception if index is out of bounds.

Parameters:

fieldName - name of the required field.

index - index of the required field occurrence.

value - the new decimal value of the specified field.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

IndexOutOfBoundsException - if index is out of bounds.

See Also:

getNumber(String, int), isNull(String, int)

getDouble
```
public double getDouble(String fieldName)
```
Returns the double value of the field identified by fieldName. If the value of the field is NULL (see isNull for details) it returns 0. It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. This method has exactly the same effect as calling getDouble(fieldName, 0).

Parameters:

fieldName - name of the required field.

Returns:

the double value of the specified field or 0.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

See Also:

getDouble(String, int), setDouble(String, double), isNull(String)

getDouble
```
public double getDouble(String fieldName,
                        int index)
```
Returns the double value of the field identified by fieldName and index. If the value of the field is NULL (see isNull for details) it returns 0. It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. It also throws an exception if index is out of bounds.

Parameters:

fieldName - name of the required field.

index - index of the required field occurrence.

Returns:

the double value of the specified field or o.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

IndexOutOfBoundsException - if index is out of bounds.

See Also:

setDouble(String, int, double), isNull(String, int)

setDouble
```
public void setDouble(String fieldName,
                      double value)
```
Updates the double value of the field identified by fieldName. It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. This method has exactly the same effect as calling setDouble(fieldName, 0, value).

Parameters:

fieldName - name of the required field.

value - the new double value of the specified field.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

See Also:

getDouble(String), setDouble(String, int, double)

setDouble
```
public void setDouble(String fieldName,
                      int index,
                      double value)
```
Updates the double value of the field identified by fieldName and index. It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. It also throws an exception if index is out of bounds.

Parameters:

fieldName - name of the required field.

index - index of the required field occurrence.

value - the new double value of the specified field.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

IndexOutOfBoundsException - if index is out of bounds.

See Also:

getDouble(String, int)

getInteger
```
public int getInteger(String fieldName)
```
Returns the integer value of the field identified by fieldName. If the value of the field is NULL (see isNull for details) it returns 0. It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. This method has exactly the same effect as calling getInteger(fieldName, 0).

Parameters:

fieldName - name of the required field.

Returns:

the integer value of the specified field or 0.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

See Also:

getInteger(String, int), setInteger(String, int), isNull(String)

getInteger
```
public int getInteger(String fieldName,
                      int index)
```
Returns the integer value of the field identified by fieldName and index. If the value of the field is NULL (see isNull for details) it returns 0. It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. It also throws an exception if index is out of bounds.

Parameters:

fieldName - name of the required field.

index - index of the required field occurrence.

Returns:

the integer value of the specified field or 0.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

IndexOutOfBoundsException - if index is out of bounds.

See Also:

setInteger(String, int, int), isNull(String, int)

setInteger
```
public void setInteger(String fieldName,
                       int value)
```
Updates the integer value of the field identified by fieldName. It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. This method has exactly the same effect as calling setInteger(fieldName, 0, value).

Parameters:

fieldName - name of the required field.

value - the new integer value of the specified field.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

See Also:

getInteger(String), setInteger(String, int, int)

setInteger
```
public void setInteger(String fieldName,
                       int index,
                       int value)
```
Updates the integer value of the field identified by fieldName and index. It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. It also throws an exception if index is out of bounds.

Parameters:

fieldName - name of the required field.

index - index of the required field occurrence.

value - the new integer value of the specified field.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

IndexOutOfBoundsException - if index is out of bounds.

See Also:

getInteger(String, int)

getDate
```
public Date getDate(String fieldName)
```
Returns the date value of the field identified by fieldName. If the value of the field is NULL (see isNull for details) it returns null. It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. This method has exactly the same effect as calling getDate(fieldName, 0).

Parameters:

fieldName - name of the required field.

Returns:

the date value of the specified field or null.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

See Also:

getDate(String, int), setDate(String, Date), isNull(String)

getDate
```
public Date getDate(String fieldName,
                    int index)
```
Returns the date value of the field identified by fieldName and index. If the value of the field is NULL (see isNull for details) it returns null. It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. It also throws an exception if index is out of bounds.

Parameters:

fieldName - name of the required field.

index - index of the required field occurrence.

Returns:

the date value of the specified field or null.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

IndexOutOfBoundsException - if index is out of bounds.

See Also:

setDate(String, int, Date), isNull(String, int)

setDate
```
public void setDate(String fieldName,
                    Date value)
```
Updates the date value of the field identified by fieldName. If value is null then the field's data is set to NULL (see isNull for details). It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. This method has exactly the same effect as calling setDate(fieldName, 0, value).

Parameters:

fieldName - name of the required field.

value - the new date value of the specified field.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

See Also:

getDate(String), setDate(String, int, Date), isNull(String)

setDate
```
public void setDate(String fieldName,
                    int index,
                    Date value)
```
Updates the date value of the field identified by fieldName and index. If value is null then the field's data is set to NULL (see isNull for details). It throws an exception if this Message has no defined layout, or if the required field is not defined in the layout. It also throws an exception if index is out of bounds.

Parameters:

fieldName - name of the required field.

index - index of the required field occurrence.

value - the new date value of the specified field.

Throws:

IllegalStateException - if no layout is defined.

IllegalArgumentException - if the field does not exist.

IndexOutOfBoundsException - if index is out of bounds.

See Also:

getDate(String, int), isNull(String, int)

toMessage
```
public static Message toMessage(Object value)
```
Converts the supplied object value to a Message. If the value is null, it returns a new Message with empty data. If the value is an instance of a Message, it returns value. Otherwise, the value is converted to a string using the standard Object.toString() method, and this string is used as the data of a new Message.

Parameters:

value - object value to convert to a Message.

Returns:

the Message obtained from the value.

See Also:

Object.toString()

toString
```
public String toString()
```
Returns a string representation of this Message.

Overrides:

toString in class Object

Returns:

a string representation of this Message.

See Also:

Object.toString()

serialize
```
public byte[] serialize()
```
Returns a serialized version of this Message. This method has exactly the same effect as calling serialize(false).

Returns:

a serialized version of this Message.

See Also:

serialize(boolean), Message

serialize
```
public byte[] serialize(boolean withType)
```
Returns a serialized version of this Message with optional type code. See Message for a detailed explanation of how a Message is serialized.

Parameters:

withType - if true the result includes the message type.

Returns:

a serialized version of this Message.

See Also:

unserialize(byte[], int, int), Message

unserialize
```
public static Message unserialize(byte[] bytes,
                                  int offset,
                                  int length)
```
Creates a new Message by unserializing the supplied byte array. This method has exactly the same effect as calling unserialize(bytes, offset, length, false).

Parameters:

bytes - array of bytes containing a serialized Message.

offset - initial offset of the bytes subarray.

length - length of the bytes subarray.

Returns:

a new Message.

See Also:

unserialize(byte[], int, int, boolean), Message

unserialize
```
public static Message unserialize(byte[] bytes,
                                  int offset,
                                  int length,
                                  boolean withType)
```
Creates a new Message by unserializing the supplied byte array with optional type code. See Message for a detailed explanation of how a Message is serialized.

Parameters:

bytes - array of bytes containing a serialized Message.

offset - initial offset of the bytes subarray.

length - length of the bytes subarray.

withType - if true bytes include the message type.

Returns:

a new Message.

See Also:

serialize(), Message

clone
```
public Object clone()
```
Returns a "deep" copy of this Message.

Overrides:

clone in class Object

Returns:

a "deep" copy of this Message.

toXml
```
public String toXml(boolean indent)
```
Returns the XML string representation of the data stored in this Message. If indent is true then the XML string will have additional whitespace included to indent the XML tree. For example, consider a layout named CONTACT with four fields called SERVICE, GROUP, USERNAME and USERCODE. The string returned by this method for a Message with layout CONTACT would be identical to the following indented XML tree, except for the values of the fields which are shown in italics:
```
 <CONTACT>
     <SERVICE>service</SERVICE>
     <GROUP>group</GROUP>
     <USERNAME>user</USERNAME>
     <USERCODE>12345</USERCODE>
 </CONTACT>
```
Parameters:

indent - specifies whether to indent the XML representation.

Returns:

the XML representation of the data stored in this Message.

Throws:

NetException - if a transformation error occurs.

See Also:

getData(), getLayout()

toTagString
```
public String toTagString(String separator)
```
Returns a string with the TAG representation of the data stored in this Message. The value of separator is used to mark the end of each field of the Message. For example, consider a Message with a layout named CONTACT that containts four fields SERVICE, GROUP, USERNAME and USERCODE. The TAG representation of this Message with a separator of ";" is the following:
```
 CONTACT[SERVICE=service;GROUP=group;USERNAME=user;USERCODE=12345;]
```
Parameters:

separator - string that separates the values of the fields.

Returns:

the TAG representation of the data stored in this Message.

See Also:

getData(), getLayout()

Class Message

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Message

Message

Method Detail

isStrict

setStrict

getSignANSI

setSignANSI

getDefaultSignANSI

setDefaultSignANSI

getType

setType

getSequence

setSequence

getOperCode

setOperCode

getSessionID

setSessionID

getTranCode

setTranCode

getReplyCode

setReplyCode

getProtCode

setProtCode

getServerCode

setServerCode

getFormCode

setFormCode

getMulticastName

getMinLabelKey

getMaxLabelKey

hasLabel

getLabel

setLabel

removeLabel

removeLabels

isDataOnly

setDataOnly

getDataBytes

setDataBytes

getDataAll

getData

setData

substring

replace

getLayout

setLayout

getField

exists

getOccurs

isNull

isNull

setNull

setNull

verifyLayout

initFields

initFields

getData

getData

setData

setData

getString

getString

setString

setString

getChar

getChar

setChar

setChar

getNumber

getNumber

setNumber

setNumber

getDouble

getDouble