javax.xml.bind.Unmarshaller Maven / Gradle / Ivy
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2001-2011 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package javax.xml.bind;
/**
* The Unmarshaller class governs the process of deserializing XML
* data into newly created Java content trees, optionally validating the XML
* data as it is unmarshalled. It provides the basic unmarshalling methods:
*
*
* Unmarshalling from a File:
*
*
* JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
* Unmarshaller u = jc.createUnmarshaller();
* Object o = u.unmarshal( new File( "nosferatu.xml" ) );
*
*
*
*
*
* Unmarshalling from an InputStream:
*
*
* InputStream is = new FileInputStream( "nosferatu.xml" );
* JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
* Unmarshaller u = jc.createUnmarshaller();
* Object o = u.unmarshal( is );
*
*
*
*
* Unmarshalling from a URL:
*
*
* JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
* Unmarshaller u = jc.createUnmarshaller();
* URL url = new URL( "http://beaker.east/nosferatu.xml" );
* Object o = u.unmarshal( url );
*
*
*
*
* Unmarshalling from a StringBuffer using a
* javax.xml.transform.stream.StreamSource:
*
*
* JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
* Unmarshaller u = jc.createUnmarshaller();
* StringBuffer xmlStr = new StringBuffer( "<?xml version="1.0"?>..." );
* Object o = u.unmarshal( new StreamSource( new StringReader( xmlStr.toString() ) ) );
*
*
*
*
* Unmarshalling from a org.w3c.dom.Node:
*
*
* JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
* Unmarshaller u = jc.createUnmarshaller();
*
* DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
* dbf.setNamespaceAware(true);
* DocumentBuilder db = dbf.newDocumentBuilder();
* Document doc = db.parse(new File( "nosferatu.xml"));
* Object o = u.unmarshal( doc );
*
*
*
*
* Unmarshalling from a javax.xml.transform.sax.SAXSource using a
* client specified validating SAX2.0 parser:
*
*
* // configure a validating SAX2.0 parser (Xerces2)
* static final String JAXP_SCHEMA_LANGUAGE =
* "http://java.sun.com/xml/jaxp/properties/schemaLanguage";
* static final String JAXP_SCHEMA_LOCATION =
* "http://java.sun.com/xml/jaxp/properties/schemaSource";
* static final String W3C_XML_SCHEMA =
* "http://www.w3.org/2001/XMLSchema";
*
* System.setProperty( "javax.xml.parsers.SAXParserFactory",
* "org.apache.xerces.jaxp.SAXParserFactoryImpl" );
*
* SAXParserFactory spf = SAXParserFactory.newInstance();
* spf.setNamespaceAware(true);
* spf.setValidating(true);
* SAXParser saxParser = spf.newSAXParser();
*
* try {
* saxParser.setProperty(JAXP_SCHEMA_LANGUAGE, W3C_XML_SCHEMA);
* saxParser.setProperty(JAXP_SCHEMA_LOCATION, "http://....");
* } catch (SAXNotRecognizedException x) {
* // exception handling omitted
* }
*
* XMLReader xmlReader = saxParser.getXMLReader();
* SAXSource source =
* new SAXSource( xmlReader, new InputSource( "http://..." ) );
*
* // Setup JAXB to unmarshal
* JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
* Unmarshaller u = jc.createUnmarshaller();
* ValidationEventCollector vec = new ValidationEventCollector();
* u.setEventHandler( vec );
*
* // turn off the JAXB provider's default validation mechanism to
* // avoid duplicate validation
* u.setValidating( false )
*
* // unmarshal
* Object o = u.unmarshal( source );
*
* // check for events
* if( vec.hasEvents() ) {
* // iterate over events
* }
*
*
*
*
* The JAXBContext object used to create this Unmarshaller
* was initialized with a contextPath which determines the schema
* derived content available to the Marshaller, Unmarshaller,
* and Validator objects it produces. If the JAXBContext
* object that was used to create this Unmarshaller does not have
* enough information to know how to unmarshal the XML content from the
* specified source, then the unmarshal operation will abort immediately by
* throwing a {@link UnmarshalException UnmarshalException}.
*
*
*
* Support for SAX2.0 Compliant Parsers
*
* A client application has the ability to select the SAX2.0 compliant parser
* of their choice. If a SAX parser is not selected, then the JAXB Provider's
* default parser will be used. Eventhough the JAXB Provider's default parser
* is not required to be SAX2.0 compliant, all providers are required to allow
* a client application to specify their own SAX2.0 parser. Some providers may
* require the client application to specify the SAX2.0 parser at schema compile
* time. See {@link #unmarshal(javax.xml.transform.Source) unmarshal(Source)}
* for more detail.
*
*
*
* Validation and Well-Formedness
*
*
* A client application can enable or disable the provider's default validation
* mechanism via the setValidating API. Sophisticated clients can
* specify their own validating SAX 2.0 compliant parser and bypass the
* provider's default validation mechanism using the
* {@link #unmarshal(javax.xml.transform.Source) unmarshal(Source)} API.
*
*
* For a more detailed definition of how validation errors and warnings are
* handled, see the {@link Validator Validator} javadoc.
*
*
*
*
* There currently are not any properties required to be supported by all
* JAXB Providers on Unmarshaller. However, some providers may support
* their own set of provider specific properties.
*
*
*
* @author - Ryan Shoemaker, Sun Microsystems, Inc.
- Kohsuke Kawaguchi, Sun Microsystems, Inc.
- Joe Fialli, Sun Microsystems, Inc.
* @version $Revision: 1.28 $ $Date: 2003/02/28 21:44:24 $
* @see JAXBContext
* @see Marshaller
* @see Validator
* @since JAXB1.0
*/
public interface Unmarshaller {
/**
* Unmarshal XML data from the specified file and return the resulting
* content tree.
*
* @param f the file to unmarshal XML data from
* @return the newly created root object of the java content tree
*
* @throws JAXBException
* If any unexpected errors occur while unmarshalling
* @throws UnmarshalException
* If the {@link ValidationEventHandler ValidationEventHandler}
* returns false from its handleEvent method or the
* Unmarshaller is unable to perform the XML to Java
* binding. See Unmarshalling XML Data
* @throws IllegalArgumentException
* If the file parameter is null
*/
public Object unmarshal( java.io.File f ) throws JAXBException;
/**
* Unmarshal XML data from the specified InputStream and return the
* resulting content tree. Validation event location information may
* be incomplete when using this form of the unmarshal API.
*
* @param is the InputStream to unmarshal XML data from
* @return the newly created root object of the java content tree
*
* @throws JAXBException
* If any unexpected errors occur while unmarshalling
* @throws UnmarshalException
* If the {@link ValidationEventHandler ValidationEventHandler}
* returns false from its handleEvent method or the
* Unmarshaller is unable to perform the XML to Java
* binding. See Unmarshalling XML Data
* @throws IllegalArgumentException
* If the InputStream parameter is null
*/
public Object unmarshal( java.io.InputStream is ) throws JAXBException;
/**
* Unmarshal XML data from the specified URL and return the resulting
* content tree.
*
* @param url the url to unmarshal XML data from
* @return the newly created root object of the java content tree
*
* @throws JAXBException
* If any unexpected errors occur while unmarshalling
* @throws UnmarshalException
* If the {@link ValidationEventHandler ValidationEventHandler}
* returns false from its handleEvent method or the
* Unmarshaller is unable to perform the XML to Java
* binding. See Unmarshalling XML Data
* @throws IllegalArgumentException
* If the URL parameter is null
*/
public Object unmarshal( java.net.URL url ) throws JAXBException;
/**
* Unmarshal XML data from the specified SAX InputSource and return the
* resulting content tree.
*
* @param source the input source to unmarshal XML data from
* @return the newly created root object of the java content tree
*
* @throws JAXBException
* If any unexpected errors occur while unmarshalling
* @throws UnmarshalException
* If the {@link ValidationEventHandler ValidationEventHandler}
* returns false from its handleEvent method or the
* Unmarshaller is unable to perform the XML to Java
* binding. See Unmarshalling XML Data
* @throws IllegalArgumentException
* If the InputSource parameter is null
*/
public Object unmarshal( org.xml.sax.InputSource source ) throws JAXBException;
/**
* Unmarshal XML data from the specified DOM tree and return the resulting
* content tree.
*
* @param node
* the document/element to unmarshal XML data from.
* The caller must support at least Document and Element.
* @return the newly created root object of the java content tree
*
* @throws JAXBException
* If any unexpected errors occur while unmarshalling
* @throws UnmarshalException
* If the {@link ValidationEventHandler ValidationEventHandler}
* returns false from its handleEvent method or the
* Unmarshaller is unable to perform the XML to Java
* binding. See Unmarshalling XML Data
* @throws IllegalArgumentException
* If the Node parameter is null
*/
public Object unmarshal( org.w3c.dom.Node node ) throws JAXBException;
/**
* Unmarshal XML data from the specified XML Source and return the
* resulting content tree.
*
* SAX 2.0 Parser Pluggability
*
* A client application can choose not to use the default parser mechanism
* supplied with their JAXB provider. Any SAX 2.0 compliant parser can be
* substituted for the JAXB provider's default mechanism. To do so, the
* client application must properly configure a SAXSource containing
* an XMLReader implemented by the SAX 2.0 parser provider. If the
* XMLReader has an org.xml.sax.ErrorHandler registered
* on it, it will be replaced by the JAXB Provider so that validation errors
* can be reported via the ValidationEventHandler mechanism of
* JAXB. If the SAXSource does not contain an XMLReader,
* then the JAXB provider's default parser mechanism will be used.
*
* This parser replacement mechanism can also be used to replace the JAXB
* provider's unmarshal-time validation engine. The client application
* must properly configure their SAX 2.0 compliant parser to perform
* validation (as shown in the example above). Any SAXParserExceptions
* encountered by the parser during the unmarshal operation will be
* processed by the JAXB provider and converted into JAXB
* ValidationEvent objects which will be reported back to the
* client via the ValidationEventHandler registered with the
* Unmarshaller. Note: specifying a substitute validating
* SAX 2.0 parser for unmarshalling does not necessarily replace the
* validation engine used by the JAXB provider for performing on-demand
* validation.
*
* The only way for a client application to specify an alternate parser
* mechanism to be used during unmarshal is via the
* unmarshal(SAXSource) API. All other forms of the unmarshal
* method (File, URL, Node, etc) will use the JAXB provider's default
* parser and validator mechanisms.
*
* @param source the XML Source to unmarshal XML data from (providers are
* only required to support SAXSource, DOMSource, and StreamSource)
* @return the newly created root object of the java content tree
*
* @throws JAXBException
* If any unexpected errors occur while unmarshalling
* @throws UnmarshalException
* If the {@link ValidationEventHandler ValidationEventHandler}
* returns false from its handleEvent method or the
* Unmarshaller is unable to perform the XML to Java
* binding. See Unmarshalling XML Data
* @throws IllegalArgumentException
* If the Source parameter is null
*/
public Object unmarshal( javax.xml.transform.Source source )
throws JAXBException;
/**
* Get an unmarshaller handler object that can be used as a component in
* an XML pipeline.
*
*
* The JAXB Provider can return the same handler object for multiple
* invocations of this method. In other words, this method does not
* necessarily create a new instance of UnmarshallerHandler. If the
* application needs to use more than one UnmarshallerHandler, it
* should create more than one Unmarshaller.
*
* @return the unmarshaller handler object
* @see UnmarshallerHandler
*/
public UnmarshallerHandler getUnmarshallerHandler();
/**
* Specifies whether or not the default validation mechanism of the
* Unmarshaller should validate during unmarshal operations.
* By default, the Unmarshaller does not validate.
*
* This method may only be invoked before or after calling one of the
* unmarshal methods.
*
* This method only controls the JAXB Provider's default unmarshal-time
* validation mechanism - it has no impact on clients that specify their
* own validating SAX 2.0 compliant parser. Clients that specify their
* own unmarshal-time validation mechanism may wish to turn off the JAXB
* Provider's default validation mechanism via this API to avoid "double
* validation".
*
* @param validating true if the Unmarshaller should validate during
* unmarshal, false otherwise
* @throws JAXBException if an error occurred while enabling or disabling
validation at unmarshal time
*/
public void setValidating( boolean validating )
throws JAXBException;
/**
* Indicates whether or not the Unmarshaller is configured to
* validate during unmarshal operations.
*
*
* This API returns the state of the JAXB Provider's default unmarshal-time
* validation mechanism.
*
* @return true if the Unmarshaller is configured to validate during
* unmarshal operations, false otherwise
* @throws JAXBException if an error occurs while retrieving the validating
* flag
*/
public boolean isValidating()
throws JAXBException;
/**
* Allow an application to register a ValidationEventHandler.
*
* The ValidationEventHandler will be called by the JAXB Provider
* if any validation errors are encountered during calls to any of the
* unmarshal methods. If the client application does not register a
* ValidationEventHandler before invoking the unmarshal methods,
* then ValidationEvents will be handled by the default event
* handler which will terminate the unmarshal operation after the first
* error or fatal error is encountered.
*
* Calling this method with a null parameter will cause the Unmarshaller
* to revert back to the default vefault event handler.
*
* @param handler the validation event handler
* @throws JAXBException if an error was encountered while setting the
* event handler
*/
public void setEventHandler( ValidationEventHandler handler )
throws JAXBException;
/**
* Return the current event handler or the default event handler if one
* hasn't been set.
*
* @return the current ValidationEventHandler or the default event handler
* if it hasn't been set
* @throws JAXBException if an error was encountered while getting the
* current event handler
*/
public ValidationEventHandler getEventHandler()
throws JAXBException;
/**
* Set the particular property in the underlying implementation of
* Unarshaller. This method can only be used to set one of
* the standard JAXB defined properties above or a provider specific
* property. Attempting to set an undefined property will result in
* a PropertyException being thrown. See
* Supported Properties.
*
* @param name the name of the property to be set. This value can either
* be specified using one of the constant fields or a user
* supplied string.
* @param value the value of the property to be set
*
* @throws PropertyException when there is an error processing the given
* property or value
* @throws IllegalArgumentException
* If the name parameter is null
*/
public void setProperty( String name, Object value )
throws PropertyException;
/**
* Get the particular property in the underlying implementation of
* Unmarshaller. This method can only be used to get one of
* the standard JAXB defined properties above or a provider specific
* property. Attempting to get an undefined property will result in
* a PropertyException being thrown. See
* Supported Properties.
*
* @param name the name of the property to retrieve
* @return the value of the requested property
*
* @throws PropertyException
* when there is an error retrieving the given property or value
* property name
* @throws IllegalArgumentException
* If the name parameter is null
*/
public Object getProperty( String name ) throws PropertyException;
}