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

Interface EDIStreamReader

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void close()
      Frees any resources associated with this Reader.
      InputStream getBinaryData()
      Returns a ByteBuffer object containing the binary element data read in the previous data element.
      Map<String,​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.
      Object getProperty​(String name)
      Get the value of a feature/property from the underlying implementation
      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.
      String getStandard()
      Get the EDI standard name.
      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.
      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 Detail

      • getProperty

        Object getProperty​(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:
        IllegalArgumentException - if name is null

      • getDelimiters

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

      • 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:
        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 IOException
        Frees any resources associated with this Reader. This method does not close the underlying input stream.
        Specified by:
        close in interface AutoCloseable
        Specified by:
        close in interface Closeable
        Throws:
        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

        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:
        IllegalStateException - when the standard has not yet been determined, prior to the start of an interchange

      • getVersion

        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:
        IllegalStateException - when the version has not yet been determined, prior to the start of an interchange

      • 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:
        IllegalStateException - when the current event type is not START_INTERCHANGE

      • 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 before the end of the segment representing the beginning of the transaction.

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

      • getReferenceCode

        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:
        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:
        IllegalStateException - when the current event type is not SEGMENT_ERROR or ELEMENT_ERROR

      • getText

        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.
        Returns:
        the current text or null
        Throws:
        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:
        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:
        IndexOutOfBoundsException - if targetStart < 0 or > than the length of target
        IndexOutOfBoundsException - if length < 0 or targetStart + length > length of target
        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:
        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:
        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:
        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

        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:
        IllegalStateException - if the stream reader did not complete the scanning of a binary data element immediately preceding this call.