Package jakarta.xml.bind

Class JAXBContext

  • public abstract class JAXBContext
extends Object
    The JAXBContext class provides the client's entry point to the Jakarta XML Binding API. It provides an abstraction for managing the XML/Java binding information necessary to implement the Jakarta XML Binding binding framework operations: unmarshal, marshal and validate.

    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 Jakarta XML Binding mapped classes, schema-derived classes and/or user annotated classes. Additionally, the java package may contain Jakarta XML Binding 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 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 Jakarta XML Binding-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 Jakarta XML Binding-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

    In Jakarta XML Binding, the Unmarshaller has included convenience methods that expose the JAXP javax.xml.validation framework. Please refer to the Unmarshaller.setSchema(javax.xml.validation.Schema) API for more information.

    Jakarta XML Binding Runtime 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 Jakarta XML Binding 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 Jakarta XML Binding 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. If the system property JAXB_CONTEXT_FACTORY exists, then its value is assumed to be the provider factory class. This phase of the look up enables per-JVM override of the Jakarta XML Binding implementation.
    2. If the property JAXB_CONTEXT_FACTORY exists in the Map<String, ?> passed to newInstance(Class[], Map) or to newInstance(String, ClassLoader, Map), then its value is assumed to be the fully qualified provider factory class name. This phase of the look up enables context sensitive selection of the Jakarta XML Binding implementation.
    3. Provider of JAXBContextFactory is loaded using the service-provider loading facilities, defined by the 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 JAXBException will be thrown.
    4. 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 Jakarta XML Binding implementation. This phase of the look up is so that the environment can have its own Jakarta XML Binding implementation as the last resort.

    Once the provider factory class is discovered, context creation is delegated to one of its createContext(...) methods.

    Since:
    1.6, JAXB 1.0
    Author:
    • Ryan Shoemaker, Sun Microsystems, Inc.
    • Kohsuke Kawaguchi, Sun Microsystems, Inc.
    • Joe Fialli, Sun Microsystems, Inc.
    See Also:
    Marshaller, Unmarshaller, S 7.4.1 "Named Packages" in Java Language Specification

    • Field Detail

      • JAXB_CONTEXT_FACTORY

        public static final String JAXB_CONTEXT_FACTORY
        The name of the property that contains the name of the class capable of creating new JAXBContext objects.
        See Also:
        Constant Field Values

    • Constructor Detail

      • JAXBContext

        protected JAXBContext()

    • Method Detail

      • newInstance

        public static JAXBContext newInstance​(String contextPath)
                               throws JAXBException
        Create a new instance of a JAXBContext class.

        This is a convenience method to invoke the newInstance(String,ClassLoader) method with the context class loader of the current thread.

        Parameters:
        contextPath - the context path
        Returns:
        the new instance of a JAXBContext class
        Throws:
        JAXBException - if an error was encountered while creating the JAXBContext such as
        1. failure to locate either ObjectFactory.class or jaxb.index in the packages
        2. an ambiguity among global elements contained in the contextPath
        3. failure to locate a value for the context factory provider property
        4. mixing schema derived packages from different providers on the same contextPath
        5. packages are not open to jakarta.xml.bind module

      • newInstance

        public static JAXBContext newInstance​(String contextPath,
                                      ClassLoader classLoader)
                               throws JAXBException
        Create a new instance of a JAXBContext class.

        The client application must supply a context path which is a list of colon (':', \u003A) separated java package names that contain schema-derived classes and/or fully qualified Jakarta XML Binding-annotated classes. Schema-derived code is registered with the JAXBContext by the ObjectFactory.class generated per package. Alternatively than being listed in the context path, programmer annotated Jakarta XML Binding mapped classes can be listed in a jaxb.index resource file, format described below. Note that a java package can contain both schema-derived classes and user annotated Jakarta XML Binding classes. Additionally, the java package may contain Jakarta XML Binding package annotations that must be processed. (see JLS, Section 7.4.1 "Named Packages").

        Every package listed on the contextPath must meet one or both of the following conditions otherwise a JAXBException will be thrown:

        1. it must contain ObjectFactory.class
        2. it must contain jaxb.index

        Format for jaxb.index

        The file contains a newline-separated list of class names. Space and tab characters, as well as blank lines, are ignored. The comment character is '#' (0x23); on each line all characters following the first comment character are ignored. The file must be encoded in UTF-8. Classes that are reachable, as defined in newInstance(Class...), from the listed classes are also registered with JAXBContext.

        Constraints on class name occuring in a jaxb.index file are:

        • Must not end with ".class".
        • Class names are resolved relative to package containing jaxb.index file. Only classes occuring directly in package containing jaxb.index file are allowed.
        • Fully qualified class names are not allowed. A qualified class name,relative to current package, is only allowed to specify a nested or inner class.

        If there are any global XML element name collisions across the various packages listed on the contextPath, a JAXBException will be thrown.

        Mixing generated interface/impl bindings from multiple Jakarta XML Binding Providers in the same context path may result in a JAXBException being thrown.

        The steps involved in discovering the Jakarta XML Binding implementation is discussed in the class javadoc.

        Parameters:
        contextPath - List of java package names that contain schema derived class and/or java to schema (Jakarta XML Binding-annotated) mapped classes. Packages in contextPath that are in named modules must be open to at least the jakarta.xml.bind module.
        classLoader - This class loader will be used to locate the implementation classes.
        Returns:
        a new instance of a JAXBContext
        Throws:
        JAXBException - if an error was encountered while creating the JAXBContext such as
        1. failure to locate either ObjectFactory.class or jaxb.index in the packages
        2. an ambiguity among global elements contained in the contextPath
        3. failure to locate a value for the context factory provider property
        4. mixing schema derived packages from different providers on the same contextPath
        5. packages are not open to jakarta.xml.bind module

      • newInstance

        public static JAXBContext newInstance​(String contextPath,
                                      ClassLoader classLoader,
                                      Map<String,​?> properties)
                               throws JAXBException
        Create a new instance of a JAXBContext class.

        This is mostly the same as newInstance(String, ClassLoader), but this version allows you to pass in provider-specific properties to configure the instantiation of JAXBContext.

        The interpretation of properties is up to implementations. Implementations must throw JAXBException if it finds properties that it doesn't understand.

        Parameters:
        contextPath - List of java package names that contain schema derived class and/or java to schema (Jakarta XML Binding-annotated) mapped classes. Packages in contextPath that are in named modules must be open to at least the jakarta.xml.bind module.
        classLoader - This class loader will be used to locate the implementation classes.
        properties - provider-specific or provider selection-specific properties. Can be null, which means the same thing as passing in an empty map.
        Returns:
        a new instance of a JAXBContext
        Throws:
        JAXBException - if an error was encountered while creating the JAXBContext such as
        1. failure to locate either ObjectFactory.class or jaxb.index in the packages
        2. an ambiguity among global elements contained in the contextPath
        3. failure to locate a value for the context factory provider property
        4. mixing schema derived packages from different providers on the same contextPath
        5. packages are not open to jakarta.xml.bind module
        Since:
        1.6, JAXB 2.0

      • newInstance

        public static JAXBContext newInstance​(Class<?>... classesToBeBound)
                               throws JAXBException
        Create a new instance of a JAXBContext class.

        The client application must supply a list of classes that the new context object needs to recognize. Not only the new context will recognize all the classes specified, but it will also recognize any classes that are directly/indirectly referenced statically from the specified classes. Subclasses of referenced classes nor @XmlTransient referenced classes are not registered with JAXBContext. For example, in the following Java code, if you do newInstance(Foo.class), the newly created JAXBContext will recognize both Foo and Bar, but not Zot or FooBar: 

         class Foo {
      @XmlTransient FooBar c;
      Bar b;
 }
 class Bar { int x; }
 class Zot extends Bar { int y; }
 class FooBar { }
        Therefore, a typical client application only needs to specify the top-level classes, but it needs to be careful.

        Note that for each java package registered with JAXBContext, when the optional package annotations exist, they must be processed. (see JLS, Section 7.4.1 "Named Packages").

        The steps involved in discovering the Jakarta XML Binding implementation is discussed in the class javadoc.

        Parameters:
        classesToBeBound - List of java classes to be recognized by the new JAXBContext. Classes in classesToBeBound that are in named modules must be in a package that is open to at least the jakarta.xml.bind module. Can be empty, in which case a JAXBContext that only knows about spec-defined classes will be returned.
        Returns:
        A new instance of a JAXBContext.
        Throws:
        JAXBException - if an error was encountered while creating the JAXBContext, such as (but not limited to):
        1. No Jakarta XML Binding implementation was discovered
        2. Classes use Jakarta XML Binding annotations incorrectly
        3. Classes have colliding annotations (i.e., two classes with the same type name)
        4. The Jakarta XML Binding implementation was unable to locate provider-specific out-of-band information (such as additional files generated at the development time.)
        5. classesToBeBound are not open to jakarta.xml.bind module
        IllegalArgumentException - if the parameter contains null (i.e., newInstance(null);)
        Since:
        1.6, JAXB 2.0

      • newInstance

        public static JAXBContext newInstance​(Class<?>[] classesToBeBound,
                                      Map<String,​?> properties)
                               throws JAXBException
        Create a new instance of a JAXBContext class.

        An overloading of newInstance(Class...) to configure 'properties' for this instantiation of JAXBContext.

        The interpretation of properties is up to implementations. Implementations must throw JAXBException if it finds properties that it doesn't understand.

        Parameters:
        classesToBeBound - List of java classes to be recognized by the new JAXBContext. Classes in classesToBeBound that are in named modules must be in a package that is open to at least the jakarta.xml.bind module. Can be empty, in which case a JAXBContext that only knows about spec-defined classes will be returned.
        properties - provider-specific or provider selection-specific properties. Can be null, which means the same thing as passing in an empty map.
        Returns:
        A new instance of a JAXBContext.
        Throws:
        JAXBException - if an error was encountered while creating the JAXBContext, such as (but not limited to):
        1. No Jakarta XML Binding implementation was discovered
        2. Classes use Jakarta XML Binding annotations incorrectly
        3. Classes have colliding annotations (i.e., two classes with the same type name)
        4. The Jakarta XML Binding implementation was unable to locate provider-specific out-of-band information (such as additional files generated at the development time.)
        5. classesToBeBound are not open to jakarta.xml.bind module
        IllegalArgumentException - if the parameter contains null (i.e., newInstance(null,someMap);)
        Since:
        1.6, JAXB 2.0

      • createUnmarshaller

        public abstract Unmarshaller createUnmarshaller()
                                         throws JAXBException
        Create an Unmarshaller object that can be used to convert XML data into a java content tree.
        Returns:
        an Unmarshaller object
        Throws:
        JAXBException - if an error was encountered while creating the Unmarshaller object

      • createMarshaller

        public abstract Marshaller createMarshaller()
                                     throws JAXBException
        Create a Marshaller object that can be used to convert a java content tree into XML data.
        Returns:
        a Marshaller object
        Throws:
        JAXBException - if an error was encountered while creating the Marshaller object

      • createBinder

        public <T> Binder<T> createBinder​(Class<T> domType)
        Creates a Binder object that can be used for associative/in-place unmarshalling/marshalling.
        Type Parameters:
        T - the DOM API type
        Parameters:
        domType - select the DOM API to use by passing in its DOM Node class
        Returns:
        always a new valid Binder object.
        Throws:
        UnsupportedOperationException - if DOM API corresponding to domType is not supported by the implementation.
        Since:
        1.6, JAXB 2.0

      • createBinder

        public Binder<Node> createBinder()
        Creates a Binder for W3C DOM.
        Returns:
        always a new valid Binder object.
        Since:
        1.6, JAXB 2.0

      • createJAXBIntrospector

        public JAXBIntrospector createJAXBIntrospector()
        Creates a JAXBIntrospector object that can be used to introspect Jakarta XML Binding objects.
        Returns:
        always return a non-null valid JAXBIntrospector object.
        Throws:
        UnsupportedOperationException - Calling this method on JAXB 1.0 implementations will throw an UnsupportedOperationException.
        Since:
        1.6, JAXB 2.0