Please note that the specifications and other information contained herein are not final and are subject to change. The information is being made available to you solely for purpose of evaluation.
Java™ Platform
Standard Ed. 7

DRAFT ea-b138
javax.xml.bind

Class JAXBContext

    • 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

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

        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
      • newInstance

        public static JAXBContext newInstance(String contextPath,
                              ClassLoader classLoader)
                                       throws JAXBException

        Obtain 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 JAXB-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 JAXB 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 JAXB classes. Additionally, the java package may contain JAXB package annotations that must be processed. (see JLS 3rd Edition, Section 7.4.1. "Package Annotations").

        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.

        To maintain compatibility with JAXB 1.0 schema to java interface/implementation binding, enabled by schema customization , 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. This requirement does not apply to JAXB annotated classes.

        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 JAXB Providers in the same context path may result in a JAXBException being thrown.

        The steps involved in discovering the JAXB implementation is discussed in the class javadoc.

        Parameters:
        contextPath - list of java package names that contain schema derived class and/or java to schema (JAXB-annotated) mapped classes
        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
      • newInstance

        public static JAXBContext newInstance(String contextPath,
                              ClassLoader classLoader,
                              Map<String,?> properties)
                                       throws JAXBException

        Obtain 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 should throw JAXBException if it finds properties that it doesn't understand.

        Parameters:
        contextPath - list of java package names that contain schema derived classes
        classLoader - This class loader will be used to locate the implementation classes.
        properties - provider-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
        Since:
        JAXB2.0
      • newInstance

        public static JAXBContext newInstance(Class... classesToBeBound)
                                       throws JAXBException

        Obtain 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 3rd Edition, Section 7.4.1. "Package Annotations").

        The steps involved in discovering the JAXB implementation is discussed in the class javadoc.

        Parameters:
        classesToBeBound - list of java classes to be recognized by the new JAXBContext. 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. Always non-null valid object.
        Throws:
        JAXBException - if an error was encountered while creating the JAXBContext, such as (but not limited to):
        1. No JAXB implementation was discovered
        2. Classes use JAXB annotations incorrectly
        3. Classes have colliding annotations (i.e., two classes with the same type name)
        4. The JAXB implementation was unable to locate provider-specific out-of-band information (such as additional files generated at the development time.)
        IllegalArgumentException - if the parameter contains null (i.e., newInstance(null);)
        Since:
        JAXB2.0
      • newInstance

        public static JAXBContext newInstance(Class[] classesToBeBound,
                              Map<String,?> properties)
                                       throws JAXBException

        Obtain 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 should throw JAXBException if it finds properties that it doesn't understand.

        Parameters:
        classesToBeBound - list of java classes to be recognized by the new JAXBContext. Can be empty, in which case a JAXBContext that only knows about spec-defined classes will be returned.
        properties - provider-specific properties. Can be null, which means the same thing as passing in an empty map.
        Returns:
        A new instance of a JAXBContext. Always non-null valid object.
        Throws:
        JAXBException - if an error was encountered while creating the JAXBContext, such as (but not limited to):
        1. No JAXB implementation was discovered
        2. Classes use JAXB annotations incorrectly
        3. Classes have colliding annotations (i.e., two classes with the same type name)
        4. The JAXB implementation was unable to locate provider-specific out-of-band information (such as additional files generated at the development time.)
        IllegalArgumentException - if the parameter contains null (i.e., newInstance(null,someMap);)
        Since:
        JAXB2.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
      • createValidator

        public abstract Validator createValidator()
                                           throws JAXBException
        Deprecated. since JAXB2.0
        Validator has been made optional and deprecated in JAXB 2.0. Please refer to the javadoc for Validator for more detail.

        Create a Validator object that can be used to validate a java content tree against its source schema.

        Returns:
        a Validator object
        Throws:
        JAXBException - if an error was encountered while creating the Validator object
      • createBinder

        public <T> Binder<T> createBinder(Class<T> domType)
        Creates a Binder object that can be used for associative/in-place unmarshalling/marshalling.
        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:
        JAXB2.0
      • createBinder

        public Binder<Node> createBinder()
        Creates a Binder for W3C DOM.
        Returns:
        always a new valid Binder object.
        Since:
        JAXB2.0
      • createJAXBIntrospector

        public JAXBIntrospector createJAXBIntrospector()
        Creates a JAXBIntrospector object that can be used to introspect JAXB 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:
        JAXB2.0
Java™ Platform
Standard Ed. 7

DRAFT ea-b138

Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2011, Oracle and/or its affiliates. All rights reserved.

DRAFT ea-b138