Module java.desktop
Package java.beans

## Class XMLDecoder

- java.lang.Object
- - java.beans.XMLDecoder

- All Implemented Interfaces:
    `AutoCloseable`

      public class XMLDecoder
      extends Object
      implements AutoCloseable

  The `XMLDecoder` class is used to read XML documents created using the `XMLEncoder` and is used just like the `ObjectInputStream`. For example, one can use the following fragment to read the first object defined in an XML document written by the `XMLEncoder` class:

             XMLDecoder d = new XMLDecoder(
                                new BufferedInputStream(
                                    new FileInputStream("Test.xml")));
             Object result = d.readObject();
             d.close();

  For more information you might also want to check out Long Term Persistence of JavaBeans Components: XML Schema, an article in The Swing Connection.

  Since:
    1.4
  See Also:
    `XMLEncoder`, `ObjectInputStream`

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `XMLDecoder​(InputStream in)` | Creates a new input stream for reading archives created by the `XMLEncoder` class.
    `XMLDecoder​(InputStream in, Object owner)` | Creates a new input stream for reading archives created by the `XMLEncoder` class.
    `XMLDecoder​(InputStream in, Object owner, ExceptionListener exceptionListener)` | Creates a new input stream for reading archives created by the `XMLEncoder` class.
    `XMLDecoder​(InputStream in, Object owner, ExceptionListener exceptionListener, ClassLoader cl)` | Creates a new input stream for reading archives created by the `XMLEncoder` class.
    `XMLDecoder​(InputSource is)` | Creates a new decoder to parse XML archives created by the `XMLEncoder` class.

  - ### Method Summary

    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `close()` | This method closes the input stream associated with this stream.
    `static DefaultHandler` | `createHandler​(Object owner, ExceptionListener el, ClassLoader cl)` | Creates a new handler for SAX parser that can be used to parse embedded XML archives created by the `XMLEncoder` class.
    `ExceptionListener` | `getExceptionListener()` | Gets the exception handler for this stream.
    `Object` | `getOwner()` | Gets the owner of this decoder.
    `Object` | `readObject()` | Reads the next object from the underlying input stream.
    `void` | `setExceptionListener​(ExceptionListener exceptionListener)` | Sets the exception handler for this stream to `exceptionListener`.
    `void` | `setOwner​(Object owner)` | Sets the owner of this decoder to `owner`.

    - ### Methods declared in class java.lang.Object

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

- - ### Constructor Detail

    - #### XMLDecoder

          public XMLDecoder​(InputStream in)

      Creates a new input stream for reading archives created by the `XMLEncoder` class.
      Parameters:
        `in` - The underlying stream.
      See Also:
        `XMLEncoder(java.io.OutputStream)`

    - #### XMLDecoder

          public XMLDecoder​(InputStream in,
                            Object owner)

      Creates a new input stream for reading archives created by the `XMLEncoder` class.
      Parameters:
        `in` - The underlying stream.
        `owner` - The owner of this stream.

    - #### XMLDecoder

          public XMLDecoder​(InputStream in,
                            Object owner,
                            ExceptionListener exceptionListener)

      Creates a new input stream for reading archives created by the `XMLEncoder` class.
      Parameters:
        `in` - the underlying stream.
        `owner` - the owner of this stream.
        `exceptionListener` - the exception handler for the stream; if `null` the default exception listener will be used.

    - #### XMLDecoder

          public XMLDecoder​(InputStream in,
                            Object owner,
                            ExceptionListener exceptionListener,
                            ClassLoader cl)

      Creates a new input stream for reading archives created by the `XMLEncoder` class.
      Parameters:
        `in` - the underlying stream. `null` may be passed without error, though the resulting XMLDecoder will be useless
        `owner` - the owner of this stream. `null` is a legal value
        `exceptionListener` - the exception handler for the stream, or `null` to use the default
        `cl` - the class loader used for instantiating objects. `null` indicates that the default class loader should be used
      Since:
        1.5

    - #### XMLDecoder

          public XMLDecoder​(InputSource is)

      Creates a new decoder to parse XML archives created by the `XMLEncoder` class. If the input source `is` is `null`, no exception is thrown and no parsing is performed. This behavior is similar to behavior of other constructors that use `InputStream` as a parameter.
      Parameters:
        `is` - the input source to parse
      Since:
        1.7

  - ### Method Detail

    - #### close

          public void close()

      This method closes the input stream associated with this stream.
      Specified by:
        `close` in interface `AutoCloseable`

    - #### setExceptionListener

          public void setExceptionListener​(ExceptionListener exceptionListener)

      Sets the exception handler for this stream to `exceptionListener`. The exception handler is notified when this stream catches recoverable exceptions.
      Parameters:
        `exceptionListener` - The exception handler for this stream; if `null` the default exception listener will be used.
      See Also:
        `getExceptionListener()`

    - #### getExceptionListener

          public ExceptionListener getExceptionListener()

      Gets the exception handler for this stream.
      Returns:
        The exception handler for this stream. Will return the default exception listener if this has not explicitly been set.
      See Also:
        `setExceptionListener(java.beans.ExceptionListener)`

    - #### readObject

          public Object readObject()

      Reads the next object from the underlying input stream.
      Returns:
        the next object read
      Throws:
        `ArrayIndexOutOfBoundsException` - if the stream contains no objects (or no more objects)
      See Also:
        `XMLEncoder.writeObject(java.lang.Object)`

    - #### setOwner

          public void setOwner​(Object owner)

      Sets the owner of this decoder to `owner`.
      Parameters:
        `owner` - The owner of this decoder.
      See Also:
        `getOwner()`

    - #### getOwner

          public Object getOwner()

      Gets the owner of this decoder.
      Returns:
        The owner of this decoder.
      See Also:
        `setOwner(java.lang.Object)`

    - #### createHandler

          public static DefaultHandler createHandler​(Object owner,
                                                     ExceptionListener el,
                                                     ClassLoader cl)

      Creates a new handler for SAX parser that can be used to parse embedded XML archives created by the `XMLEncoder` class. The `owner` should be used if parsed XML document contains the method call within context of the <java> element. The `null` value may cause illegal parsing in such case. The same problem may occur, if the `owner` class does not contain expected method to call. See details here.
      Parameters:
        `owner` - the owner of the default handler that can be used as a value of <java> element
        `el` - the exception handler for the parser, or `null` to use the default exception handler
        `cl` - the class loader used for instantiating objects, or `null` to use the default class loader
      Returns:
        an instance of `DefaultHandler` for SAX parser
      Since:
        1.7