ohair@286: * The JAXBContext class provides the client's entry point to the ohair@286: * JAXB API. It provides an abstraction for managing the XML/Java binding ohair@286: * information necessary to implement the JAXB binding framework operations: ohair@286: * unmarshal, marshal and validate. ohair@286: * ohair@286: *
A client application normally obtains new instances of this class using ohair@286: * one of these two styles for newInstance methods, although there are other ohair@286: * specialized forms of the method available: ohair@286: * ohair@286: *
ohair@286: * SPEC REQUIREMENT: the provider must supply an implementation ohair@286: * class containing the following method signatures: ohair@286: * ohair@286: *
ohair@286: * public static JAXBContext createContext( String contextPath, ClassLoader classLoader, Map<String,Object> properties ) throws JAXBException ohair@286: * public static JAXBContext createContext( Class[] classes, Map<String,Object> properties ) throws JAXBException ohair@286: *ohair@286: * ohair@286: *
ohair@286: * The following JAXB 1.0 requirement is only required for schema to ohair@286: * java interface/implementation binding. It does not apply to JAXB annotated ohair@286: * classes. JAXB Providers must generate a jaxb.properties file in ohair@286: * each package containing schema derived classes. The property file must ohair@286: * contain a property named javax.xml.bind.context.factory whose ohair@286: * value is the name of the class that implements the createContext ohair@286: * APIs. ohair@286: * ohair@286: *
ohair@286: * The class supplied by the provider does not have to be assignable to ohair@286: * javax.xml.bind.JAXBContext, it simply has to provide a class that ohair@286: * implements the createContext APIs. ohair@286: * ohair@286: *
ohair@286: * In addition, the provider must call the ohair@286: * {@link DatatypeConverter#setDatatypeConverter(DatatypeConverterInterface) ohair@286: * DatatypeConverter.setDatatypeConverter} api prior to any client ohair@286: * invocations of the marshal and unmarshal methods. This is necessary to ohair@286: * configure the datatype converter that will be used during these operations. ohair@286: * ohair@286: * ohair@286: *
ohair@286: * The {@link Unmarshaller} class provides the client application the ability ohair@286: * to convert XML data into a tree of Java content objects. ohair@286: * The unmarshal method allows for ohair@286: * any global XML element declared in the schema to be unmarshalled as ohair@286: * the root of an instance document. ohair@286: * Additionally, the unmarshal method allows for an unrecognized root element that ohair@286: * has an xsi:type attribute's value that references a type definition declared in ohair@286: * the schema to be unmarshalled as the root of an instance document. ohair@286: * The JAXBContext object ohair@286: * allows the merging of global elements and type definitions across a set of schemas (listed ohair@286: * in the contextPath). Since each schema in the schema set can belong ohair@286: * to distinct namespaces, the unification of schemas to an unmarshalling ohair@286: * context should be namespace independent. This means that a client ohair@286: * application is able to unmarshal XML documents that are instances of ohair@286: * any of the schemas listed in the contextPath. For example: ohair@286: * ohair@286: *
ohair@286: * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo:com.acme.bar" ); ohair@286: * Unmarshaller u = jc.createUnmarshaller(); ohair@286: * FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) ); // ok ohair@286: * BarObject barObj = (BarObject)u.unmarshal( new File( "bar.xml" ) ); // ok ohair@286: * BazObject bazObj = (BazObject)u.unmarshal( new File( "baz.xml" ) ); // error, "com.acme.baz" not in contextPath ohair@286: *ohair@286: * ohair@286: *
ohair@286: * The client application may also generate Java content trees explicitly rather ohair@286: * than unmarshalling existing XML data. For all JAXB-annotated value classes, ohair@286: * an application can create content using constructors. ohair@286: * For schema-derived interface/implementation classes and for the ohair@286: * creation of elements that are not bound to a JAXB-annotated ohair@286: * class, an application needs to have access and knowledge about each of ohair@286: * the schema derived ObjectFactory classes that exist in each of ohair@286: * java packages contained in the contextPath. For each schema ohair@286: * derived java class, there is a static factory method that produces objects ohair@286: * of that type. For example, ohair@286: * assume that after compiling a schema, you have a package com.acme.foo ohair@286: * that contains a schema derived interface named PurchaseOrder. In ohair@286: * order to create objects of that type, the client application would use the ohair@286: * factory method like this: ohair@286: * ohair@286: *
ohair@286: * com.acme.foo.PurchaseOrder po = ohair@286: * com.acme.foo.ObjectFactory.createPurchaseOrder(); ohair@286: *ohair@286: * ohair@286: *
ohair@286: * Once the client application has an instance of the the schema derived object, ohair@286: * it can use the mutator methods to set content on it. ohair@286: * ohair@286: *
ohair@286: * For more information on the generated ObjectFactory classes, see ohair@286: * Section 4.2 Java Package of the specification. ohair@286: * ohair@286: *
ohair@286: * SPEC REQUIREMENT: the provider must generate a class in each ohair@286: * package that contains all of the necessary object factory methods for that ohair@286: * package named ObjectFactory as well as the static ohair@286: * newInstance( javaContentInterface ) method ohair@286: * ohair@286: *
ohair@286: * The {@link Marshaller} class provides the client application the ability ohair@286: * to convert a Java content tree back into XML data. There is no difference ohair@286: * between marshalling a content tree that is created manually using the factory ohair@286: * methods and marshalling a content tree that is the result an unmarshal ohair@286: * operation. Clients can marshal a java content tree back to XML data ohair@286: * to a java.io.OutputStream or a java.io.Writer. The ohair@286: * marshalling process can alternatively produce SAX2 event streams to a ohair@286: * registered ContentHandler or produce a DOM Node object. ohair@286: * Client applications have control over the output encoding as well as ohair@286: * whether or not to marshal the XML data as a complete document or ohair@286: * as a fragment. ohair@286: * ohair@286: *
ohair@286: * Here is a simple example that unmarshals an XML document and then marshals ohair@286: * it back out: ohair@286: * ohair@286: *
ohair@286: * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); ohair@286: * ohair@286: * // unmarshal from foo.xml ohair@286: * Unmarshaller u = jc.createUnmarshaller(); ohair@286: * FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) ); ohair@286: * ohair@286: * // marshal to System.out ohair@286: * Marshaller m = jc.createMarshaller(); ohair@286: * m.marshal( fooObj, System.out ); ohair@286: *ohair@286: * ohair@286: * ohair@286: *
ohair@286: * Validation has been changed significantly since JAXB 1.0. The {@link Validator} ohair@286: * class has been deprecated and made optional. This means that you are advised ohair@286: * not to use this class and, in fact, it may not even be available depending on ohair@286: * your JAXB provider. JAXB 1.0 client applications that rely on Validator ohair@286: * will still work properly when deployed with the JAXB 1.0 runtime system. ohair@286: * ohair@286: * In JAXB 2.0, the {@link Unmarshaller} has included convenince methods that expose ohair@286: * the JAXP 1.3 {@link javax.xml.validation} framework. Please refer to the ohair@286: * {@link Unmarshaller#setSchema(javax.xml.validation.Schema)} API for more ohair@286: * information. ohair@286: * ohair@286: * ohair@286: *
ohair@286: * The following JAXB 1.0 restriction only applies to binding schema to ohair@286: * interfaces/implementation classes. ohair@286: * Since this binding does not require a common runtime system, a JAXB ohair@286: * client application must not attempt to mix runtime objects (JAXBContext, ohair@286: * Marshaller, etc. ) from different providers. This does not ohair@286: * mean that the client application isn't portable, it simply means that a ohair@286: * client has to use a runtime system provided by the same provider that was ohair@286: * used to compile the schema. ohair@286: * ohair@286: * ohair@286: *
ohair@286: * When one of the newInstance methods is called, a JAXB implementation is discovered ohair@286: * by the following steps. ohair@286: * ohair@286: *
ohair@286: * If such a file is discovered, it is {@link Properties#load(InputStream) loaded} as a property file, and ohair@286: * the value of the {@link #JAXB_CONTEXT_FACTORY} key will be assumed to be the provider factory class. ohair@286: * This class is then loaded by the associated classloader discussed above. ohair@286: * ohair@286: *
ohair@286: * This phase of the look up allows some packages to force the use of a certain JAXB implementation. ohair@286: * (For example, perhaps the schema compiler has generated some vendor extension in the code.) ohair@286: * ohair@286: *
ohair@286: * Once the provider factory class is discovered, its ohair@286: * public static JAXBContext createContext(String,ClassLoader,Map) method ohair@286: * (see {@link #newInstance(String, ClassLoader, Map)} for the parameter semantics.) ohair@286: * or public static JAXBContext createContet(Class[],Map) method ohair@286: * (see {@link #newInstance(Class[], Map)} for the parameter semantics) are invoked ohair@286: * to create a {@link JAXBContext}. ohair@286: * ohair@286: * @author
ohair@286: * Obtain a new instance of a JAXBContext class. ohair@286: * ohair@286: *
ohair@286: * This is a convenience method to invoke the ohair@286: * {@link #newInstance(String,ClassLoader)} method with ohair@286: * the context class loader of the current thread. ohair@286: * ohair@286: * @throws JAXBException if an error was encountered while creating the ohair@286: * JAXBContext such as ohair@286: *
ohair@286: * Obtain a new instance of a JAXBContext class. ohair@286: * ohair@286: *
ohair@286: * The client application must supply a context path which is a list of ohair@286: * colon (':', \u005Cu003A) separated java package names that contain ohair@286: * schema-derived classes and/or fully qualified JAXB-annotated classes. ohair@286: * Schema-derived ohair@286: * code is registered with the JAXBContext by the ohair@286: * ObjectFactory.class generated per package. ohair@286: * Alternatively than being listed in the context path, programmer ohair@286: * annotated JAXB mapped classes can be listed in a ohair@286: * jaxb.index resource file, format described below. ohair@286: * Note that a java package can contain both schema-derived classes and ohair@286: * user annotated JAXB classes. Additionally, the java package may ohair@286: * contain JAXB package annotations that must be processed. (see JLS, ohair@286: * Section 7.4.1 "Named Packages"). ohair@286: *
ohair@286: * ohair@286: *ohair@286: * Every package listed on the contextPath must meet one or both of the ohair@286: * following conditions otherwise a JAXBException will be thrown: ohair@286: *
ohair@286: *ohair@286: * Format for jaxb.index ohair@286: *
ohair@286: * The file contains a newline-separated list of class names. ohair@286: * Space and tab characters, as well as blank ohair@286: * lines, are ignored. The comment character ohair@286: * is '#' (0x23); on each line all characters following the first comment ohair@286: * character are ignored. The file must be encoded in UTF-8. Classes that ohair@286: * are reachable, as defined in {@link #newInstance(Class...)}, from the ohair@286: * listed classes are also registered with JAXBContext. ohair@286: *
ohair@286: * Constraints on class name occuring in a jaxb.index file are: ohair@286: *
ohair@286: * To maintain compatibility with JAXB 1.0 schema to java ohair@286: * interface/implementation binding, enabled by schema customization ohair@286: * <jaxb:globalBindings valueClass="false">, ohair@286: * the JAXB provider will ensure that each package on the context path ohair@286: * has a jaxb.properties file which contains a value for the ohair@286: * javax.xml.bind.context.factory property and that all values ohair@286: * resolve to the same provider. This requirement does not apply to ohair@286: * JAXB annotated classes. ohair@286: * ohair@286: *
ohair@286: * If there are any global XML element name collisions across the various ohair@286: * packages listed on the contextPath, a JAXBException ohair@286: * will be thrown. ohair@286: * ohair@286: *
ohair@286: * Mixing generated interface/impl bindings from multiple JAXB Providers ohair@286: * in the same context path may result in a JAXBException ohair@286: * being thrown. ohair@286: * ohair@286: *
ohair@286: * The steps involved in discovering the JAXB implementation is discussed in the class javadoc. ohair@286: * ohair@286: * @param contextPath list of java package names that contain schema ohair@286: * derived class and/or java to schema (JAXB-annotated) ohair@286: * mapped classes ohair@286: * @param classLoader ohair@286: * This class loader will be used to locate the implementation ohair@286: * classes. ohair@286: * ohair@286: * @return a new instance of a JAXBContext ohair@286: * @throws JAXBException if an error was encountered while creating the ohair@286: * JAXBContext such as ohair@286: *
ohair@286: * Obtain a new instance of a JAXBContext class. ohair@286: * ohair@286: *
ohair@286: * This is mostly the same as {@link JAXBContext#newInstance(String, ClassLoader)}, ohair@286: * but this version allows you to pass in provider-specific properties to configure ohair@286: * the instantiation of {@link JAXBContext}. ohair@286: * ohair@286: *
ohair@286: * The interpretation of properties is up to implementations. Implementations should ohair@286: * throw JAXBException if it finds properties that it doesn't understand. ohair@286: * ohair@286: * @param contextPath list of java package names that contain schema derived classes ohair@286: * @param classLoader ohair@286: * This class loader will be used to locate the implementation classes. ohair@286: * @param properties ohair@286: * provider-specific properties. Can be null, which means the same thing as passing ohair@286: * in an empty map. ohair@286: * ohair@286: * @return a new instance of a JAXBContext ohair@286: * @throws JAXBException if an error was encountered while creating the ohair@286: * JAXBContext such as ohair@286: *
ohair@286: // * Obtain a new instance of a JAXBContext class. ohair@286: // * ohair@286: // *
ohair@286: // * The client application must supply a list of classes that the new ohair@286: // * context object needs to recognize. ohair@286: // * ohair@286: // * Not only the new context will recognize all the classes specified, ohair@286: // * but it will also recognize any classes that are directly/indirectly ohair@286: // * referenced statically from the specified classes. ohair@286: // * ohair@286: // * For example, in the following Java code, if you do ohair@286: // * newInstance(Foo.class), the newly created {@link JAXBContext} ohair@286: // * will recognize both Foo and Bar, but not Zot: ohair@286: // *
ohair@286: // * class Foo {
ohair@286: // * Bar b;
ohair@286: // * }
ohair@286: // * class Bar { int x; }
ohair@286: // * class Zot extends Bar { int y; }
ohair@286: // *
ohair@286: // *
ohair@286: // * Therefore, a typical client application only needs to specify the
ohair@286: // * top-level classes, but it needs to be careful.
ohair@286: // *
ohair@286: // * TODO: if we are to define other mechanisms, refer to them.
ohair@286: // *
ohair@286: // * @param externalBindings
ohair@286: // * list of external binding files. Can be null or empty if none is used.
ohair@286: // * when specified, those files determine how the classes are bound.
ohair@286: // *
ohair@286: // * @param classesToBeBound
ohair@286: // * list of java classes to be recognized by the new {@link JAXBContext}.
ohair@286: // * Can be empty, in which case a {@link JAXBContext} that only knows about
ohair@286: // * spec-defined classes will be returned.
ohair@286: // *
ohair@286: // * @return
ohair@286: // * A new instance of a JAXBContext. Always non-null valid object.
ohair@286: // *
ohair@286: // * @throws JAXBException
ohair@286: // * if an error was encountered while creating the
ohair@286: // * JAXBContext, such as (but not limited to):
ohair@286: // * ohair@286: * Obtain a new instance of a JAXBContext class. ohair@286: * ohair@286: *
ohair@286: * The client application must supply a list of classes that the new ohair@286: * context object needs to recognize. ohair@286: * ohair@286: * Not only the new context will recognize all the classes specified, ohair@286: * but it will also recognize any classes that are directly/indirectly ohair@286: * referenced statically from the specified classes. Subclasses of ohair@286: * referenced classes nor @XmlTransient referenced classes ohair@286: * are not registered with JAXBContext. ohair@286: * ohair@286: * For example, in the following Java code, if you do ohair@286: * newInstance(Foo.class), the newly created {@link JAXBContext} ohair@286: * will recognize both Foo and Bar, but not Zot or FooBar: ohair@286: *
ohair@286: * class Foo {
ohair@286: * @XmlTransient FooBar c;
ohair@286: * Bar b;
ohair@286: * }
ohair@286: * class Bar { int x; }
ohair@286: * class Zot extends Bar { int y; }
ohair@286: * class FooBar { }
ohair@286: *
ohair@286: *
ohair@286: * Therefore, a typical client application only needs to specify the
ohair@286: * top-level classes, but it needs to be careful.
ohair@286: *
ohair@286: * ohair@286: * Note that for each java package registered with JAXBContext, ohair@286: * when the optional package annotations exist, they must be processed. ohair@286: * (see JLS, Section 7.4.1 "Named Packages"). ohair@286: * ohair@286: *
ohair@286: * The steps involved in discovering the JAXB implementation is discussed in the class javadoc. ohair@286: * ohair@286: * @param classesToBeBound ohair@286: * list of java classes to be recognized by the new {@link JAXBContext}. ohair@286: * Can be empty, in which case a {@link JAXBContext} that only knows about ohair@286: * spec-defined classes will be returned. ohair@286: * ohair@286: * @return ohair@286: * A new instance of a JAXBContext. Always non-null valid object. ohair@286: * ohair@286: * @throws JAXBException ohair@286: * if an error was encountered while creating the ohair@286: * JAXBContext, such as (but not limited to): ohair@286: *
ohair@286: * Obtain a new instance of a JAXBContext class. ohair@286: * ohair@286: *
ohair@286: * An overloading of {@link JAXBContext#newInstance(Class...)} ohair@286: * to configure 'properties' for this instantiation of {@link JAXBContext}. ohair@286: * ohair@286: *
ohair@286: * The interpretation of properties is up to implementations. Implementations should ohair@286: * throw JAXBException if it finds properties that it doesn't understand. ohair@286: * ohair@286: * @param classesToBeBound ohair@286: * list of java classes to be recognized by the new {@link JAXBContext}. ohair@286: * Can be empty, in which case a {@link JAXBContext} that only knows about ohair@286: * spec-defined classes will be returned. ohair@286: * @param properties ohair@286: * provider-specific properties. Can be null, which means the same thing as passing ohair@286: * in an empty map. ohair@286: * ohair@286: * @return ohair@286: * A new instance of a JAXBContext. Always non-null valid object. ohair@286: * ohair@286: * @throws JAXBException ohair@286: * if an error was encountered while creating the ohair@286: * JAXBContext, such as (but not limited to): ohair@286: *
ohair@286: * Create a Validator object that can be used to validate a
ohair@286: * java content tree against its source schema.
ohair@286: *
ohair@286: * @return a Validator object
ohair@286: *
ohair@286: * @throws JAXBException if an error was encountered while creating the
ohair@286: * Validator object
ohair@286: * @deprecated since JAXB2.0
ohair@286: */
ohair@286: public abstract Validator createValidator() throws JAXBException;
ohair@286:
ohair@286: /**
ohair@286: * Creates a Binder object that can be used for
ohair@286: * associative/in-place unmarshalling/marshalling.
ohair@286: *
ohair@286: * @param domType select the DOM API to use by passing in its DOM Node class.
ohair@286: *
ohair@286: * @return always a new valid Binder object.
ohair@286: *
ohair@286: * @throws UnsupportedOperationException
ohair@286: * if DOM API corresponding to domType is not supported by
ohair@286: * the implementation.
ohair@286: *
ohair@286: * @since JAXB2.0
ohair@286: */
ohair@286: public