com.verisign.epp.util

## Class EPPXMLStream

- java.lang.Object
- - com.verisign.epp.util.EPPXMLStream

-     public class EPPXMLStream
      extends java.lang.Object

  `EPPXMLStream` is a utility class for reading and writing EPP messages to/from streams. DOM Document are read and written to the streams. An XML parser is required when reading from the stream. There is one constructor that will create an XML parser per call to `read(InputStream)` and one that will use a parser pool. Use of a parser pool is recommended.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DEFAULT_MAX_PACKET_SIZE` Default Maximum packet size of bytes accepted to ensure that the client is not overrun with an invalid packet or a packet that exceeds the maximum size.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `EPPXMLStream()` Default constructor for `EPPXMLStream`.
    `EPPXMLStream(java.lang.String aParserPoolName)` Construct `EPPXMLStream` to use a parser pool and a default transformer pool.
    `EPPXMLStream(java.lang.String aParserPoolName, java.lang.String aTransformerPoolName)` Construct `EPPXMLStream` to use a parser pool and a transformer pool.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `org.w3c.dom.Document` | `decodePacket(byte[] aPacket)` Decodes the passed in packet `byte[]` into a DOM `Document`.
    `org.w3c.dom.Document` | `read(java.io.InputStream aStream)` Reads an EPP packet from the `aStream` parameter, parses/validates it, and returns the associated DOM Document.
    `byte[]` | `readPacket(java.io.InputStream aStream)` Reads an EPP packet from the stream based on a search for the End Of Message (EOM) string (</epp>).
    `void` | `write(org.w3c.dom.Document aDoc, java.io.OutputStream aOutput, EPPMessage aMessage)` Writes a DOM Document to the output stream.
    `void` | `writePacket(byte[] aPacket, java.io.OutputStream aOutput)` Writes a packet to the output stream with the inclusion of the EPP four byte header.
    `void` | `writePacket(byte[] aPacket, java.io.OutputStream aOutput, EPPMessage aMessage)` Writes a packet to the output stream with the inclusion of the EPP four byte header.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### DEFAULT_MAX_PACKET_SIZE

          public static final int DEFAULT_MAX_PACKET_SIZE

      Default Maximum packet size of bytes accepted to ensure that the client is not overrun with an invalid packet or a packet that exceeds the maximum size. This setting could be made configurable in the future.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### EPPXMLStream

          public EPPXMLStream()

      Default constructor for `EPPXMLStream`. When using this constructor, a parser instance will be created on each call to `read(InputStream)` and a transformer instance will be created on each call to `write(Document,OutputStream)`. .

    - #### EPPXMLStream

          public EPPXMLStream(java.lang.String aParserPoolName)

      Construct `EPPXMLStream` to use a parser pool and a default transformer pool. The `aParserPoolName` parameter has to be a pool of `EPPParserPool` subclasses. When using this constructor, a parser instance will be checked out and checkin as needed on each call to `read(InputStream)`. The `Transformer` pool used is defined by the `EPPTransformer.POOL` constant.
      Parameters:
        `aParserPoolName` - Parser pool name to use

    - #### EPPXMLStream

          public EPPXMLStream(java.lang.String aParserPoolName,
                              java.lang.String aTransformerPoolName)

      Construct `EPPXMLStream` to use a parser pool and a transformer pool. The `aParserPoolName` parameter has to be a pool of `EPPParserPool` subclasses. When using this constructor, a parser instance will be checked out and checkin as needed on each call to `read(InputStream)`. The `Transformer` pool used is defined by the `EPPTransformer.POOL` constant. The `aTransformerPoolName` parameters is the name of pool containing `Transformer` instances.
      Parameters:
        `aParserPoolName` - Parser pool name to use
        `aTransformerPoolName` - Transformer pool name to use

  - ### Method Detail

    - #### readPacket

          public byte[] readPacket(java.io.InputStream aStream)
                            throws EPPException,
                                   java.io.InterruptedIOException,
                                   java.io.IOException

      Reads an EPP packet from the stream based on a search for the End Of Message (EOM) string (</epp>).
      Parameters:
        `aStream` - Stream to read packet from
      Returns:
        EPP packet `String`
      Throws:
        `EPPException` - Error reading packet from stream. The stream should be closed.
        `java.io.InterruptedIOException` - Time out reading for packet
        `java.io.IOException` - Exception from the input stream

    - #### read

          public org.w3c.dom.Document read(java.io.InputStream aStream)
                                    throws EPPAssemblerException,
                                           EPPException,
                                           java.io.IOException

      Reads an EPP packet from the `aStream` parameter, parses/validates it, and returns the associated DOM Document. The XML parser is either created per call, or is retrieved from a parser pool when `EPPXMLStream(GenericPoolManager)` is used. Use of a parser pool is recommended.
      Parameters:
        `aStream` - Input stream to read for an EPP packet.
      Returns:
        Parsed DOM Document of packet
      Throws:
        `EPPException` - Error with received packet or end of stream. It is recommended that the stream be closed.
        `EPPAssemblerException` - Error parsing packet
        `java.io.IOException` - Error reading packet from stream

    - #### decodePacket

          public org.w3c.dom.Document decodePacket(byte[] aPacket)
                                            throws EPPException,
                                                   java.io.IOException

      Decodes the passed in packet `byte[]` into a DOM `Document`.
      Parameters:
        `aPacket` - Input packet to decode to DOM `Document`.
      Returns:
        Decoded DOM `Document`
      Throws:
        `EPPException` - Error decoding the packet.
        `java.io.IOException` - Basic IO error decoding the packet.

    - #### writePacket

          public void writePacket(byte[] aPacket,
                                  java.io.OutputStream aOutput,
                                  EPPMessage aMessage)
                           throws java.io.IOException

      Writes a packet to the output stream with the inclusion of the EPP four byte header.
      Parameters:
        `aPacket` - Packet to write to the output stream
        `aOutput` - Output stream to write the packet to
        `aMessage` - Message object associated with the packet that can be used for filtering the information written to the packet log. Passing `null` may not filter or may cause performance issues in filtering the log information.
      Throws:
        `java.io.IOException` - Error writing the packet to the output stream

    - #### writePacket

          public void writePacket(byte[] aPacket,
                                  java.io.OutputStream aOutput)
                           throws java.io.IOException

      Writes a packet to the output stream with the inclusion of the EPP four byte header.
      Parameters:
        `aPacket` - Packet to write to the output stream
        `aOutput` - Output stream to write the packet to
      Throws:
        `java.io.IOException` - Error writing the packet to the output stream

    - #### write

          public void write(org.w3c.dom.Document aDoc,
                            java.io.OutputStream aOutput,
                            EPPMessage aMessage)
                     throws EPPException

      Writes a DOM Document to the output stream. The DOM Document will be serialized to XML and written to the output stream.
      Parameters:
        `aDoc` - DOM Document to write to stream
        `aOutput` - Output stream to write to
        `aMessage` - `EPPMessage` associated with `aDoc` that is used for packet logging logic. Set to `null` if unavailable.
      Throws:
        `EPPException` - Error writing to stream. It is recommended that the stream be closed.