javax.xml.bind.JAXBContext 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 JAXBContext class provides the client's entry point to the
* JAXB API. It provides an abstraction for managing the XML/Java binding
* information necessary to implement the JAXB binding framework operations:
* unmarshal, marshal and validate. A client application obtains new instances
* of this class via the {@link #newInstance(String) newInstance(contextPath)}
* method.
*
*
* JAXBContext jc = JAXBContext.newInstance( "com.acme.foo:com.acme.bar" );
*
*
*
* The contextPath contains a list of Java package names that contain
* schema derived interfaces. The value of this parameter initializes the
* JAXBContext object so that it is capable of managing the
* schema derived interfaces.
*
*
*
* SPEC REQUIREMENT: the provider must supply an implementation
* class containing a method with the following signature:
*
*
* public static JAXBContext createContext( String contextPath, ClassLoader classLoader )
* throws JAXBException;
*
*
*
* JAXB Providers must generate a jaxb.properties file in each package
* containing schema derived classes. The property file must contain a
* property named javax.xml.bind.context.factory whose value is
* the name of the class that implements the createContext API.
*
*
* The class supplied by the provider does not have to be assignable to
* javax.xml.bind.JAXBContext, it simply has to provide a class that
* implements the createContext API.
*
*
* In addition, the provider must call the
* {@link DatatypeConverter#setDatatypeConverter(DatatypeConverterInterface)
* DatatypeConverter.setDatatypeConverter} api prior to any client
* invocations of the marshal and unmarshal methods. This is necessary to
* configure the datatype converter that will be used during these operations.
*
*
*
* Unmarshalling
*
*
* The {@link Unmarshaller} class provides the client application the ability
* to convert XML data into a tree of Java content objects.
* The unmarshal method for a schema (within a namespace) allows for
* any global XML element declared in the schema to be unmarshalled as
* the root of an instance document. The JAXBContext object
* allows the merging of global elements across a set of schemas (listed
* in the contextPath). Since each schema in the schema set can belong
* to distinct namespaces, the unification of schemas to an unmarshalling
* context should be namespace independent. This means that a client
* application is able to unmarshal XML documents that are instances of
* any of the schemas listed in the contextPath. For example:
*
*
* JAXBContext jc = JAXBContext.newInstance( "com.acme.foo:com.acme.bar" );
* Unmarshaller u = jc.createUnmarshaller();
* FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) ); // ok
* BarObject barObj = (BarObject)u.unmarshal( new File( "bar.xml" ) ); // ok
* BazObject bazObj = (BazObject)u.unmarshal( new File( "baz.xml" ) ); // error, "com.acme.baz" not in contextPath
*
*
*
* The client application may also generate Java content trees explicitly rather
* than unmarshalling existing XML data. To do so, the application needs to
* have access and knowledge about each of the schema derived
* ObjectFactory classes that exist in each of java packages contained
* in the contextPath. For each schema derived java class, there will
* be a static factory method that produces objects of that type. For example,
* assume that after compiling a schema, you have a package com.acme.foo
* that contains a schema derived interface named PurchaseOrder. In
* order to create objects of that type, the client application would use the
* factory method like this:
*
*
* com.acme.foo.PurchaseOrder po =
* com.acme.foo.ObjectFactory.createPurchaseOrder();
*
*
*
* Once the client application has an instance of the the schema derived object,
* it can use the mutator methods to set content on it.
*
*
* For more information on the generated ObjectFactory classes, see
* Section 4.2 Java Package of the specification.
*
*
* SPEC REQUIREMENT: the provider must generate a class in each
* package that contains all of the necessary object factory methods for that
* package named ObjectFactory as well as the static
* newInstance( javaContentInterface ) method
*
*
*
* Marshalling
*
*
* The {@link Marshaller} class provides the client application the ability
* to convert a Java content tree back into XML data. There is no difference
* between marshalling a content tree that is created manually using the factory
* methods and marshalling a content tree that is the result an unmarshal
* operation. Clients can marshal a java content tree back to XML data
* to a java.io.OutputStream or a java.io.Writer. The
* marshalling process can alternatively produce SAX2 event streams to a
* registered ContentHandler or produce a DOM Node object.
*
*
*
* Here is a simple example that unmarshals an XML document and then marshals
* it back out:
*
*
* JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
*
* // unmarshal from foo.xml
* Unmarshaller u = jc.createUnmarshaller();
* FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) );
*
* // marshal to System.out
* Marshaller m = jc.createMarshaller();
* m.marshal( fooObj, System.out );
*
*
*
*
* Validation
*
*
* There are three varieties of validation available to JAXB client applications:
*
*
* - Unmarshal-time Validation
* - Validation performed on the XML data as it is being unmarshalled into
* a Java content tree
* - On-Demand Validation
* - Validation performed on the Java content tree in memory
* - Fail-Fast Validation
* - Validation of Java property constraints at runtime when client
* applications invoke the setter methods of the generated classes
*
*
*
*
* See: Validator javadocs for a
* more detailed definition of the different type of validation.
*
*
* Although unmarshal-time validation and on-demand validation are very similar,
* they are completely orthogonal operations with no dependencies on each other.
* Client applications are free to use one, both, or neither types of validation.
*
*
* Validation errors and warnings encountered during the unmarshal and validate
* operations are reported to the client application via a callback error handler
* interface ({@link ValidationEventHandler ValidationEventHandler}) that receives
* {@link ValidationEvent ValidationEvent} objects. The ValidationEvent
* objects contain information about the error or warning encountered. JAXB
* allows a few diffent methods of handling validation events which are described
* in more detail in the
* Validator javadoc.
*
*
*
* JAXB Runtime Binding Framework Compatibility
*
* Since the JAXB Specification does not define a common runtime system, a JAXB
* client application must not attempt to mix runtime objects (JAXBContext,
* Marshaller, etc. ) from different providers. This does not
* mean that the client application isn't portable, it simply means that a
* client has to use a runtime system provided by the same provider that was
* used to compile the schema.
*
*
* @author - Ryan Shoemaker, Sun Microsystems, Inc.
- Kohsuke Kawaguchi, Sun Microsystems, Inc.
- Joe Fialli, Sun Microsystems, Inc.
* @version $Revision: 1.28 $ $Date: 2003/01/23 22:08:06 $
* @see Marshaller
* @see Unmarshaller
* @see Validator
* @since JAXB1.0
*/
public abstract class JAXBContext {
/**
* The name of the property that contains the name of the class capable
* of creating new JAXBContext objects.
*/
public static final String JAXB_CONTEXT_FACTORY =
"javax.xml.bind.context.factory";
protected JAXBContext() {
}
/**
*
* Obtain a new instance of a JAXBContext class.
*
*
* This is a convenience method for the
* {@link #newInstance(String,ClassLoader) newInstance} method. It uses
* the context class loader of the current thread. To specify the use of
* a different class loader, either set it via the
* Thread.setContextClassLoader() api or use the
* {@link #newInstance(String,ClassLoader) newInstance} method.
*/
public static JAXBContext newInstance( String contextPath )
throws JAXBException {
//return newInstance( contextPath, JAXBContext.class.getClassLoader() );
return newInstance( contextPath, Thread.currentThread().getContextClassLoader() );
}
/**
*
* Obtain a new instance of a JAXBContext class.
*
*
* The client application must supply a context path which is a list of
* colon (':', \u005Cu003A) separated java package names that contain schema
* derived classes.
*
* The JAXB provider will ensure that each package on the context path
* has a jaxb.properties file which contains a value for the
* javax.xml.bind.context.factory property and that all values
* resolve to the same provider.
*
*
* If there are any global XML element name collisions across the various
* packages listed on the contextPath, a JAXBException
* will be thrown. Mixing generated classes from multiple JAXB Providers
* in the same context path will also result in a JAXBException
* being thrown.
*
* @param contextPath list of java package names that contain schema
* derived classes
* @param classLoader
* This class loader will be used to locate the implementation
* classes.
*
* @return a new instance of a JAXBContext
* @throws JAXBException if an error was encountered while creating the
* JAXBContext, such as an ambiguity among
* global elements contained in the contextPath,
* failure to locate a value for the context factory
* property, or mixing schema derived packages from
* different providers on the same contextPath.
*/
public static JAXBContext newInstance( String contextPath, ClassLoader classLoader )
throws JAXBException {
return (JAXBContext) ContextFinder.find(
/* The default property name according to the JAXB spec */
JAXB_CONTEXT_FACTORY,
/* the context path supplied by the client app */
contextPath,
/* class loader to be used */
classLoader );
}
/**
* Create an Unmarshaller object that can be used to convert XML
* data into a java content tree.
*
* @return an Unmarshaller object
*
* @throws JAXBException if an error was encountered while creating the
* Unmarshaller object
*/
public abstract Unmarshaller createUnmarshaller() throws JAXBException;
/**
* Create a Marshaller object that can be used to convert a
* java content tree into XML data.
*
* @return a Marshaller object
*
* @throws JAXBException if an error was encountered while creating the
* Marshaller object
*/
public abstract Marshaller createMarshaller() throws JAXBException;
/**
* Create a Validator object that can be used to validate a
* java content tree against its source schema.
*
* @return a Validator object
*
* @throws JAXBException if an error was encountered while creating the
* Validator object
*/
public abstract Validator createValidator() throws JAXBException;
}