Generated by
JDiff

javax.xml.bind Documentation Differences

This file contains all the changes in documentation in the package javax.xml.bind as colored differences. Deletions are shown like this, and additions are shown like this.
If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.
Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

Class DatatypeConverter

The javaType binding declaration can be used to customize the binding of an XML schema datatype to a Java datatype. Customizations can involve writing a parse and print method for parsing and printing lexical representations of a XML schema datatype respectively. However, writing parse and print methods requires knowledge of the lexical representations ( XML Schema Part2: Datatypes specification ) and hence may be difficult to write.

This class makes it easier to write parse and print methods. It defines static parse and print methods that provide access to a JAXB provider's implementation of parse and print methods. These methods are invoked by custom parse and print methods. For example, the binding of xsd:dateTime to a long can be customized using parse and print methods as follows:

    // Customized parse method 
    public long myParseCal( String dateTimeString ) {
        java.util.Calendar cal = DatatypeConverter.parseDateTime(dateTimeString);
        long longval = convert_calendar_to_long(cal); //application specific
        return longval;
    }
     
    // Customized print method
    public String myPrintCal( Long longval ) {
        java.util.Calendar cal = convert_long_to_calendar(longval) ; //application specific
        String dateTimeString = DatatypeConverter.printDateTime(cal);
        return dateTimeString;
    }
    

There is a static parse and print method corresponding to each parse and print method respectively in the DatatypeConverterInterface.

The static methods defined in the class can also be used to specify a parse or a print method in a javaType binding declaration.

JAXB Providers are required to call the setDatatypeConverter api at some point before the first marshal or unmarshal operation (perhaps during the call to JAXBContext.newInstance). This step is necessary to configure the converter that should be used to perform the print and parse functionality.

A print method for a XML schema datatype can output any lexical representation that is valid with respect to the XML schema datatype. If an error is encountered during conversion, then an IllegalArgumentException, or a subclass of IllegalArgumentException must be thrown by the method.

@author @version $Revision: 1.4.2.1 $ @see DatatypeConverterInterface @see ParseConversionEvent @see PrintConversionEvent @since JAXB1.0
Class DatatypeConverter, void setDatatypeConverter(DatatypeConverterInterface)

This method is for JAXB provider use only.

JAXB Providers are required to call this method at some point before allowing any of the JAXB client marshal or unmarshal operations to occur. This is necessary to configure the datatype converter that should be used to perform the print and parse conversions.

Calling this api repeatedly will have no effect - the DatatypeConverterInterface instance passed into the first invocation is the one that will be used from then on. @param converter an instance of a class that implements the DatatypeConverterInterface class - this parameter must not be null. @throws IllegalArgumentException if the parameter is nullnull @throws SecurityException If the SecurityManager in charge denies the access to set the datatype converter. @see JAXBPermission


Class JAXBContext

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 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:

SPEC REQUIREMENT: the provider must supply an implementation class containing the following method signatures:

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

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

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

When one of the newInstance methods is called, a JAXB implementation is discovered by the following steps.

  1. For each package/class explicitly passed in to the .newInstance method, in the order they are specified, 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 speified ClassLoader.

    If such a file 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. This class is then loaded by the associated classloader 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.)

  2. 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 JAXB implementation.
  3. Look for /META-INF/services/javax.xml.bind.JAXBContext file in the associated classloader. This file follows the standard service descriptor convention, and if such a file exists, its content is assumed to be the provider factory class. This phase of the look up is for automatic discovery. It allows users to just put a JAXB implementation in a classpath and use it without any furhter configuration.
  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 JAXB implementation. This phase of the look up is so that JavaSE can have its own JAXB implementation as the last resort.

Once the provider factory class is discovered, its public static JAXBContext createContext(String,ClassLoader,Map) method (see .newInstance(String, ClassLoader, Map) for the parameter semantics.) or public static JAXBContext createContet(Class[],Map) method (see .newInstance(Class[], Map) for the parameter semantics) are invoked to create a JAXBContext. @author

@version $Revision: 1.24.4.2 $ $Date: 20062008/0305/08 1715 22:05:0102 $ @see Marshaller @see Unmarshaller @see S 7.4.1.1 "Package Annotations" in Java Language Specification, 3rd Edition @since JAXB1.0
Class JAXBContext, JAXBContext newInstance(Class[])

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. @param 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. @return 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.)
@throws IllegalArgumentException if the parameter contains {@code null} (i.e., {@code newInstance(null);}) @since JAXB2.0
Class JAXBContext, JAXBContext newInstance(Class[], Map<String, ?>)

Obtain a new instance of a JAXBContext class.

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

The interpretation of properties is implementationup specificto implementations. Implementations should throw JAXBException if it finds properties that it doesn't understand. @param 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. @param properties provider-specific properties. Can be null, which means the same thing as passing in an empty map. @return 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.)
@throws IllegalArgumentException if the parameter contains {@code null} (i.e., {@code newInstance(null,someMap);}) @since JAXB2.0
Class JAXBContext, JAXBContext newInstance(String)

Obtain a new instance of a JAXBContext class.

This is a convenience method for the to invoke the .newInstance(String,ClassLoader) method. It uses with 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 newInstance method. @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
Class JAXBContext, JAXBContext newInstance(String, ClassLoader)

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 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:

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. @param contextPath list of java package names that contain schema derived class and/or java to schema (JAXB-annotated) mapped 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

  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
Class JAXBContext, JAXBContext newInstance(String, ClassLoader, Map<String, ?>)

Obtain a new instance of a JAXBContext class.

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

The interpretation of properties is up to implementations. Implementations should throw JAXBException if it finds properties that it doesn't understand. @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. @param properties provider-specific properties properties. Can be null, which means the same thing as passing in an empty map. @return 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