Package com.solab.iso8583

Class IsoMessage

  • public class IsoMessage
extends java.lang.Object
    Represents an ISO8583 message. This is the core class of the framework. Contains the bitmap which is modified as fields are added/removed. This class makes no assumptions as to what types belong in each field, nor what fields should each different message type have; that is left for the developer, since the different ISO8583 implementations can vary greatly.

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
        IsoMessage()
      Creates a new empty message with no values set.
      protected IsoMessage​(byte[] binaryHeader)
      Creates a new message with the specified binary ISO header.
      protected IsoMessage​(java.lang.String header)
      Creates a new message with the specified ISO header.

    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      <T> IsoValue<T> apply​(int i)
      Returns the IsoValue in the specified field, just like getField(int).
      void copyFieldsFrom​(IsoMessage src, int... idx)
      Copies the specified fields from the other message into the recipient.
      protected java.util.BitSet createBitmapBitSet()
      Creates a BitSet for the bitmap.
      java.lang.String debugString()
      Returns a string representation of the message, as if it were encoded in ASCII with no binary bitmap.
      <T> IsoValue<T> getAt​(int i)
      Returns the IsoValue in the specified field, just like getField(int).
      byte[] getBinaryIsoHeader()
      Returns the binary ISO header that this message was created with.
      java.lang.String getCharacterEncoding()
      Returns the character encoding for Strings inside the message.
      <T> IsoValue<T> getField​(int field)
      Returns the IsoValue for the specified field.
      boolean getForceSecondaryBitmap()
      Returns true if the secondary bitmap is always included in the message, even if it's not needed.
      java.lang.String getIsoHeader()
      Returns the ISO header that this message was created with.
      <T> T getObjectValue​(int field)
      Returns the stored value in the field, without converting or formatting it.
      int getType()
      Returns the ISO message type.
      boolean hasAnyField​(int... idx)
      Returns true is the message contains at least one of the specified fields.
      boolean hasEveryField​(int... idx)
      Returns true is the message contains all the specified fields.
      boolean hasField​(int idx)
      Returns true is the message has a value in the specified field.
      boolean isBinary()
      Deprecated.
      Use the new flags isBinaryHeader and isBinaryFields instead.
      boolean isBinaryBitmap()
      Returns true if the message's bitmap is encoded in binary format, when the message is encoded as text.
      boolean isBinaryFields()
      field data is binary encoded
      boolean isBinaryHeader()
      header information is binary encoded
      boolean isEncodeVariableLengthFieldsInHex()  
      <T> void putAt​(int i, IsoValue<T> v)
      Sets the specified value in the specified field, just like setField(int, IsoValue).
      void removeFields​(int... idx)
      Remove the specified fields from the message.
      void setBinary​(boolean flag)
      Indicates whether the message should be binary.
      void setBinaryBitmap​(boolean flag)
      Tells the message to encode its bitmap in binary format, even if the message itself is encoded as text.
      void setBinaryFields​(boolean flag)
      field data is binary encoded
      void setBinaryHeader​(boolean flag)
      header information is binary encoded
      void setBinaryIsoHeader​(byte[] binaryHeader)
      Sets the string to be sent as ISO header, that is, after the length header but before the message type.
      void setCharacterEncoding​(java.lang.String value)
      Sets the encoding to use.
      void setEncodeVariableLengthFieldsInHex​(boolean flag)
      Specified whether the variable-length fields should encode their length headers using hexadecimal values.
      void setEtx​(int value)
      Sets the ETX character, which is sent at the end of the message as a terminator.
      IsoMessage setField​(int index, IsoValue<?> field)
      Stored the field in the specified index.
      IsoMessage setFields​(java.util.Map<java.lang.Integer,​IsoValue<?>> values)
      Convenience method for setting several fields in one call.
      void setForceSecondaryBitmap​(boolean flag)
      If set, this flag will cause the secondary bitmap to be written even if it's not needed.
      void setForceStringEncoding​(boolean flag)
      Specified whether the variable-length fields should encode their length headers using string conversion with the proper character encoding.
      void setIsoHeader​(java.lang.String value)
      Sets the string to be sent as ISO header, that is, after the length header but before the message type.
      void setType​(int value)
      Sets the ISO message type.
      IsoMessage setValue​(int index, java.lang.Object value, IsoType t, int length)
      Sets the specified value in the specified field, creating an IsoValue internally.
      <T> IsoMessage setValue​(int index, T value, CustomFieldEncoder<T> encoder, IsoType t, int length)
      Sets the specified value in the specified field, creating an IsoValue internally.
      <T> void update​(int i, IsoValue<T> v)
      Sets the specified value in the specified field, just like setField(int, IsoValue).
      <T> IsoMessage updateValue​(int index, T value)
      A convenience method to set new values in fields that already contain values.
      void write​(java.io.OutputStream outs, int lengthBytes)
      Writes a message to a stream, after writing the specified number of bytes indicating the message's length.
      byte[] writeData()
      Writes the message to a memory stream and returns a byte array with the result.
      java.nio.ByteBuffer writeToBuffer​(int lengthBytes)
      Creates and returns a ByteBuffer with the data of the message, including the length header.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • IsoMessage

        public IsoMessage()
        Creates a new empty message with no values set.

      • IsoMessage

        protected IsoMessage​(java.lang.String header)
        Creates a new message with the specified ISO header. This will be prepended to the message.

      • IsoMessage

        protected IsoMessage​(byte[] binaryHeader)
        Creates a new message with the specified binary ISO header. This will be prepended to the message.

    • Method Detail

      • setBinaryBitmap

        public void setBinaryBitmap​(boolean flag)
        Tells the message to encode its bitmap in binary format, even if the message itself is encoded as text. This has no effect if the binary flag is set, which means binary messages will always encode their bitmap in binary format.

      • isBinaryBitmap

        public boolean isBinaryBitmap()
        Returns true if the message's bitmap is encoded in binary format, when the message is encoded as text. Default is false.

      • setForceSecondaryBitmap

        public void setForceSecondaryBitmap​(boolean flag)
        If set, this flag will cause the secondary bitmap to be written even if it's not needed.

      • getForceSecondaryBitmap

        public boolean getForceSecondaryBitmap()
        Returns true if the secondary bitmap is always included in the message, even if it's not needed. Default is false.

      • setCharacterEncoding

        public void setCharacterEncoding​(java.lang.String value)
        Sets the encoding to use.

      • getCharacterEncoding

        public java.lang.String getCharacterEncoding()
        Returns the character encoding for Strings inside the message. Default is taken from the file.encoding system property.

      • setForceStringEncoding

        public void setForceStringEncoding​(boolean flag)
        Specified whether the variable-length fields should encode their length headers using string conversion with the proper character encoding. Default is false, which is the old behavior (encoding as ASCII). This is only useful for text format.

      • setEncodeVariableLengthFieldsInHex

        public void setEncodeVariableLengthFieldsInHex​(boolean flag)
        Specified whether the variable-length fields should encode their length headers using hexadecimal values. This is only useful for binary format.

      • isEncodeVariableLengthFieldsInHex

        public boolean isEncodeVariableLengthFieldsInHex()

      • setIsoHeader

        public void setIsoHeader​(java.lang.String value)
        Sets the string to be sent as ISO header, that is, after the length header but before the message type. This is useful in case an application needs some custom data in the ISO header of each message (very rare).

      • getIsoHeader

        public java.lang.String getIsoHeader()
        Returns the ISO header that this message was created with.

      • setBinaryIsoHeader

        public void setBinaryIsoHeader​(byte[] binaryHeader)
        Sets the string to be sent as ISO header, that is, after the length header but before the message type. This is useful in case an application needs some custom data in the ISO header of each message (very rare).

      • getBinaryIsoHeader

        public byte[] getBinaryIsoHeader()
        Returns the binary ISO header that this message was created with.

      • setType

        public void setType​(int value)
        Sets the ISO message type. Common values are 0x200, 0x210, 0x400, 0x410, 0x800, 0x810.

      • getType

        public int getType()
        Returns the ISO message type.

      • setBinary

        public void setBinary​(boolean flag)
        Indicates whether the message should be binary. Default is false. To encode the message as text but the bitmap in binary format, you can set the binaryBitmap flag.

      • isBinary

        @Deprecated
public boolean isBinary()
        Deprecated.
        Use the new flags isBinaryHeader and isBinaryFields instead.
        Returns true if the message is binary coded (both header and fields); default is false.

      • setBinaryHeader

        public void setBinaryHeader​(boolean flag)
        header information is binary encoded

      • isBinaryHeader

        public boolean isBinaryHeader()
        header information is binary encoded

      • setBinaryFields

        public void setBinaryFields​(boolean flag)
        field data is binary encoded

      • isBinaryFields

        public boolean isBinaryFields()
        field data is binary encoded

      • setEtx

        public void setEtx​(int value)
        Sets the ETX character, which is sent at the end of the message as a terminator. Default is -1, which means no terminator is sent.

      • getObjectValue

        public <T> T getObjectValue​(int field)
        Returns the stored value in the field, without converting or formatting it.
        Parameters:
        field - The field number. 1 is the secondary bitmap and is not returned as such; real fields go from 2 to 128.

      • getField

        public <T> IsoValue<T> getField​(int field)
        Returns the IsoValue for the specified field. First real field is 2.

      • setField

        public IsoMessage setField​(int index,
                           IsoValue<?> field)
        Stored the field in the specified index. The first field is the secondary bitmap and has index 1, so the first valid value for index must be 2.
        Returns:
        The receiver (useful for setting several fields in sequence).

      • setFields

        public IsoMessage setFields​(java.util.Map<java.lang.Integer,​IsoValue<?>> values)
        Convenience method for setting several fields in one call.

      • setValue

        public IsoMessage setValue​(int index,
                           java.lang.Object value,
                           IsoType t,
                           int length)
        Sets the specified value in the specified field, creating an IsoValue internally.
        Parameters:
        index - The field number (2 to 128)
        value - The value to be stored.
        t - The ISO type.
        length - The length of the field, used for ALPHA and NUMERIC values only, ignored with any other type.
        Returns:
        The receiver (useful for setting several values in sequence).

      • setValue

        public <T> IsoMessage setValue​(int index,
                               T value,
                               CustomFieldEncoder<T> encoder,
                               IsoType t,
                               int length)
        Sets the specified value in the specified field, creating an IsoValue internally.
        Parameters:
        index - The field number (2 to 128)
        value - The value to be stored.
        encoder - An optional CustomFieldEncoder for the value.
        t - The ISO type.
        length - The length of the field, used for ALPHA and NUMERIC values only, ignored with any other type.
        Returns:
        The receiver (useful for setting several values in sequence).

      • updateValue

        public <T> IsoMessage updateValue​(int index,
                                  T value)
        A convenience method to set new values in fields that already contain values. The field's type, length and custom encoder are taken from the current value. This method can only be used with fields that have been previously set, usually from a template in the MessageFactory.
        Parameters:
        index - The field's index
        value - The new value to be set in that field.
        Returns:
        The message itself.
        Throws:
        java.lang.IllegalArgumentException - if there is no current field at the specified index.

      • hasField

        public boolean hasField​(int idx)
        Returns true is the message has a value in the specified field.
        Parameters:
        idx - The field number.

      • write

        public void write​(java.io.OutputStream outs,
                  int lengthBytes)
           throws java.io.IOException
        Writes a message to a stream, after writing the specified number of bytes indicating the message's length. The message will first be written to an internal memory stream which will then be dumped into the specified stream. This method flushes the stream after the write. There are at most three write operations to the stream: one for the length header, one for the message, and the last one with for the ETX.
        Parameters:
        outs - The stream to write the message to.
        lengthBytes - The size of the message length header. Valid ranges are 0 to 4.
        Throws:
        java.lang.IllegalArgumentException - if the specified length header is more than 4 bytes.
        java.io.IOException - if there is a problem writing to the stream.

      • writeToBuffer

        public java.nio.ByteBuffer writeToBuffer​(int lengthBytes)
        Creates and returns a ByteBuffer with the data of the message, including the length header. The returned buffer is already flipped, so it is ready to be written to a Channel.

      • createBitmapBitSet

        protected java.util.BitSet createBitmapBitSet()
        Creates a BitSet for the bitmap.

      • writeData

        public byte[] writeData()
        Writes the message to a memory stream and returns a byte array with the result.

      • debugString

        public java.lang.String debugString()
        Returns a string representation of the message, as if it were encoded in ASCII with no binary bitmap.

      • getAt

        public <T> IsoValue<T> getAt​(int i)
        Returns the IsoValue in the specified field, just like getField(int).

      • apply

        public <T> IsoValue<T> apply​(int i)
        Returns the IsoValue in the specified field, just like getField(int).

      • copyFieldsFrom

        public void copyFieldsFrom​(IsoMessage src,
                           int... idx)
        Copies the specified fields from the other message into the recipient. If a specified field is not present in the source message it is simply ignored.

      • removeFields

        public void removeFields​(int... idx)
        Remove the specified fields from the message.

      • hasEveryField

        public boolean hasEveryField​(int... idx)
        Returns true is the message contains all the specified fields. A convenience for m.hasField(x) && m.hasField(y) && m.hasField(z) && ...

      • hasAnyField

        public boolean hasAnyField​(int... idx)
        Returns true is the message contains at least one of the specified fields. A convenience for m.hasField(x) || m.hasField(y) || m.hasField(z) || ...