XMLDecoder


1   /*
2    * @(#)XMLDecoder.java  1.30 04/06/01
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   package java.beans;
8   
9   import com.sun.beans.ObjectHandler;
10  
11  import java.io.InputStream  ;
12  import java.io.IOException  ;
13  
14  import java.lang.ref.Reference  ;
15  import java.lang.ref.WeakReference  ;
16  
17  import org.xml.sax.SAXException  ;
18  
19  import javax.xml.parsers.SAXParserFactory  ;  
20  import javax.xml.parsers.ParserConfigurationException  ;  
21  import javax.xml.parsers.SAXParser  ;  
22  
23  /**
24   * The <code>XMLDecoder</code> class is used to read XML documents 
25   * created using the <code>XMLEncoder</code> and is used just like 
26   * the <code>ObjectInputStream</code>. For example, one can use 
27   * the following fragment to read the first object defined 
28   * in an XML document written by the <code>XMLEncoder</code> 
29   * class: 
30   * <pre>
31   *       XMLDecoder d = new XMLDecoder(
32   *                          new BufferedInputStream(
33   *                              new FileInputStream("Test.xml")));
34   *       Object result = d.readObject();
35   *       d.close();
36   * </pre>
37   * 
38   *<p>
39   * For more information you might also want to check out
40   * <a
41   href="http://java.sun.com/products/jfc/tsc/articles/persistence3">Long Term Persistence of JavaBeans Components: XML Schema</a>,
42   * an article in <em>The Swing Connection.</em>
43   * @see XMLEncoder
44   * @see java.io.ObjectInputStream
45   *
46   * @since 1.4
47   * 
48   * @version 1.30 06/01/04
49   * @author Philip Milne
50   */
51  public class XMLDecoder { 
52      private InputStream   in; 
53      private Object   owner; 
54      private ExceptionListener   exceptionListener; 
55      private ObjectHandler handler; 
56      private Reference   clref;
57      
58      /** 
59       * Creates a new input stream for reading archives  
60       * created by the <code>XMLEncoder</code> class. 
61       *
62       * @param in The underlying stream. 
63       *
64       * @see XMLEncoder#XMLEncoder(OutputStream)
65       */ 
66      public XMLDecoder(InputStream   in) { 
67          this(in, null); 
68      } 
69      
70      /** 
71       * Creates a new input stream for reading archives  
72       * created by the <code>XMLEncoder</code> class. 
73       *
74       * @param in The underlying stream. 
75       * @param owner The owner of this stream. 
76       *
77       */ 
78      public XMLDecoder(InputStream   in, Object   owner) { 
79          this(in, owner, null); 
80      } 
81      
82      /** 
83       * Creates a new input stream for reading archives  
84       * created by the <code>XMLEncoder</code> class. 
85       *
86       * @param in the underlying stream. 
87       * @param owner the owner of this stream. 
88       * @param exceptionListener the exception handler for the stream;
89       *        if <code>null</code> the default exception listener will be used.
90       */ 
91      public XMLDecoder(InputStream   in, Object   owner, ExceptionListener   exceptionListener) { 
92      this(in, owner, exceptionListener, null);
93      }
94  
95      /** 
96       * Creates a new input stream for reading archives  
97       * created by the <code>XMLEncoder</code> class. 
98       *
99       * @param in the underlying stream.  <code>null</code> may be passed without
100      *        error, though the resulting XMLDecoder will be useless
101      * @param owner the owner of this stream.  <code>null</code> is a legal
102      *        value
103      * @param exceptionListener the exception handler for the stream, or
104      *        <code>null</code> to use the default
105      * @param cl the class loader used for instantiating objects.  
106      *        <code>null</code> indicates that the default class loader should
107      *        be used
108      * @since 1.5
109      */ 
110     public XMLDecoder(InputStream   in, Object   owner, 
111                       ExceptionListener   exceptionListener, ClassLoader   cl) { 
112         this.in = in;  
113         setOwner(owner);  
114         setExceptionListener(exceptionListener); 
115         setClassLoader(cl);
116     } 
117 
118     
119     /**
120      * Set the class loader used to instantiate objects for this stream. 
121      * 
122      * @param cl a classloader to use; if null then the default class loader
123      *           will be used
124      */
125     private void setClassLoader(ClassLoader   cl) {
126     if (cl != null) {
127         this.clref = new WeakReference  (cl);
128     }
129     }
130 
131     /**
132      * Return the class loader used to instantiate objects. If the class loader 
133      * has not been explicitly set then null is returned.
134      * 
135      * @return the class loader used to instantiate objects 
136      */ 
137     private ClassLoader   getClassLoader() { 
138         if (clref != null) {
139             return (ClassLoader  )clref.get();
140         }
141         return null; 
142     } 
143 
144     /**
145      * This method closes the input stream associated 
146      * with this stream. 
147      */
148     public void close() { 
149         if (in != null) {
150             try { 
151                 in.close(); 
152             } 
153             catch (IOException   e) { 
154                 getExceptionListener().exceptionThrown(e); 
155             }
156         }
157     }
158     
159     /** 
160      * Sets the exception handler for this stream to <code>exceptionListener</code>. 
161      * The exception handler is notified when this stream catches recoverable 
162      * exceptions.
163      * 
164      * @param exceptionListener The exception handler for this stream;
165      * if <code>null</code> the default exception listener will be used. 
166      *
167      * @see #getExceptionListener
168      */ 
169     public void setExceptionListener(ExceptionListener   exceptionListener) { 
170         this.exceptionListener = exceptionListener; 
171     } 
172     
173     /**
174      * Gets the exception handler for this stream. 
175      * 
176      * @return The exception handler for this stream. 
177      *     Will return the default exception listener if this has not explicitly been set.
178      *
179      * @see #setExceptionListener
180      */ 
181     public ExceptionListener   getExceptionListener() { 
182         return (exceptionListener != null) ? exceptionListener : 
183         Statement.defaultExceptionListener;
184     } 
185     
186     /** 
187      * Reads the next object from the underlying input stream. 
188      *
189      * @return the next object read
190      *
191      * @throws ArrayIndexOutOfBoundsException if the stream contains no objects 
192      *         (or no more objects)
193      *
194      * @see XMLEncoder#writeObject
195      */ 
196     public Object   readObject() { 
197     if (in == null) {
198         return null;
199     }
200         if (handler == null) {
201             SAXParserFactory   factory = SAXParserFactory.newInstance();
202             try {
203                 SAXParser   saxParser = factory.newSAXParser();
204                 handler = new ObjectHandler(this, getClassLoader());
205                 saxParser.parse(in, handler); 
206             } 
207             catch (ParserConfigurationException   e) {
208                 getExceptionListener().exceptionThrown(e);
209             } 
210             catch (SAXException   se) { 
211                 Exception   e = se.getException(); 
212                 getExceptionListener().exceptionThrown((e == null) ? se : e); 
213             }
214             catch (IOException   ioe) { 
215                 getExceptionListener().exceptionThrown(ioe); 
216             }
217         }
218         return handler.dequeueResult(); 
219     } 
220     
221     /** 
222      * Sets the owner of this decoder to <code>owner</code>. 
223      * 
224      * @param owner The owner of this decoder. 
225      *
226      * @see #getOwner
227      */ 
228     public void setOwner(Object   owner) { 
229         this.owner = owner; 
230     }
231         
232     /**
233      * Gets the owner of this decoder. 
234      * 
235      * @return The owner of this decoder. 
236      *
237      * @see #setOwner
238      */ 
239     public Object   getOwner() {
240     return owner; 
241     }
242 }
243
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags