Class FSDMsg

java.lang.Object
org.jpos.util.FSDMsg
All Implemented Interfaces:
Cloneable, Loggeable
public class FSDMsg extends Object implements Loggeable, Cloneable
General purpose, Field Separator delimited message.

How to use

The message format (or schema) is defined in xml files containing a schema element, with an optional id attribute, and multiple field elements. A field element is made up of the following attributes:

id
The name of the field. This is used in calls to set(String, String). It should be unique amongst the fields in an FSDMsg.
length
The maximum length of the data allowed in this field. Fixed length fields will be padded to this length. A zero length is allowed, and can be useful to define extra separator characters in the message.
type
The type of the included data, including an optional separator for marking the end of the field and the beginning of the next one. The data type is defined by the first char of the type, and the separator is defined by the following chars. If a field separator is specified, then no padding is done on values for this field.
key
If this optional attribute has a value of "true", then fields from another schema, specified by the value, are appended to this schema.
separator
An optional attribute containing the separator for the field. This is the preferred method of specifying the separator. See the list of optional

Possible types are:

A
Alphanumeric. Padding if any is done with spaces to the right.
B
Binary. Padding, if any, is done with zeros to the left.
K
Constant. The value is specified by the field content. No padding is done.
N
Numeric. Padding, if any, is done with zeros to the left.

Supported field separators are:

FS
Field separator using '034' as the separator.
US
Field separator using '037' as the separator.
GS
Group separator using '035' as the separator.
RS
Row separator using '036' as the separator.
PIPE
Field separator using '|' as the separator.
EOF
End of File - no separator character is emitted, but also no padding is done. Also if the end of file is reached parsing a message, then no exception is thrown.
DS
A dummy separator. This is similar to EOF, but the message stream must not end before it is allowed.
EOM
End of message separator. This reads all bytes available in the stream.

Key fields allow you to specify a tree of possible message formats. The key fields are the fork points of the tree. Multiple key fields are supported. It is also possible to have more key fields specified in appended schemas.

Since:
1.4.7

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static char
    EOF
    End of File character (null byte).
    static char
    EOM
    End of Message marker (null byte).
    static char
    FS
    Field Separator character (ASCII 0x1C).
    static char
    GS
    Group Separator character (ASCII 0x1D).
    static char
    PIPE
    Pipe character (ASCII 0x7C).
    static char
    RS
    Record Separator character (ASCII 0x1E).
    static char
    US
    Unit Separator character (ASCII 0x1F).

  • Constructor Summary

    Constructors
    Constructor
    Description
    FSDMsg(String basePath)
    Creates a FSDMsg with a specific base path for the message format schema.
    FSDMsg(String basePath, String baseSchema)
    Creates a FSDMsg with a specific base path for the message format schema, and a base schema name.

  • Method Summary

    Modifier and Type
    Method
    Description
    Object
    clone()
     
    void
    copy(String fieldName, FSDMsg msg)
    Copies a field value from another FSDMsg into this message.
    void
    copy(String fieldName, FSDMsg msg, String def)
    Copies a field value from another FSDMsg into this message, using a default if not present.
    void
    dump(PrintStream p, String indent)
    Dumps a human-readable representation of this object to the print stream.
    boolean
    equals(Object o)
     
    String
    get(String fieldName)
    Returns the value of the named field.
    String
    get(String fieldName, String def)
    Returns the value of the named field, or a default if not set.
    protected String
    get(String id, String type, int length, String defValue, String separator)
    Returns the formatted value for the named field.
    protected String
    get(String id, String type, int length, String defValue, String separator, boolean unPad)
    Returns the formatted value for the named field with optional unpadding.
    String
    getBasePath()
    Returns the base schema path used to load field definitions.
    String
    getBaseSchema()
    Returns the base schema name used to load field definitions.
    byte[]
    getHeader()
    Returns the binary header bytes.
    byte[]
    getHexBytes(String name)
    Returns the value of the named field decoded from hex.
    String
    getHexHeader()
    Returns the header as a hex string, or empty string if no header is set.
    int
    getInt(String name)
    Returns the integer value of the named field, or 0 if absent or non-numeric.
    int
    getInt(String name, int def)
    Returns the integer value of the named field, or a default if absent or non-numeric.
    Map
    getMap()
    Returns the underlying fields map.
    protected org.jdom2.Element
    getSchema()
    Returns the root schema Element for the base schema.
    protected org.jdom2.Element
    getSchema(String message)
    Returns the root schema Element for the named message schema.
    protected org.jdom2.Element
    getSchema(String prefix, String suffix, String defSuffix)
    Returns the root schema Element located at the given path.
    boolean
    hasField(String fieldName)
    Returns true if this message has a value for the named field.
    int
    hashCode()
     
    boolean
    isSeparator(byte b)
    Tests whether a byte matches any configured separator character.
    protected org.jdom2.Element
    loadSchema(String uri, boolean throwex)
    Loads and parses the schema from the given URI.
    void
    merge(FSDMsg m)
    Copies all fields from the given message into this message.
    String
    pack()
    Packs this FSDMsg into its string representation.
    protected void
    pack(org.jdom2.Element schema, StringBuilder sb)
    Packs this message into the given StringBuilder using the provided schema.
    byte[]
    packToBytes()
    Packs this message into a byte array.
    protected String
    read(InputStreamReader r, int len, String type, String separator)
    Reads a field value from the stream.
    protected String
    readField(InputStreamReader r, String fieldName, int len, String type, String separator)
    Reads a named field value from the stream.
    protected InputStream
    schemaResouceInputStream(String resource)
    Returns an InputStream for the given classpath resource.
    void
    set(String name, String value)
    Sets a field value; removes the field if value is null.
    void
    setCharset(Charset charset)
    Sets the character set used for packing and unpacking string fields.
    void
    setHeader(byte[] h)
    Sets the binary header bytes for this message.
    void
    setMap(Map fields)
    Sets the underlying fields map.
    void
    setSeparator(String separatorName, char separator)
    Adds or overrides a separator type/char pair.
    org.jdom2.Element
    toXML()
    Serializes this FSDMsg to a JDOM XML Element.
    void
    unpack(byte[] b)
    parse message.
    void
    unpack(InputStream is)
    parse message.
    protected void
    unpack(InputStreamReader r, org.jdom2.Element schema)
    Unpacks a message from the reader using the provided schema.
    void
    unsetSeparator(String separatorName)
    Removes a previously defined separator type.

    Methods inherited from class Object

    finalize, getClass, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface Loggeable

    dump
    Modifier and Type
    Method
    Description
    default void
    dump(PrintStream p, String indent, LogRenderer.Type type)
    Dumps a representation of this object using the specified renderer type.

  • Field Details

    • FS

      public static char FS
      Field Separator character (ASCII 0x1C).

    • US

      public static char US
      Unit Separator character (ASCII 0x1F).

    • GS

      public static char GS
      Group Separator character (ASCII 0x1D).

    • RS

      public static char RS
      Record Separator character (ASCII 0x1E).

    • EOF

      public static char EOF
      End of File character (null byte).

    • PIPE

      public static char PIPE
      Pipe character (ASCII 0x7C).

    • EOM

      public static char EOM
      End of Message marker (null byte).

  • Constructor Details

    • FSDMsg

      public FSDMsg(String basePath)
      Creates a FSDMsg with a specific base path for the message format schema.
      Parameters:
      basePath - schema path, for example: "file:src/data/NDC-" looks for a file src/data/NDC-base.xml

    • FSDMsg

      public FSDMsg(String basePath, String baseSchema)
      Creates a FSDMsg with a specific base path for the message format schema, and a base schema name. For instance, FSDMsg("file:src/data/NDC-", "root") will look for a file: src/data/NDC-root.xml
      Parameters:
      basePath - schema path
      baseSchema - schema name

  • Method Details

    • getBasePath

      public String getBasePath()
      Returns the base schema path used to load field definitions.
      Returns:
      the base schema path

    • getBaseSchema

      public String getBaseSchema()
      Returns the base schema name used to load field definitions.
      Returns:
      the base schema name

    • setCharset

      public void setCharset(Charset charset)
      Sets the character set used for packing and unpacking string fields.
      Parameters:
      charset - the character set to use

    • setSeparator

      public void setSeparator(String separatorName, char separator)
      Adds or overrides a separator type/char pair.
      Parameters:
      separatorName - string identifier for the separator type (e.g. "FS", "US")
      separator - the character representing this separator

    • unsetSeparator

      public void unsetSeparator(String separatorName)
      Removes a previously defined separator type.
      Parameters:
      separatorName - string identifier for the separator type to remove
      Throws:
      IllegalArgumentException - if the separator was not previously defined

    • unpack

      public void unpack(InputStream is) throws IOException, org.jdom2.JDOMException
      parse message. If the stream ends before the message is completely read, then the method adds an EOF field.
      Parameters:
      is - input stream
      Throws:
      IOException - on I/O error
      org.jdom2.JDOMException - on XML parsing error

    • unpack

      public void unpack(byte[] b) throws IOException, org.jdom2.JDOMException
      parse message. If the stream ends before the message is completely read, then the method adds an EOF field.
      Parameters:
      b - message image
      Throws:
      IOException - on I/O error while reading the byte array
      org.jdom2.JDOMException - on schema parsing error

    • pack

      public String pack() throws org.jdom2.JDOMException, IOException, ISOException
      Packs this FSDMsg into its string representation.
      Returns:
      the packed message string
      Throws:
      org.jdom2.JDOMException - on schema parsing error
      IOException - on I/O error
      ISOException - on packing error

    • packToBytes

      public byte[] packToBytes() throws org.jdom2.JDOMException, IOException, ISOException
      Packs this message into a byte array.
      Returns:
      the packed bytes
      Throws:
      ISOException - on pack error
      IOException - on I/O error
      org.jdom2.JDOMException - on schema parse error

    • get

      protected String get(String id, String type, int length, String defValue, String separator) throws ISOException
      Returns the formatted value for the named field.
      Parameters:
      id - field identifier
      type - field type
      length - field length
      defValue - default value if field is absent
      separator - field separator
      Returns:
      formatted field value
      Throws:
      ISOException - on error

    • get

      protected String get(String id, String type, int length, String defValue, String separator, boolean unPad) throws ISOException
      Returns the formatted value for the named field with optional unpadding.
      Parameters:
      id - field identifier
      type - field type
      length - field length
      defValue - default value
      separator - field separator
      unPad - if true, strip padding
      Returns:
      formatted field value
      Throws:
      ISOException - on error

    • isSeparator

      public boolean isSeparator(byte b)
      Tests whether a byte matches any configured separator character.
      Parameters:
      b - the byte to test
      Returns:
      true if the byte corresponds to any configured separator

    • pack

      protected void pack(org.jdom2.Element schema, StringBuilder sb) throws org.jdom2.JDOMException, IOException, ISOException
      Packs this message into the given StringBuilder using the provided schema.
      Parameters:
      schema - the schema element
      sb - the target StringBuilder
      Throws:
      ISOException - on pack error
      IOException - on I/O error
      org.jdom2.JDOMException - on schema error

    • unpack

      protected void unpack(InputStreamReader r, org.jdom2.Element schema) throws IOException, org.jdom2.JDOMException
      Unpacks a message from the reader using the provided schema.
      Parameters:
      r - the reader
      schema - the schema element
      Throws:
      IOException - on I/O error
      org.jdom2.JDOMException - on schema error

    • read

      protected String read(InputStreamReader r, int len, String type, String separator) throws IOException
      Reads a field value from the stream.
      Parameters:
      r - the reader
      len - maximum field length
      type - field type
      separator - field separator
      Returns:
      the field value
      Throws:
      IOException - on I/O error

    • readField

      protected String readField(InputStreamReader r, String fieldName, int len, String type, String separator) throws IOException
      Reads a named field value from the stream.
      Parameters:
      r - the reader
      fieldName - the field name
      len - maximum field length
      type - field type
      separator - field separator
      Returns:
      the field value
      Throws:
      IOException - on I/O error

    • set

      public void set(String name, String value)
      Sets a field value; removes the field if value is null.
      Parameters:
      name - the field name
      value - the field value, or null to remove

    • setHeader

      public void setHeader(byte[] h)
      Sets the binary header bytes for this message.
      Parameters:
      h - the header bytes to set

    • getHeader

      public byte[] getHeader()
      Returns the binary header bytes.
      Returns:
      the header bytes, or null if not set

    • getHexHeader

      public String getHexHeader()
      Returns the header as a hex string, or empty string if no header is set.
      Returns:
      the header as a hex string

    • get

      public String get(String fieldName)
      Returns the value of the named field.
      Parameters:
      fieldName - the field name to retrieve
      Returns:
      the field value, or null if not set

    • get

      public String get(String fieldName, String def)
      Returns the value of the named field, or a default if not set.
      Parameters:
      fieldName - the field name
      def - the default value if not set
      Returns:
      the field value, or the default

    • copy

      public void copy(String fieldName, FSDMsg msg)
      Copies a field value from another FSDMsg into this message.
      Parameters:
      fieldName - the field to copy
      msg - the source FSDMsg

    • copy

      public void copy(String fieldName, FSDMsg msg, String def)
      Copies a field value from another FSDMsg into this message, using a default if not present.
      Parameters:
      fieldName - the field to copy
      msg - the source FSDMsg
      def - default value if the field is not present in msg

    • getHexBytes

      public byte[] getHexBytes(String name)
      Returns the value of the named field decoded from hex.
      Parameters:
      name - the field name containing a hex-encoded value
      Returns:
      decoded bytes, or null if field not set

    • getInt

      public int getInt(String name)
      Returns the integer value of the named field, or 0 if absent or non-numeric.
      Parameters:
      name - the field name
      Returns:
      integer value of the field

    • getInt

      public int getInt(String name, int def)
      Returns the integer value of the named field, or a default if absent or non-numeric.
      Parameters:
      name - the field name
      def - the default value to return if the field is absent or non-numeric
      Returns:
      integer value of the field or the default

    • toXML

      public org.jdom2.Element toXML()
      Serializes this FSDMsg to a JDOM XML Element.
      Returns:
      XML Element representing this message

    • getSchema

      protected org.jdom2.Element getSchema() throws org.jdom2.JDOMException, IOException
      Returns the root schema Element for the base schema.
      Returns:
      the root schema Element
      Throws:
      org.jdom2.JDOMException - on XML parsing error
      IOException - on I/O error

    • getSchema

      protected org.jdom2.Element getSchema(String message) throws org.jdom2.JDOMException, IOException
      Returns the root schema Element for the named message schema.
      Parameters:
      message - the schema message name
      Returns:
      the root schema Element
      Throws:
      org.jdom2.JDOMException - on XML parsing error
      IOException - on I/O error

    • getSchema

      protected org.jdom2.Element getSchema(String prefix, String suffix, String defSuffix) throws org.jdom2.JDOMException, IOException
      Returns the root schema Element located at the given path.
      Parameters:
      prefix - the schema path prefix
      suffix - the schema path suffix
      defSuffix - the default suffix to use if the path is not found
      Returns:
      the root schema Element
      Throws:
      org.jdom2.JDOMException - on XML parsing error
      IOException - on I/O error

    • loadSchema

      protected org.jdom2.Element loadSchema(String uri, boolean throwex) throws org.jdom2.JDOMException, IOException
      Loads and parses the schema from the given URI.
      Parameters:
      uri - the URI of the schema resource to load
      throwex - if true, throw an exception if the resource is not found
      Returns:
      the parsed root Element, or null if not found and throwex is false
      Throws:
      org.jdom2.JDOMException - on XML parsing error
      IOException - on I/O error

    • schemaResouceInputStream

      protected InputStream schemaResouceInputStream(String resource) throws org.jdom2.JDOMException, IOException
      Returns an InputStream for the given classpath resource.
      Parameters:
      resource - the classpath resource path
      Returns:
      the InputStream, or null if the resource is not found
      Throws:
      IOException - on I/O error
      org.jdom2.JDOMException - on XML error

    • getMap

      public Map getMap()
      Returns the underlying fields map.
      Returns:
      the fields map

    • setMap

      public void setMap(Map fields)
      Sets the underlying fields map.
      Parameters:
      fields - the fields map to set

    • dump

      public void dump(PrintStream p, String indent)
      Description copied from interface: Loggeable
      Dumps a human-readable representation of this object to the print stream.
      Specified by:
      dump in interface Loggeable
      Parameters:
      p - the output stream
      indent - indentation prefix

    • hasField

      public boolean hasField(String fieldName)
      Returns true if this message has a value for the named field.
      Parameters:
      fieldName - the field name to check
      Returns:
      true if the field is present

    • clone

      public Object clone()
      Overrides:
      clone in class Object

    • merge

      public void merge(FSDMsg m)
      Copies all fields from the given message into this message.
      Parameters:
      m - the source message to merge from

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object