001 /*
002 * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025 package javax.xml.bind.helpers;
026
027 import org.xml.sax.InputSource;
028 import org.xml.sax.SAXException;
029 import org.xml.sax.XMLReader;
030 import org.w3c.dom.Node;
031
032 import javax.xml.bind.JAXBException;
033 import javax.xml.bind.PropertyException;
034 import javax.xml.bind.UnmarshalException;
035 import javax.xml.bind.Unmarshaller;
036 import javax.xml.bind.ValidationEventHandler;
037 import javax.xml.bind.JAXBElement;
038 import javax.xml.bind.annotation.adapters.XmlAdapter;
039 import javax.xml.bind.attachment.AttachmentUnmarshaller;
040 import javax.xml.parsers.ParserConfigurationException;
041 import javax.xml.parsers.SAXParserFactory;
042 import javax.xml.stream.XMLEventReader;
043 import javax.xml.stream.XMLStreamReader;
044 import javax.xml.transform.Source;
045 import javax.xml.transform.dom.DOMSource;
046 import javax.xml.transform.sax.SAXSource;
047 import javax.xml.transform.stream.StreamSource;
048 import javax.xml.validation.Schema;
049 import java.io.File;
050 import java.io.Reader;
051 import java.net.MalformedURLException;
052 import java.net.URL;
053
054 /**
055 * Partial default <tt>Unmarshaller</tt> implementation.
056 *
057 * <p>
058 * This class provides a partial default implementation for the
059 * {@link javax.xml.bind.Unmarshaller}interface.
060 *
061 * <p>
062 * A JAXB Provider has to implement five methods (getUnmarshallerHandler,
063 * unmarshal(Node), unmarshal(XMLReader,InputSource),
064 * unmarshal(XMLStreamReader), and unmarshal(XMLEventReader).
065 *
066 * @author <ul>
067 * <li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li>
068 * </ul>
069 * @version $Revision: 1.13 $ $Date: 2005/07/28 22:18:12 $
070 * @see javax.xml.bind.Unmarshaller
071 * @since JAXB1.0
072 */
073 public abstract class AbstractUnmarshallerImpl implements Unmarshaller {
074 /** handler that will be used to process errors and warnings during unmarshal */
075 private ValidationEventHandler eventHandler = new DefaultValidationEventHandler();
076
077 /** whether or not the unmarshaller will validate */
078 protected boolean validating = false;
079
080 /**
081 * XMLReader that will be used to parse a document.
082 */
083 private XMLReader reader = null;
084
085 /**
086 * Obtains a configured XMLReader.
087 *
088 * This method is used when the client-specified
089 * {@link SAXSource} object doesn't have XMLReader.
090 *
091 * {@link Unmarshaller} is not re-entrant, so we will
092 * only use one instance of XMLReader.
093 */
094 protected XMLReader getXMLReader() throws JAXBException {
095 if (reader == null) {
096 try {
097 SAXParserFactory parserFactory;
098 parserFactory = SAXParserFactory.newInstance();
099 parserFactory.setNamespaceAware(true);
100 // there is no point in asking a validation because
101 // there is no guarantee that the document will come with
102 // a proper schemaLocation.
103 parserFactory.setValidating(false);
104 reader = parserFactory.newSAXParser().getXMLReader();
105 } catch (ParserConfigurationException e) {
106 throw new JAXBException(e);
107 } catch (SAXException e) {
108 throw new JAXBException(e);
109 }
110 }
111 return reader;
112 }
113
114 public Object unmarshal(Source source) throws JAXBException {
115 if (source == null) {
116 throw new IllegalArgumentException(Messages.format(
117 Messages.MUST_NOT_BE_NULL, "source"));
118 }
119
120 if (source instanceof SAXSource)
121 return unmarshal((SAXSource) source);
122 if (source instanceof StreamSource)
123 return unmarshal(streamSourceToInputSource((StreamSource) source));
124 if (source instanceof DOMSource)
125 return unmarshal(((DOMSource) source).getNode());
126
127 // we don't handle other types of Source
128 throw new IllegalArgumentException();
129 }
130
131 // use the client specified XMLReader contained in the SAXSource.
132 private Object unmarshal(SAXSource source) throws JAXBException {
133
134 XMLReader reader = source.getXMLReader();
135 if (reader == null)
136 reader = getXMLReader();
137
138 return unmarshal(reader, source.getInputSource());
139 }
140
141 /**
142 * Unmarshals an object by using the specified XMLReader and the InputSource.
143 *
144 * The callee should call the setErrorHandler method of the XMLReader
145 * so that errors are passed to the client-specified ValidationEventHandler.
146 */
147 protected abstract Object unmarshal(XMLReader reader,
148 InputSource source) throws JAXBException;
149
150 public final Object unmarshal(InputSource source)
151 throws JAXBException {
152 if (source == null) {
153 throw new IllegalArgumentException(Messages.format(
154 Messages.MUST_NOT_BE_NULL, "source"));
155 }
156
157 return unmarshal(getXMLReader(), source);
158 }
159
160 private Object unmarshal(String url) throws JAXBException {
161 return unmarshal(new InputSource(url));
162 }
163
164 public final Object unmarshal(URL url) throws JAXBException {
165 if (url == null) {
166 throw new IllegalArgumentException(Messages.format(
167 Messages.MUST_NOT_BE_NULL, "url"));
168 }
169
170 return unmarshal(url.toExternalForm());
171 }
172
173 public final Object unmarshal(File f) throws JAXBException {
174 if (f == null) {
175 throw new IllegalArgumentException(Messages.format(
176 Messages.MUST_NOT_BE_NULL, "file"));
177 }
178
179 try {
180 // copied from JAXP
181 String path = f.getAbsolutePath();
182 if (File.separatorChar != '/')
183 path = path.replace(File.separatorChar, '/');
184 if (!path.startsWith("/"))
185 path = "/" + path;
186 if (!path.endsWith("/") && f.isDirectory())
187 path = path + "/";
188 return unmarshal(new URL("file", "", path));
189 } catch (MalformedURLException e) {
190 throw new IllegalArgumentException(e.getMessage());
191 }
192 }
193
194 public final Object unmarshal(java.io.InputStream is)
195 throws JAXBException {
196
197 if (is == null) {
198 throw new IllegalArgumentException(Messages.format(
199 Messages.MUST_NOT_BE_NULL, "is"));
200 }
201
202 InputSource isrc = new InputSource(is);
203 return unmarshal(isrc);
204 }
205
206 public final Object unmarshal(Reader reader) throws JAXBException {
207 if (reader == null) {
208 throw new IllegalArgumentException(Messages.format(
209 Messages.MUST_NOT_BE_NULL, "reader"));
210 }
211
212 InputSource isrc = new InputSource(reader);
213 return unmarshal(isrc);
214 }
215
216 private static InputSource streamSourceToInputSource(StreamSource ss) {
217 InputSource is = new InputSource();
218 is.setSystemId(ss.getSystemId());
219 is.setByteStream(ss.getInputStream());
220 is.setCharacterStream(ss.getReader());
221
222 return is;
223 }
224
225 /**
226 * Indicates whether or not the Unmarshaller is configured to validate
227 * during unmarshal operations.
228 * <p>
229 * <i><b>Note:</b> I named this method isValidating() to stay in-line
230 * with JAXP, as opposed to naming it getValidating(). </i>
231 *
232 * @return true if the Unmarshaller is configured to validate during
233 * unmarshal operations, false otherwise
234 * @throws JAXBException if an error occurs while retrieving the validating
235 * flag
236 */
237 public boolean isValidating() throws JAXBException {
238 return validating;
239 }
240
241 /**
242 * Allow an application to register a validation event handler.
243 * <p>
244 * The validation event handler will be called by the JAXB Provider if any
245 * validation errors are encountered during calls to any of the
246 * <tt>unmarshal</tt> methods. If the client application does not register
247 * a validation event handler before invoking the unmarshal methods, then
248 * all validation events will be silently ignored and may result in
249 * unexpected behaviour.
250 *
251 * @param handler the validation event handler
252 * @throws JAXBException if an error was encountered while setting the
253 * event handler
254 */
255 public void setEventHandler(ValidationEventHandler handler)
256 throws JAXBException {
257
258 if (handler == null) {
259 eventHandler = new DefaultValidationEventHandler();
260 } else {
261 eventHandler = handler;
262 }
263 }
264
265 /**
266 * Specifies whether or not the Unmarshaller should validate during
267 * unmarshal operations. By default, the <tt>Unmarshaller</tt> does
268 * not validate.
269 * <p>
270 * This method may only be invoked before or after calling one of the
271 * unmarshal methods.
272 *
273 * @param validating true if the Unmarshaller should validate during
274 * unmarshal, false otherwise
275 * @throws JAXBException if an error occurred while enabling or disabling
276 * validation at unmarshal time
277 */
278 public void setValidating(boolean validating) throws JAXBException {
279 this .validating = validating;
280 }
281
282 /**
283 * Return the current event handler or the default event handler if one
284 * hasn't been set.
285 *
286 * @return the current ValidationEventHandler or the default event handler
287 * if it hasn't been set
288 * @throws JAXBException if an error was encountered while getting the
289 * current event handler
290 */
291 public ValidationEventHandler getEventHandler()
292 throws JAXBException {
293 return eventHandler;
294 }
295
296 /**
297 * Creates an UnmarshalException from a SAXException.
298 *
299 * This is an utility method provided for the derived classes.
300 *
301 * <p>
302 * When a provider-implemented ContentHandler wants to throw a
303 * JAXBException, it needs to wrap the exception by a SAXException.
304 * If the unmarshaller implementation blindly wrap SAXException
305 * by JAXBException, such an exception will be a JAXBException
306 * wrapped by a SAXException wrapped by another JAXBException.
307 * This is silly.
308 *
309 * <p>
310 * This method checks the nested exception of SAXException
311 * and reduce those excessive wrapping.
312 *
313 * @return the resulting UnmarshalException
314 */
315 protected UnmarshalException createUnmarshalException(SAXException e) {
316 // check the nested exception to see if it's an UnmarshalException
317 Exception nested = e.getException();
318 if (nested instanceof UnmarshalException)
319 return (UnmarshalException) nested;
320
321 if (nested instanceof RuntimeException)
322 // typically this is an unexpected exception,
323 // just throw it rather than wrap it, so that the full stack
324 // trace can be displayed.
325 throw (RuntimeException) nested;
326
327 // otherwise simply wrap it
328 if (nested != null)
329 return new UnmarshalException(nested);
330 else
331 return new UnmarshalException(e);
332 }
333
334 /**
335 * Default implementation of the setProperty method always
336 * throws PropertyException since there are no required
337 * properties. If a provider needs to handle additional
338 * properties, it should override this method in a derived class.
339 */
340 public void setProperty(String name, Object value)
341 throws PropertyException {
342
343 if (name == null) {
344 throw new IllegalArgumentException(Messages.format(
345 Messages.MUST_NOT_BE_NULL, "name"));
346 }
347
348 throw new PropertyException(name, value);
349 }
350
351 /**
352 * Default implementation of the getProperty method always
353 * throws PropertyException since there are no required
354 * properties. If a provider needs to handle additional
355 * properties, it should override this method in a derived class.
356 */
357 public Object getProperty(String name) throws PropertyException {
358
359 if (name == null) {
360 throw new IllegalArgumentException(Messages.format(
361 Messages.MUST_NOT_BE_NULL, "name"));
362 }
363
364 throw new PropertyException(name);
365 }
366
367 public Object unmarshal(XMLEventReader reader) throws JAXBException {
368
369 throw new UnsupportedOperationException();
370 }
371
372 public Object unmarshal(XMLStreamReader reader)
373 throws JAXBException {
374
375 throw new UnsupportedOperationException();
376 }
377
378 public <T> JAXBElement<T> unmarshal(Node node, Class<T> expectedType)
379 throws JAXBException {
380 throw new UnsupportedOperationException();
381 }
382
383 public <T> JAXBElement<T> unmarshal(Source source,
384 Class<T> expectedType) throws JAXBException {
385 throw new UnsupportedOperationException();
386 }
387
388 public <T> JAXBElement<T> unmarshal(XMLStreamReader reader,
389 Class<T> expectedType) throws JAXBException {
390 throw new UnsupportedOperationException();
391 }
392
393 public <T> JAXBElement<T> unmarshal(XMLEventReader reader,
394 Class<T> expectedType) throws JAXBException {
395 throw new UnsupportedOperationException();
396 }
397
398 public void setSchema(Schema schema) {
399 throw new UnsupportedOperationException();
400 }
401
402 public Schema getSchema() {
403 throw new UnsupportedOperationException();
404 }
405
406 public void setAdapter(XmlAdapter adapter) {
407 if (adapter == null)
408 throw new IllegalArgumentException();
409 setAdapter((Class) adapter.getClass(), adapter);
410 }
411
412 public <A extends XmlAdapter> void setAdapter(Class<A> type,
413 A adapter) {
414 throw new UnsupportedOperationException();
415 }
416
417 public <A extends XmlAdapter> A getAdapter(Class<A> type) {
418 throw new UnsupportedOperationException();
419 }
420
421 public void setAttachmentUnmarshaller(AttachmentUnmarshaller au) {
422 throw new UnsupportedOperationException();
423 }
424
425 public AttachmentUnmarshaller getAttachmentUnmarshaller() {
426 throw new UnsupportedOperationException();
427 }
428
429 public void setListener(Listener listener) {
430 throw new UnsupportedOperationException();
431 }
432
433 public Listener getListener() {
434 throw new UnsupportedOperationException();
435 }
436 }
|