001/* java.beans.XMLDecoder -- 002 Copyright (C) 2004, 2005, 2006 Free Software Foundation, Inc. 003 004This file is part of GNU Classpath. 005 006GNU Classpath is free software; you can redistribute it and/or modify 007it under the terms of the GNU General Public License as published by 008the Free Software Foundation; either version 2, or (at your option) 009any later version. 010 011GNU Classpath is distributed in the hope that it will be useful, but 012WITHOUT ANY WARRANTY; without even the implied warranty of 013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014General Public License for more details. 015 016You should have received a copy of the GNU General Public License 017along with GNU Classpath; see the file COPYING. If not, write to the 018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 01902110-1301 USA. 020 021Linking this library statically or dynamically with other modules is 022making a combined work based on this library. Thus, the terms and 023conditions of the GNU General Public License cover the whole 024combination. 025 026As a special exception, the copyright holders of this library give you 027permission to link this library with independent modules to produce an 028executable, regardless of the license terms of these independent 029modules, and to copy and distribute the resulting executable under 030terms of your choice, provided that you also meet, for each linked 031independent module, the terms and conditions of the license of that 032module. An independent module is a module which is not derived from 033or based on this library. If you modify this library, you may extend 034this exception to your version of the library, but you are not 035obligated to do so. If you do not wish to do so, delete this 036exception statement from your version. */ 037 038 039package java.beans; 040 041import gnu.java.beans.DefaultExceptionListener; 042import gnu.java.beans.decoder.PersistenceParser; 043 044import java.io.IOException; 045import java.io.InputStream; 046import java.util.Iterator; 047import java.util.NoSuchElementException; 048 049/** 050 * The XMLDecoder reads XML data that is structured according to 051 * <a href="http://java.sun.com/products/jfc/tsc/articles/persistence3/javabeans.dtd">this</a> DTD 052 * and creates objects according to the content. Usually such data is generated using the 053 * {@link XMLEncoder} class. 054 * <p> 055 * An example XML document might look like this: 056 * <code> 057 * <java> 058 * <string>Hello World</string> 059 * <int>200</int> 060 * </java> 061 * </code> 062 * <p>To read the <code>String</code> and the <code>Integer</code> instance the following can be used (assume 063 * the XML data can be obtained from the InputStream):</p> 064 * <code> 065 * XMLDecoder decoder = new XMLDecoder(inputStreamContainingXMLData); 066 * String message = (String) decoder.readObject(); 067 * Integer number = (Integer) decoder.readObject(); 068 * </code> 069 * <p>Besides this basic functionality the <code>XMLDecoder</code> has some more features that might come 070 * handy in certain situations:</p> 071 * <p>An owner object can be set using the <code>setOwner</code> method which can then be accessed when 072 * decoding. This feature is only useful if the XML data is aware of the owner object. Such data may 073 * look like this (assume that the owner object is a JFrame instance):</p> 074 * <code> 075 * <java> 076 * <void method="getOwner"> 077 * <void method="setVisible"> 078 * <boolean>true<boolean> 079 * </void> 080 * </void> 081 * </java> 082 * </code> 083 * This accesses the <code>JFrame</code> and makes it visible using the <code>setVisible</code> method. 084 * <p>Please note that changing the owner <b>after</b> the having read the first object has no effect, 085 * because all object have been decoded then.</p> 086 * <p>If the <code>XMLDecoder</code> is created with no {@link ExceptionListener} instance a default one 087 * is used that prints an error message to <code>System.err</code> whenever a recoverable exception 088 * is thrown. Recovarable exceptions occur when the XML data cannot be interpreted correctly (e.g 089 * unknown classes or methods, invocation on null, ...). In general be very careful when the 090 * <code>XMLDecoder</code> provoked such exceptions because the resulting object(s) may be in an 091 * undesirable state.</p> 092 * <p>Note that changing the ExceptionListener instance after <code>readObject</code> has been called 093 * once has no effect because the decoding is completed then.</p> 094 * <p>At last one can provide a specific <code>ClassLoader</code> which is then used when <code>Class</code> 095 * objects are accessed. See {@link java.lang.Class#forName(String, boolean, ClassLoader)} for details 096 * on this.</p> 097 * <p>Note: If the <code>InputStream</code> instance given to any of the constructors is <code>null</code> 098 * the resulting <code>XMLDecoder</code> will be silently (without any exception) useless. Each call 099 * to <code>readObject</code> will return <code>null</code> and never throws an 100 * <code>ArrayIndexOutOfBoundsException</code>.</p> 101 * 102 * @author Robert Schuster 103 * @since 1.4 104 * @status updated to 1.5 105 */ 106public class XMLDecoder 107 implements AutoCloseable 108{ 109 private Object owner; 110 111 private ExceptionListener exceptionListener; 112 113 private InputStream inputStream; 114 115 private boolean isStreamClosed; 116 117 private ClassLoader classLoader; 118 119 private Iterator iterator; 120 121 /** Creates a XMLDecoder instance that parses the XML data of the given input stream. 122 * Using this constructor no special ClassLoader, a default ExceptionListener 123 * and no owner object is used. 124 * 125 * @param in InputStream to read XML data from. 126 */ 127 public XMLDecoder(InputStream in) 128 { 129 this(in, null); 130 } 131 132 /** Creates a XMLDecoder instance that parses the XML data of the given input stream. 133 * Using this constructor no special ClassLoader and a default ExceptionListener 134 * is used. 135 * 136 * @param in InputStream to read XML data from. 137 * @param owner Owner object which can be accessed and modified while parsing. 138 */ 139 public XMLDecoder(InputStream in, Object owner) 140 { 141 this(in, owner, null); 142 } 143 144 /** Creates a XMLDecoder instance that parses the XML data of the given input stream. 145 * If the ExceptionListener argument is null a default implementation is used. 146 * 147 * @param in InputStream to read XML data from. 148 * @param owner Owner object which can be accessed and modified while parsing. 149 * @param exceptionListener ExceptionListener instance to which exception notifications are send. 150 */ 151 public XMLDecoder( 152 InputStream in, 153 Object owner, 154 ExceptionListener exceptionListener) 155 { 156 this( 157 in, 158 owner, 159 exceptionListener, 160 Thread.currentThread().getContextClassLoader()); 161 } 162 163 /** Creates a XMLDecoder instance that parses the XML data of the given input stream. 164 * If the ExceptionListener argument is null a default implementation is used. 165 * 166 * @param in InputStream to read XML data from. 167 * @param owner Owner object which can be accessed and modified while parsing. 168 * @param listener ExceptionListener instance to which exception notifications are send. 169 * @param cl ClassLoader instance that is used for calls to <code>Class.forName(String, boolean, ClassLoader)</code> 170 * @since 1.5 171 */ 172 public XMLDecoder( 173 InputStream in, 174 Object owner, 175 ExceptionListener listener, 176 ClassLoader cl) 177 { 178 // initially here was a check for the validity of the InputStream argument but some 179 // great engineers decided that this API should silently discard this and behave rather 180 // odd: readObject will always return null ... 181 inputStream = in; 182 183 setExceptionListener(listener); 184 185 // validity of this object is checked in Class.forName() and therefore may be null 186 classLoader = cl; 187 188 this.owner = owner; 189 } 190 191 /** Closes the stream associated with this decoder. This should be done after having read all 192 * decoded objects. 193 * <p>See the description of the {@link #readObject()} for the effect caused by <code>close</code>.</p> 194 */ 195 public void close() 196 { 197 if (isStreamClosed) 198 { 199 return; 200 } 201 202 try 203 { 204 inputStream.close(); 205 isStreamClosed = true; 206 } 207 catch (IOException e) 208 { 209 // bad style forced by original API design ... 210 } 211 } 212 213 /** Returns the ExceptionListener instance associated with this decoder. 214 * <p>See the description of {@link XMLDecoder} class for more information on the ExceptionListener.</p> 215 * 216 * @return Current ExceptionListener of the decoder. 217 */ 218 public ExceptionListener getExceptionListener() 219 { 220 return exceptionListener; 221 } 222 223 /** Returns the owner object of the decoder. This method is usually called 224 * from within the parsed XML data. 225 * <p>See the description of {@link XMLDecoder} class for more information on the owner object.</p> 226 * 227 * @return The owner object of this decoder. 228 */ 229 public Object getOwner() 230 { 231 return owner; 232 } 233 234 /** Returns the next available decoded object. 235 * <p>Note that the actual decoding takes place when the method is called for the first time.</p> 236 * <p>If the <code>close</code> method was already called a <code>NoSuchElementException</code> 237 * is thrown.</p> 238 * <p>If the InputStream instance used in the constructors was <code>null</code> this method 239 * will always return <code>null</code> itself.</p> 240 * 241 * @return The next object in a sequence decoded from XML data. 242 * @throws ArrayIndexOutOfBoundsException When no more objects are available. 243 */ 244 public Object readObject() throws ArrayIndexOutOfBoundsException 245 { 246 // note: the RI does it this way ... 247 if(inputStream == null) { 248 return null; 249 } 250 251 // note: the original API documentation says nothing on what to do 252 // when the stream was closed before readObject is called but it actually 253 // throws a NoSuchElementException - this behaviour is imitated here 254 if (isStreamClosed) 255 { 256 throw new NoSuchElementException("Cannot read any objects - XMLDecoder was already closed."); 257 } 258 259 // creates the PersistenceParser (doing the parsing and decoding) and returns its 260 // Iterator on first invocation 261 if (iterator == null) 262 { 263 iterator = 264 new PersistenceParser( 265 inputStream, 266 exceptionListener, 267 classLoader, 268 this) 269 .iterator(); 270 } 271 272 // note: done according to the official documentation 273 if (!iterator.hasNext()) 274 { 275 throw new ArrayIndexOutOfBoundsException("No more objects available from this XMLDecoder."); 276 } 277 278 // returns just the next object if there was no problem 279 return iterator.next(); 280 } 281 282 /** Sets the ExceptionListener instance to which notifications of exceptions are send 283 * while parsing the XML data. 284 * <p>See the description of {@link XMLDecoder} class for more information on the ExceptionListener.</p> 285 * 286 * @param listener 287 */ 288 public void setExceptionListener(ExceptionListener listener) 289 { 290 // uses a default implementation when null 291 if (listener == null) 292 { 293 listener = DefaultExceptionListener.INSTANCE; 294 } 295 exceptionListener = listener; 296 } 297 298 /** Sets the owner object which can be accessed from the parsed XML data. 299 * <p>See the description of {@link XMLDecoder} class for more information on the owner object.</p> 300 * 301 * @param newOwner 302 */ 303 public void setOwner(Object newOwner) 304 { 305 owner = newOwner; 306 } 307 308}