Module io.xlate.staedi
Package io.xlate.edi.stream

Interface EDIStreamReader

All Superinterfaces:
java.lang.AutoCloseable, java.io.Closeable, EDIStreamConstants
public interface EDIStreamReader
extends java.io.Closeable, EDIStreamConstants

  • Nested Class Summary

    Nested classes/interfaces inherited from interface io.xlate.edi.stream.EDIStreamConstants

    EDIStreamConstants.Delimiters, EDIStreamConstants.Standards

  • Method Summary

    Modifier and Type Method Description
    void close()
    Frees any resources associated with this Reader.
    java.io.InputStream getBinaryData()
    Returns a ByteBuffer object containing the binary element data read in the previous data element.
    Schema getControlSchema()
    Returns the control schema currently set on the reader.
    java.util.Map<java.lang.String,​java.lang.Character> getDelimiters()
    Retrieve a read-only map of delimiters in use for the stream being read.
    EDIStreamValidationError getErrorType()
    Returns an integer code that indicates the type of error the cursor is pointing to.
    EDIStreamEvent getEventType()
    Returns an integer code that indicates the type of the event the cursor is pointing to.
    Location getLocation()
    Return the current location of the processor.
    java.lang.Object getProperty​(java.lang.String name)
    Get the value of a feature/property from the underlying implementation
    java.lang.String getReferenceCode()
    Return the reference code for the current element if a schema has been set and the current processing state is within an interchange.
    EDIReference getSchemaTypeReference()
    Returns an EDIReference for the schema type at the current point in the reader's input stream.
    java.lang.String getStandard()
    Get the EDI standard name.
    java.lang.String getText()
    Returns the current value of the parse event as a string.
    char[] getTextCharacters()
    Returns an array which contains the characters from this event.
    int getTextCharacters​(int sourceStart, char[] target, int targetStart, int length)
    Gets the the text associated with a ELEMENT_DATA, ELEMENT_ERROR, START_SEGMENT, or END_SEGMENT event.
    int getTextLength()
    Returns the length of the sequence of characters for this Text event within the text character array.
    int getTextStart()
    Returns the offset into the text character array where the first character (of this text event) is stored.
    Schema getTransactionSchema()
    Returns the schema currently set on the reader to be used for validation of the business transaction.
    java.lang.String[] getTransactionVersion()
    Get the transaction version declared on the transaction header segment or the functional group header segment (X12 only).
    java.lang.String getTransactionVersionString()
    The transaction version string elements as a single, period-delimited value.
    java.lang.String[] getVersion()
    Get the interchange version declared on the interchange begin segment.
    boolean hasNext()
    Returns true if there are more parsing events and false if there are no more events.
    EDIStreamEvent next()
    Get next parsing event
    EDIStreamEvent nextTag()
    Skips any ELEMENT_DATA, START_COMPOSITE, and END_COMPOSITE until a START_SEGMENT is reached.
    void setBinaryDataLength​(long length)
    Sets the number of bytes that should be read as binary data and not interpreted as EDI data.
    void setControlSchema​(Schema schema)
    Sets the schema to be used for validation of the control structure for this stream reader.
    void setTransactionSchema​(Schema schema)
    Sets the schema to be used for validation of the business transaction for this stream reader.

  • Method Details

    • getProperty

      java.lang.Object getProperty​(java.lang.String name)
      Get the value of a feature/property from the underlying implementation
      Parameters:
      name - - The name of the property, may not be null
      Returns:
      The value of the property
      Throws:
      java.lang.IllegalArgumentException - if name is null

    • getDelimiters

      java.util.Map<java.lang.String,​java.lang.Character> getDelimiters()
      Retrieve a read-only map of delimiters in use for the stream being read.
      Returns:
      The value of the property
      Throws:
      java.lang.IllegalStateException - if called outside of an interchange

    • next

      EDIStreamEvent next() throws EDIStreamException
      Get next parsing event
      Returns:
      the integer code corresponding to the current parse event
      Throws:
      java.util.NoSuchElementException - if this is called when hasNext() returns false
      EDIStreamException - if there is an error processing the underlying EDI source

    • nextTag

      EDIStreamEvent nextTag() throws EDIStreamException
      Skips any ELEMENT_DATA, START_COMPOSITE, and END_COMPOSITE until a START_SEGMENT is reached.
      Returns:
      the event type of the element read - START_SEGMENT
      Throws:
      java.util.NoSuchElementException - if this is called when hasNext() returns false or there are no additional START_SEGMENT events in the stream
      EDIStreamException - if the current event is not following START_INTERCHANGE and preceding END_INTERCHANGE

    • hasNext

      boolean hasNext() throws EDIStreamException
      Returns true if there are more parsing events and false if there are no more events. This method will return false if the current state of the EDIStreamReader is END_INTERCHANGE
      Returns:
      true if there are more events, false otherwise
      Throws:
      EDIStreamException - if there is a fatal error detecting the next state

    • close

      void close() throws java.io.IOException
      Frees any resources associated with this Reader. This method does not close the underlying input stream.
      Specified by:
      close in interface java.lang.AutoCloseable
      Specified by:
      close in interface java.io.Closeable
      Throws:
      java.io.IOException - if there are errors freeing associated resources

    • getEventType

      EDIStreamEvent getEventType()
      Returns an integer code that indicates the type of the event the cursor is pointing to.
      Returns:
      code that indicates the type of the event the cursor is pointing to

    • getStandard

      java.lang.String getStandard()
      Get the EDI standard name. Calls to this method are only valid when the interchange type has been determined, after START_INTERCHANGE.
      Returns:
      the name of the EDI standard
      Throws:
      java.lang.IllegalStateException - when the standard has not yet been determined, prior to the start of an interchange

    • getVersion

      java.lang.String[] getVersion()
      Get the interchange version declared on the interchange begin segment. Calls to this method are only valid when interchange type has been determined, after START_INTERCHANGE.
      Returns:
      the version
      Throws:
      java.lang.IllegalStateException - when the version has not yet been determined, prior to the start of an interchange

    • getTransactionVersion

      java.lang.String[] getTransactionVersion()
      Get the transaction version declared on the transaction header segment or the functional group header segment (X12 only). Calls to this method are only valid when interchange type has been determined, after START_INTERCHANGE, and the transaction version has been determined by reading the dialect-specific data elements containing the version value(s). The elements of the returned array are defined as:
      1. Agency code
      2. Version
      3. Release
      4. Industry code
      In practice, the values will be the following elements:

      For EDIFACT:

      1. Agency code: UNH02-4
      2. Version: UNH02-2
      3. Release: UNH02-3
      4. Industry code: UNH02-5

      For X12:

      1. Agency code: GS07
      2. Version/Release/Industry code: GS08 (or ST03, when used)
      Returns:
      the transaction version
      Throws:
      java.lang.IllegalStateException - when the version has not yet been determined, prior to the start of a transaction (or functional group when in use)
      Since:
      1.9

    • getTransactionVersionString

      java.lang.String getTransactionVersionString()
      The transaction version string elements as a single, period-delimited value. This value may be used to obtain version-specific schema information available from the EDIReference returned from getSchemaTypeReference().
      Returns:
      the transaction version as a single, period-delimited value
      Throws:
      java.lang.IllegalStateException - when the version has not yet been determined, prior to the start of a transaction (or functional group when in use)
      Since:
      1.9

    • getControlSchema

      Schema getControlSchema()
      Returns the control schema currently set on the reader. If none has been set, then null will be returned.
      Returns:
      the control schema current set on this reader, may be null
      Since:
      1.5

    • setControlSchema

      void setControlSchema​(Schema schema)

      Sets the schema to be used for validation of the control structure for this stream reader. This schema will be used to validate interchange, group, and transaction/message envelopes.

      Calls to this method are only valid when the current event type is START_INTERCHANGE.

      Parameters:
      schema - the schema instance to use for validation of control structures
      Throws:
      java.lang.IllegalStateException - when the current event type is not START_INTERCHANGE

    • getTransactionSchema

      Schema getTransactionSchema()
      Returns the schema currently set on the reader to be used for validation of the business transaction. If none has been set, then null will be returned.
      Returns:
      the transaction schema current set on this reader, may be null
      Since:
      1.5

    • setTransactionSchema

      void setTransactionSchema​(Schema schema)

      Sets the schema to be used for validation of the business transaction for this stream reader. This schema will be used to validate only the contents of a transaction/message, not including the begin/end control structures.

      Calls to this method are only valid after a START_TRANSACTION event and up to and including the END_SEGMENT event representing the beginning of the transaction.

      Parameters:
      schema - the schema instance to use for validation of business transaction structures
      Throws:
      java.lang.IllegalStateException - when the reader is not positioned on the start transaction segment

    • getReferenceCode

      java.lang.String getReferenceCode()
      Return the reference code for the current element if a schema has been set and the current processing state is within an interchange. Otherwise, an IllegalStateException will be thrown. If the reader encounters an unknown type, the reference code will be null.
      Returns:
      the reference code from the schema for the current EDIType
      Throws:
      java.lang.IllegalStateException - when the current event type is not within an interchange

    • getErrorType

      EDIStreamValidationError getErrorType()
      Returns an integer code that indicates the type of error the cursor is pointing to. Calls to this method are only valid when the current event type is SEGMENT_ERROR or ELEMENT_ERROR.
      Returns:
      code that indicates the type of the error the cursor is pointing to
      Throws:
      java.lang.IllegalStateException - when the current event type is not SEGMENT_ERROR or ELEMENT_ERROR

    • getText

      java.lang.String getText()
      Returns the current value of the parse event as a string. This returns the string value of an ELEMENT_DATA event, and the string value of a segment tag in a START_SEGMENT event. During an ELEMENT_ERROR event, this contains the invalid element (when available).
      Returns:
      the current text or null
      Throws:
      java.lang.IllegalStateException - if this state is not a valid text state

    • getTextCharacters

      char[] getTextCharacters()
      Returns an array which contains the characters from this event. This array should be treated as read-only and transient. I.e. the array will contain the text characters until the EDIStreamReader moves on to the next event. Attempts to hold onto the character array beyond that time or modify the contents of the array are breaches of the contract for this interface.
      Returns:
      the current text or an empty array
      Throws:
      java.lang.IllegalStateException - if this state is not a valid text state

    • getTextCharacters

      int getTextCharacters​(int sourceStart, char[] target, int targetStart, int length)
      Gets the the text associated with a ELEMENT_DATA, ELEMENT_ERROR, START_SEGMENT, or END_SEGMENT event. Text starting at "sourceStart" is copied into "target" starting at "targetStart". Up to "length" characters are copied. The number of characters actually copied is returned. The "sourceStart" argument must be greater or equal to 0 and less than or equal to the number of characters associated with the event. Usually, one requests text starting at a "sourceStart" of 0. If the number of characters actually copied is less than the "length", then there is no more text. Otherwise, subsequent calls need to be made until all text has been retrieved. For example: 
       int length = 1024;
 char[] myBuffer = new char[length];

 for (int sourceStart = 0;; sourceStart += length) {
     int nCopied = stream.getTextCharacters(sourceStart, myBuffer, 0, length);
     if (nCopied < length)
         break;
 }
      EDIStreamException may be thrown if there are any parsing errors in the underlying source. The "targetStart" argument must be greater than or equal to 0 and less than the length of "target", Length must be greater than 0 and "targetStart + length" must be less than or equal to length of "target".
      Parameters:
      sourceStart - - the index of the first character in the source array to copy
      target - - the destination array
      targetStart - - the start offset in the target array
      length - - the number of characters to copy
      Returns:
      the number of characters actually copied
      Throws:
      java.lang.IndexOutOfBoundsException - if targetStart < 0 or > than the length of target
      java.lang.IndexOutOfBoundsException - if length < 0 or targetStart + length > length of target
      java.lang.NullPointerException - if target is null

    • getTextStart

      int getTextStart()
      Returns the offset into the text character array where the first character (of this text event) is stored.
      Returns:
      offset into the text character array where the first character is stored
      Throws:
      java.lang.IllegalStateException - if this state is not a valid text state

    • getTextLength

      int getTextLength()
      Returns the length of the sequence of characters for this Text event within the text character array.
      Returns:
      length of the sequence of characters for this Text event
      Throws:
      java.lang.IllegalStateException - if this state is not a valid text state

    • getLocation

      Location getLocation()
      Return the current location of the processor. If the Location is unknown the processor should return an implementation of Location that returns -1 for the location values. The location information is only valid until next() is called.
      Returns:
      current location of the processor

    • setBinaryDataLength

      void setBinaryDataLength​(long length) throws EDIStreamException
      Sets the number of bytes that should be read as binary data and not interpreted as EDI data. This EDIStreamReader will return to normal EDI parsing after reading this number of bytes. The byte immediately following length bytes must be a delimiter valid in the scope of the current interchange or an EDIStreamException will occur. This method must only be called immediately preceding a binary data element. Attempts to call it while the reader is in any other state will result in an IllegalStateException.

      Note: Applications parsing transactions which contain binary data elements must call this method to avoid the binary data being parsed as EDI content. The length of the binary data is typically found in a companion data element preceding the binary element in the stream.

      Parameters:
      length - - the number of bytes to read as binary data and not as EDI-formatted
      Throws:
      java.lang.IllegalStateException - if this state is not a state which may precede a data element.
      EDIStreamException - if there are IO errors allocating resources for binary data processing

    • getBinaryData

      java.io.InputStream getBinaryData()
      Returns a ByteBuffer object containing the binary element data read in the previous data element. The limit of the buffer will be set to the length of the data.
      Returns:
      buffer containing binary data
      Throws:
      java.lang.IllegalStateException - if the stream reader did not complete the scanning of a binary data element immediately preceding this call.

    • getSchemaTypeReference

      EDIReference getSchemaTypeReference()
      Returns an EDIReference for the schema type at the current point in the reader's input stream. Information such as minimum and maximum occurrences, as well as the EDIType may be obtained from the reference. If the reader is utilizing an implementation schema and the current schema type is an implemented type, the returned reference will be an EDITypeImplementation.
      Returns:
      an EDIReference for the schema type at the current point in the reader's input stream
      Since:
      1.9