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

Interface EDIStreamWriter

All Superinterfaces:
AutoCloseable
public interface EDIStreamWriter extends AutoCloseable
The EDIStreamWriter interface specifies how to write EDI. Each method depends on the internal state of the writer and a client application must ensure that the methods are called in the proper sequence. For example, element data may not be written prior to starting an interchange and a segment.

  • Method Details

    • 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

    • close

      void close() throws EDIStreamException
      Close this writer and free any resources associated with the writer. This must not close the underlying output stream.
      Specified by:
      close in interface AutoCloseable
      Throws:
      EDIStreamException - if there are errors freeing associated resources

    • flush

      void flush() throws EDIStreamException
      Write any cached data to the underlying output mechanism.
      Throws:
      EDIStreamException - if there are errors flushing the cache

    • 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.8

    • setControlSchema

      void setControlSchema(Schema controlSchema)

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

      Calls to this method are only valid before the interchange is started.

      A built-in control schema may be obtained from SchemaFactory#getControlSchema to pass to this method.

      Parameters:
      controlSchema - the schema instance to use for validation of control structures
      Throws:
      IllegalStateException - when the writer is not in its initial state
      Since:
      1.1
      See Also:

    • setTransactionSchema

      void setTransactionSchema(Schema transactionSchema)

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

      This method may be called at any time. However, when non-null, the writer will make use of the transaction schema for output validation. It is the responsibility of the caller to set the transaction schema to null at the end of the business transaction.

      Parameters:
      transactionSchema - the schema instance to use for validation of business transaction structures
      Since:
      1.1

    • getLocation

      Location getLocation()
      Return the current location of the writer. 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 the next item is written to the output.
      Returns:
      current location of the writer
      Since:
      1.1

    • getStandard

      String getStandard()
      Get the EDI standard name. Calls to this method are only valid when the interchange type has been determined, after the full interchange header segment has been written.
      Returns:
      the name of the EDI standard
      Throws:
      IllegalStateException - when the standard has not yet been determined, prior to the start of an interchange header segment being fully written
      Since:
      1.7

    • getDelimiters

      Map<String,Character> getDelimiters()
      Retrieve a read-only map of delimiters in use for the stream being written.
      Returns:
      The value of the property
      Throws:
      IllegalStateException - when the standard has not yet been determined, prior to the start of an interchange header segment being fully written
      Since:
      1.8

    • startInterchange

      EDIStreamWriter startInterchange() throws EDIStreamException
      Initialize this writer to begin writing an interchange. This method does not write any output to the underlying stream.
      Returns:
      this EDI stream writer
      Throws:
      EDIStreamException - is not thrown and will be removed in the next major version of StAEDI.
      IllegalStateException - when the writer is in any state other than the initial state

    • endInterchange

      EDIStreamWriter endInterchange() throws EDIStreamException
      Completes an interchange and returns the writer to its initial state. Any data pending output will be flushed.
      Returns:
      this EDI stream writer
      Throws:
      EDIStreamException - if an error occurs
      IllegalStateException - when the writer is in a state writing a segment, element, composite

    • writeStartSegment

      EDIStreamWriter writeStartSegment(String name) throws EDIStreamException
      Begin a new segment with the given name and write the tag to the underlying output.
      Parameters:
      name - name of the segment (i.e. the segment tag)
      Returns:
      this EDI stream writer
      Throws:
      EDIStreamException - if an error occurs
      IllegalStateException - when the writer is not in a state to begin a segment

    • writeEndSegment

      EDIStreamWriter writeEndSegment() throws EDIStreamException
      Complete a segment by writing the segment terminator to the underlying output.
      Returns:
      this EDI stream writer
      Throws:
      EDIStreamException - if an error occurs
      IllegalStateException - when the writer is not in a state to end a segment

    • writeStartElement

      EDIStreamWriter writeStartElement() throws EDIStreamException
      Start a new element, composite or simple.
      Returns:
      this EDI stream writer
      Throws:
      EDIStreamException - if an error occurs
      IllegalStateException - when a segment has not been started with writeStartSegment(String)

    • writeStartElementBinary

      EDIStreamWriter writeStartElementBinary() throws EDIStreamException
      Start a new element for binary data.
      Returns:
      this EDI stream writer
      Throws:
      EDIStreamException - if an error occurs
      IllegalStateException - when the a segment has not been started with writeStartSegment(String)

    • endElement

      EDIStreamWriter endElement() throws EDIStreamException
      Complete an element. A delimiter will not be written immediately.
      Returns:
      this EDI stream writer
      Throws:
      EDIStreamException - if an error occurs
      IllegalStateException - when the writer is not in the state of writing an element

    • writeRepeatElement

      EDIStreamWriter writeRepeatElement() throws EDIStreamException
      Write an element repeat delimiter/separator to the output stream. Following this method being called, the writer will be in a state to accept element data using writeElementData(CharSequence) or writeElementData(char[], int, int).
      Returns:
      this EDI stream writer
      Throws:
      EDIStreamException - if an error occurs
      IllegalStateException - when the writer is not in a state for writing element data. A segment must have already been started.

    • startComponent

      EDIStreamWriter startComponent() throws EDIStreamException
      Start a component of a composite element.
      Returns:
      this EDI stream writer
      Throws:
      EDIStreamException - if an error occurs
      IllegalStateException - when an element has not been started with writeStartElement()

    • endComponent

      EDIStreamWriter endComponent() throws EDIStreamException
      Complete a component of a composite element.
      Returns:
      this EDI stream writer
      Throws:
      EDIStreamException - if an error occurs
      IllegalStateException - when the writer is not in the state of writing an component element

    • writeEmptyElement

      EDIStreamWriter writeEmptyElement() throws EDIStreamException
      Write an empty simple element.

      Shorthand for calling writeStartElement() immediately followed by endElement().

      Returns:
      this EDI stream writer
      Throws:
      EDIStreamException - if an error occurs
      IllegalStateException - when the writer is not in a state for writing simple element data

    • writeElement

      EDIStreamWriter writeElement(CharSequence text) throws EDIStreamException
      Begin an element, write text data from the given CharSequence to the output, and end the element.

      Shorthand for calling writeStartElement(), writeElementData(CharSequence), and endElement(), in that order.

      Parameters:
      text - CharSequence containing element's full text data
      Returns:
      this EDI stream writer
      Throws:
      EDIStreamException - if an error occurs
      IllegalStateException - when the writer is not in a state for writing simple element data

    • writeElement

      EDIStreamWriter writeElement(char[] text, int start, int end) throws EDIStreamException
      Begin an element, write text data from the given char array to the output, and end the element. Data will be read from the offset given by start (inclusive) to the offset given by end (exclusive).

      Shorthand for calling writeStartElement(), writeElementData(char[], int, int), and endElement(), in that order.

      Parameters:
      text - char array containing element's full text data
      start - the start index, inclusive
      end - the end index, exclusive
      Returns:
      this EDI stream writer
      Throws:
      EDIStreamException - if an error occurs
      IllegalStateException - when the writer is not in a state for writing simple element data

    • writeEmptyComponent

      EDIStreamWriter writeEmptyComponent() throws EDIStreamException
      Write an empty component

      Shorthand for calling startComponent() immediately followed by endComponent().

      Returns:
      this EDI stream writer
      Throws:
      EDIStreamException - if an error occurs
      IllegalStateException - when the writer is not in a state for writing component element data

    • writeComponent

      EDIStreamWriter writeComponent(CharSequence text) throws EDIStreamException
      Begin a component element, write text data from the given CharSequence to the output, and end the element.

      Shorthand for calling startComponent(), writeElementData(CharSequence), and endComponent(), in that order.

      Parameters:
      text - CharSequence containing component's full text data
      Returns:
      this EDI stream writer
      Throws:
      EDIStreamException - if an error occurs
      IllegalStateException - when the writer is not in a state for writing component element data

    • writeComponent

      EDIStreamWriter writeComponent(char[] text, int start, int end) throws EDIStreamException
      Begin a component element, write text data from the given char array to the output, and end the element. Data will be read from the offset given by start (inclusive) to the offset given by end (exclusive).

      Shorthand for calling startComponent(), writeElementData(char[], int, int), and endComponent(), in that order.

      Parameters:
      text - char array containing component's full text data
      start - the start index, inclusive
      end - the end index, exclusive
      Returns:
      this EDI stream writer
      Throws:
      EDIStreamException - if an error occurs
      IllegalStateException - when the writer is not in a state for writing component element data

    • writeElementData

      EDIStreamWriter writeElementData(CharSequence text) throws EDIStreamException
      Write text data from the given CharSequence to the output.
      Parameters:
      text - CharSequence containing element text data
      Returns:
      this EDI stream writer
      Throws:
      EDIStreamException - if an error occurs
      IllegalStateException - when the writer is not in a state for writing element data. See writeStartElement()

    • writeElementData

      EDIStreamWriter writeElementData(char[] text, int start, int end) throws EDIStreamException
      Write text data from the given char array to the output. Data will be read from the offset given by start (inclusive) to the offset given by end (exclusive).
      Parameters:
      text - char array containing element text data
      start - the start index, inclusive
      end - the end index, exclusive
      Returns:
      this EDI stream writer
      Throws:
      EDIStreamException - if an error occurs
      IllegalStateException - when the writer is not in a state for writing element data. See writeStartElement()

    • writeBinaryData

      EDIStreamWriter writeBinaryData(InputStream stream) throws EDIStreamException
      Write binary data from the given InputStream to the output. The stream will be read fully, until the byte returned by InputStream.read() is -1. Any data pending output will first be flushed.
      Parameters:
      stream - InputStream containing binary data to be consumed by the reader and written to the underlying output
      Returns:
      this EDI stream writer
      Throws:
      EDIStreamException - if an error occurs
      IllegalStateException - when the writer is not in a state for writing binary element data. See writeStartElementBinary()

    • writeBinaryData

      EDIStreamWriter writeBinaryData(byte[] binary, int start, int end) throws EDIStreamException
      Write binary data from the given byte array to the output. Data will be read from the offset given by start (inclusive) to the offset given by end (exclusive). Any data pending output will first be flushed.
      Parameters:
      binary - byte array containing binary data
      start - the start index, inclusive
      end - the end index, exclusive
      Returns:
      this EDI stream writer
      Throws:
      EDIStreamException - if an error occurs
      IllegalStateException - when the writer is not in a state for writing binary element data. See writeStartElementBinary()

    • writeBinaryData

      EDIStreamWriter writeBinaryData(ByteBuffer buffer) throws EDIStreamException
      Write binary data from the given buffer to the output. Any data pending output will first be flushed.
      Parameters:
      buffer - data buffer containing binary data
      Returns:
      this EDI stream writer
      Throws:
      EDIStreamException - if an error occurs
      IllegalStateException - when the writer is not in a state for writing binary element data. See writeStartElementBinary()