/*
 * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

package javax.xml.bind;

import org.w3c.dom.Node;

import java.util.Collections;
import java.util.Map;
import java.io.IOException;

/**
 * <p>
 * The <tt>JAXBContext</tt> 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.
 *
 * <p>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:
 *
 * <ul>
 *   <li>{@link #newInstance(String,ClassLoader) JAXBContext.newInstance( "com.acme.foo:com.acme.bar" )} <br/>

 *   The JAXBContext instance is initialized from a list of colon 
 *   separated Java package names. Each java package contains
 *   JAXB mapped classes, schema-derived classes and/or user annotated 
 *   classes. Additionally, the java package may contain JAXB package annotations 
 *   that must be processed. (see JLS 3rd Edition, Section 7.4.1. Package Annotations).
 *   </li>
 *   <li>{@link #newInstance(Class...) JAXBContext.newInstance( com.acme.foo.Foo.class )} <br/>
 *    The JAXBContext instance is intialized with class(es) 
 *    passed as parameter(s) and classes that are statically reachable from 
 *    these class(es). See {@link #newInstance(Class...)} for details.
 *   </li>
 * </ul>
 *
 * <p>
 * <blockquote>
 * <i><B>SPEC REQUIREMENT:</B> the provider must supply an implementation
 * class containing the following method signatures:</i>
 *
 * <pre>
 * public static JAXBContext createContext( String contextPath, ClassLoader classLoader, Map<String,Object> properties ) 
throws JAXBException
 * public static JAXBContext createContext( Class[] classes, Map<String,Object> properties ) throws JAXBException

 * </pre>
 *
 * <p><i>
 * 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 <tt>jaxb.properties</tt> file in 
 * each package containing schema derived classes.  The property file must 
 * contain a property named <tt>javax.xml.bind.context.factory</tt> whose 
 * value is the name of the class that implements the <tt>createContext</tt> 
 * APIs.</i>
 * 
 * <p><i>
 * The class supplied by the provider does not have to be assignable to 
 * <tt>javax.xml.bind.JAXBContext</tt>, it simply has to provide a class that
 * implements the <tt>createContext</tt> APIs.</i>
 * 
 * <p><i>
 * In addition, the provider must call the 
 * {@link DatatypeConverter#setDatatypeConverter(DatatypeConverterInterface) 
 * 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.</i>
 * </blockquote>
 *
 * <p>
 * <a name="Unmarshalling"></a>
 * <b>Unmarshalling</b>
 * <p>
 * <blockquote>
 * The {@link 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 <tt>JAXBContext</tt> object 
 * allows the merging of global elements and type definitions across a set of schemas (listed
 * in the <tt>contextPath</tt>). 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 <tt>contextPath</tt>.  For example:
 *
 * <pre>
 *        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

 * </pre>
 *