public abstract Class JAXBContext

A client application normally obtains new instances of this class using one of these two styles for newInstance methods, although there are other specialized forms of the method available:

• JAXBContext.newInstance( "com.acme.foo:com.acme.bar" )
  The JAXBContext instance is initialized from a list of colon separated Java package names. Each java package contains JAXB mapped classes, schema-derived classes and/or user annotated classes. Additionally, the java package may contain JAXB package annotations that must be processed. (see JLS, Section 7.4.1 "Named Packages").
• JAXBContext.newInstance( com.acme.foo.Foo.class )
  The JAXBContext instance is initialized with class(es) passed as parameter(s) and classes that are statically reachable from these class(es). See newInstance(Class...) for details.

The following JAXB 1.0 requirement is only required for schema to java interface/implementation binding. It does not apply to JAXB annotated classes. 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 APIs.

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 APIs.

In addition, the provider must call the 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 Unmarshaller class provides the client application the ability to convert XML data into a tree of Java content objects. The unmarshal method allows for any global XML element declared in the schema to be unmarshalled as the root of an instance document. Additionally, the unmarshal method allows for an unrecognized root element that has an xsi:type attribute's value that references a type definition declared in the schema to be unmarshalled as the root of an instance document. The JAXBContext object allows the merging of global elements and type definitions 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 must 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. For all JAXB-annotated value classes, an application can create content using constructors. For schema-derived interface/implementation classes and for the creation of elements that are not bound to a JAXB-annotated class, an 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 is 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.

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 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. Client applications have control over the output encoding as well as whether or not to marshal the XML data as a complete document or as a fragment.

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

Validation has been changed significantly since JAXB 1.0. The Validator class has been deprecated and made optional. This means that you are advised not to use this class and, in fact, it may not even be available depending on your JAXB provider. JAXB 1.0 client applications that rely on Validator will still work properly when deployed with the JAXB 1.0 runtime system. In JAXB 2.0, the Unmarshaller has included convenince methods that expose the JAXP 1.3 javax.xml.validation framework. Please refer to the Unmarshaller#setSchema(javax.xml.validation.Schema) API for more information.

JAXB Runtime Binding Framework Compatibility

The following JAXB 1.0 restriction only applies to binding schema to interfaces/implementation classes. Since this binding does not require 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.

Discovery of JAXB implementation

To create an instance of JAXBContext, one of JAXBContext.newInstance(...) methods is invoked. After JAX-B implementation is discovered, call is delegated to appropriate provider's method createContext(...) passing parameters from the original call.

JAX-B implementation discovery happens each time JAXBContext.newInstance is invoked. If there is no user specific configuration provided, default JAX-B provider must be returned.

Implementation discovery consists of following steps:

1. Packages/classes explicitly passed in to the newInstance method are processed in the order they are specified, until jaxb.properties file is looked up in its package, by using the associated classloader — this is the owner class loader for a Class argument, and for a package the specified ClassLoader.

   If such a resource is discovered, it is loaded as a property file, and the value of the JAXB_CONTEXT_FACTORY key will be assumed to be the provider factory class. If no value found, "javax.xml.bind.context.factory" is used as a key for backwards compatibility reasons. This class is then loaded by the associated class loader discussed above.

   This phase of the look up allows some packages to force the use of a certain JAXB implementation. (For example, perhaps the schema compiler has generated some vendor extension in the code.)

   This configuration method is deprecated.

2. If the system property JAXB_CONTEXT_FACTORY exists, then its value is assumed to be the provider factory class. If no such property exists, properties "javax.xml.bind.context.factory" and "javax.xml.bind.JAXBContext" are checked too (in this order), for backwards compatibility reasons. This phase of the look up enables per-JVM override of the JAXB implementation.
3. Provider of javax.xml.bind.JAXBContextFactory is loaded using the service-provider loading facilities, defined by the java.util.ServiceLoader class, to attempt to locate and load an implementation of the service using the default loading mechanism: the service-provider loading facility will use the current thread's context class loader to attempt to load the context factory. If the context class loader is null, the system class loader will be used.
   In case of service configuration error a javax.xml.bind.JAXBException will be thrown.
4. Look for resource /META-INF/services/javax.xml.bind.JAXBContext using provided class loader. Methods without class loader parameter use Thread.currentThread().getContextClassLoader(). If such a resource exists, its content is assumed to be the provider factory class. This configuration method is deprecated.
5. Finally, if all the steps above fail, then the rest of the look up is unspecified. That said, the recommended behavior is to simply look for some hard-coded platform default JAXB implementation. This phase of the look up is so that Java SE can have its own JAXB implementation as the last resort.

Once the provider factory class is discovered, context creation is delegated to one of its createContext(...) methods. For backward compatibility reasons, there are two ways how to implement provider factory class:

1. the class is implementation of javax.xml.bind.JAXBContextFactory. It must also implement no-arg constructor. If discovered in other step then 3, new instance using no-arg constructor is created first. After that, appropriate instance method is invoked on this instance.
2. the class is not implementation of interface above and then it is mandated to implement the following static method signatures:

   
   public static JAXBContext createContext(
                                        String contextPath,
                                        ClassLoader classLoader,
                                        Map<String,Object> properties ) throws JAXBException
   
   public static JAXBContext createContext(
                                        Class[] classes,
                                        Map<String,Object> properties ) throws JAXBException
   

   In this scenario, appropriate static method is used instead of instance method. This approach is incompatible with java.util.ServiceLoader so it can't be used with step 3.

There is no difference in behavior of given method createContext(...) regardless of whether it uses approach 1 (JAXBContextFactory) or 2 (no interface, static methods).