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:
- it must contain ObjectFactory.class
- 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 JAXBContext.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.
Returns:
a new instance of a JAXBContext
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.
Throws:
- JAXBException - if an error was encountered while creating the
JAXBContext such as
- failure to locate either ObjectFactory.class or jaxb.index in the packages
- an ambiguity among global elements contained in the contextPath
- failure to locate a value for the context factory provider property
- mixing schema derived packages from different providers on the same contextPath