Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

de.ispsoft.jaxme.jaxb
Class JAXBContext

java.lang.Object
  extended byde.ispsoft.jaxme.jaxb.JAXBContext
Direct Known Subclasses:
JMManagerFactoryImpl
Deprecated. Soon to be replaced with javax.xml.bind.JAXBContext

public abstract class JAXBContext
extends java.lang.Object

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 obtains new instances of this class via the newInstance(contextPath) method. 

     JAXBContext jc = JAXBContext.newInstance( "com.acme.foo:com.acme.bar" );

The contextPath contains a list of Java package names that contain schema derived interfaces. The value of this parameter initializes the JAXBContext object so that it is capable of managing the schema derived interfaces.

SPEC REQUIREMENT: the provider must supply an implementation class containing a method with the following signature: 
        public static JAXBContext createContext( String contextPath )
            throws JAXBException;

The client application must specify the name of this class via the javax.xml.bind.context.factory property. In most cases, the client should not actually have to specify the property unless they want to override the default. Providers may want to configure this property as a side-effect of the schema compilation process. This property is located via the lookup order described in the newInstance method below. The RI currently generates a jaxb.properties file in each package containing schema derived code (contextPath).

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

Unmarshalling

The Unmarshaller class provides the client application the ability to convert XML data into a tree of Java content objects. The unmarshal method for a schema (within a namespace) allows for any global XML element declared in the schema to be unmarshalled as the root of an instance document. The JAXBContext object allows the merging of global elements 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( "foo.xml" ); // ok
        BarObject barObj = (BarObject)u.unmarshal( "bar.xml" ); // ok
        BazObject bazObj = (BazObject)u.unmarshal( "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. To do so, the 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 will be 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 Chapter 5 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 ) and setImplementation( javaContentInterface, implementationClass ) methods

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.

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( "foo.xml" );

        // marshal to System.out
        Marshaller m = jc.createMarshaller();
        m.marshal( fooObj, System.out );

Validation

There are three varieties of validation available to JAXB client applications:
Unmarshal-time Validation
Validation performed on the XML data as it is being unmarshalled into a Java content tree
On-Demand Validation
Validation performed on the Java content tree in memory
Fail-Fast Validation
Validation of Java property constraints at runtime when client applications invoke the setter methods of the generated classes

See: Validator javadocs for a more detailed definition of the different type of validation.

Although unmarshal-time validation and on-demand validation are very similar, they are completely orthogonal operations with no dependencies on each other. Client applications are free to use one, both, or neither types of validation.

Validation errors and warnings encountered during the unmarshal and validate operations are reported to the client application via a callback error handler interface (ValidationEventHandler) that receives ValidationEvent objects. The ValidationEvent objects contain information about the error or warning encountered. JAXB allows a few diffent methods of handling validation events which are described in more detail in the Validator javadoc.

JAXB Runtime Binding Framework Compatibility

Since the JAXB Specification does not define 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.

Since:
JAXB1.0
Version:
$Revision: 1.5 $ $Date: 2003/05/21 03:30:18 $
Author:
See Also:
Marshaller, Unmarshaller, Validator

Field Summary
static java.lang.String JAXB_CONTEXT_FACTORY
          Deprecated. The name of the property that contains the name of the class capable of creating new JAXBContext objects.
 
Constructor Summary
protected JAXBContext()
          Deprecated.  
 
Method Summary
abstract  Marshaller createMarshaller()
          Deprecated. Create a Marshaller object that can be used to convert a java content tree into XML data.
abstract  Unmarshaller createUnmarshaller()
          Deprecated. Create an Unmarshaller object that can be used to convert XML data into a java content tree.
abstract  Validator createValidator()
          Deprecated. Create a Validator object that can be used to validate a java content tree against its source schema.
static JAXBContext newInstance(java.lang.String contextPath)
          Deprecated.  Obtain a new instance of a JAXBContext class.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

JAXB_CONTEXT_FACTORY

public static final java.lang.String JAXB_CONTEXT_FACTORY
Deprecated. 
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()
Deprecated. 
Method Detail

newInstance

public static JAXBContext newInstance(java.lang.String contextPath)
                               throws JAXBException
Deprecated. 

Obtain a new instance of a JAXBContext class.

Typically, the client application will not have to specify which provider's implementation to have returned from this method. However, it is possible to over ride the default behavior by specifying a value for the javax.xml.bind.context.factory property.

The following ordered lookup procedure is used to determine which concrete implementation of JAXBContext to load:

The client application must supply a list of java package names that contain schema derived classes. The packages should be separated by the system default path separator (System.getProperty( "path.separator" ) ).

If there are any global XML element name collisions across the various packages listed on the contextPath, a JAXBException will be thrown. Mixing generated classes from multiple JAXB Providers in the same context path will also result in a JAXBException being thrown.

TODO:The last bullet is for future integration with JDK1.5

TODO:Additional exception types for this method?

Parameters:
contextPath - list of java package names that contain schema derived classes
Returns:
a new instance of a JAXBContext
Throws:
JAXBException - if an error was encountered while creating the JAXBContext, such as an ambiguity among global elements contained in the contextPath, failure to locate a value for the context factory property, or mixing schema derived packages from different providers on the same contextPath.

createUnmarshaller

public abstract Unmarshaller createUnmarshaller()
                                         throws JAXBException
Deprecated. 
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
Deprecated. 
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. 
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
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD