001    /*
002     * $Id: JAXBContext.java,v 1.28 2003/01/23 22:08:06 ryans Exp $
003     *
004     * Copyright 2001 Sun Microsystems, Inc. All Rights Reserved.
005     * 
006     * This software is the proprietary information of Sun Microsystems, Inc.  
007     * Use is subject to license terms.
008     * 
009     */
010    
011    package javax.xml.bind;
012    
013    /**
014     * <p>
015     * The <tt>JAXBContext</tt> class provides the client's entry point to the 
016     * JAXB API. It provides an abstraction for managing the XML/Java binding 
017     * information necessary to implement the JAXB binding framework operations: 
018     * unmarshal, marshal and validate.  A client application obtains new instances 
019     * of this class via the {@link #newInstance(String) newInstance(contextPath)}
020     * method.
021     *
022     * <pre>
023     *     JAXBContext jc = JAXBContext.newInstance( "com.acme.foo:com.acme.bar" );
024     * </pre>
025     *
026     * <p>
027     * The <tt>contextPath</tt> contains a list of Java package names that contain
028     * schema derived interfaces.  The value of this parameter initializes the 
029     * <tt>JAXBContext</tt> object so that it is capable of managing the
030     * schema derived interfaces.
031     *
032     * <p>
033     * <blockquote>
034     * <i><B>SPEC REQUIREMENT:</B> the provider must supply an implementation
035     * class containing a method with the following signature:</i>
036     *
037     * <pre>
038     *        public static JAXBContext createContext( String contextPath, ClassLoader classLoader )
039     *            throws JAXBException;
040     * </pre>
041     *
042     * <p><i>
043     * JAXB Providers must generate a <tt>jaxb.properties</tt> file in each package
044     * containing schema derived classes.  The property file must contain a
045     * property named <tt>javax.xml.bind.context.factory</tt> whose value is
046     * the name of the class that implements the <tt>createContext</tt> API.</i>
047     * 
048     * <p><i>
049     * The class supplied by the provider does not have to be assignable to 
050     * <tt>javax.xml.bind.JAXBContext</tt>, it simply has to provide a class that
051     * implements the <tt>createContext</tt> API.</i>
052     * 
053     * <p><i>
054     * In addition, the provider must call the 
055     * {@link DatatypeConverter#setDatatypeConverter(DatatypeConverterInterface) 
056     * DatatypeConverter.setDatatypeConverter} api prior to any client 
057     * invocations of the marshal and unmarshal methods.  This is necessary to 
058     * configure the datatype converter that will be used during these operations.</i>
059     * </blockquote>
060     *
061     * <p>
062     * <b>Unmarshalling</b>
063     * <p>
064     * <blockquote>
065     * The {@link Unmarshaller} class provides the client application the ability
066     * to convert XML data into a tree of Java content objects.
067     * The unmarshal method for a schema (within a namespace) allows for
068     * any global XML element declared in the schema to be unmarshalled as
069     * the root of an instance document. The <tt>JAXBContext</tt> object 
070     * allows the merging of global elements across a set of schemas (listed
071     * in the <tt>contextPath</tt>). Since each schema in the schema set can belong
072     * to distinct namespaces, the unification of schemas to an unmarshalling 
073     * context should be namespace independent.  This means that a client 
074     * application is able to unmarshal XML documents that are instances of
075     * any of the schemas listed in the <tt>contextPath</tt>.  For example:
076     *
077     * <pre>
078     *        JAXBContext jc = JAXBContext.newInstance( "com.acme.foo:com.acme.bar" );
079     *        Unmarshaller u = jc.createUnmarshaller();
080     *        FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) ); // ok
081     *        BarObject barObj = (BarObject)u.unmarshal( new File( "bar.xml" ) ); // ok
082     *        BazObject bazObj = (BazObject)u.unmarshal( new File( "baz.xml" ) ); // error, "com.acme.baz" not in contextPath
083     * </pre>
084     *
085     * <p>
086     * The client application may also generate Java content trees explicitly rather
087     * than unmarshalling existing XML data.  To do so, the application needs to 
088     * have access and knowledge about each of the schema derived <tt>
089     * ObjectFactory</tt> classes that exist in each of java packages contained 
090     * in the <tt>contextPath</tt>.  For each schema derived java class, there will 
091     * be a static factory method that produces objects of that type.  For example, 
092     * assume that after compiling a schema, you have a package <tt>com.acme.foo</tt> 
093     * that contains a schema derived interface named <tt>PurchaseOrder</tt>.  In 
094     * order to create objects of that type, the client application would use the 
095     * factory method like this:
096     *
097     * <pre>
098     *       com.acme.foo.PurchaseOrder po = 
099     *           com.acme.foo.ObjectFactory.createPurchaseOrder();
100     * </pre>
101     *
102     * <p>
103     * Once the client application has an instance of the the schema derived object,
104     * it can use the mutator methods to set content on it.
105     *
106     * <p>
107     * For more information on the generated <tt>ObjectFactory</tt> classes, see
108     * Section 4.2 <i>Java Package</i> of the specification.
109     *
110     * <p>
111     * <i><B>SPEC REQUIREMENT:</B> the provider must generate a class in each
112     * package that contains all of the necessary object factory methods for that 
113     * package named ObjectFactory as well as the static 
114     * <tt>newInstance( javaContentInterface )</tt> method</i>  
115     * </blockquote>
116     *
117     * <p>
118     * <b>Marshalling</b>
119     * <p>
120     * <blockquote>
121     * The {@link Marshaller} class provides the client application the ability
122     * to convert a Java content tree back into XML data.  There is no difference
123     * between marshalling a content tree that is created manually using the factory
124     * methods and marshalling a content tree that is the result an <tt>unmarshal
125     * </tt> operation.  Clients can marshal a java content tree back to XML data
126     * to a <tt>java.io.OutputStream</tt> or a <tt>java.io.Writer</tt>.  The 
127     * marshalling process can alternatively produce SAX2 event streams to a 
128     * registered <tt>ContentHandler</tt> or produce a DOM Node object.  
129     * <!-- don't expose fragment support yet 
130     * Client applications 
131     * have control over the output encoding as well as whether or not to marshal 
132     * the XML data as a complete document or as a fragment.
133     * -->
134     *
135     * <p>
136     * Here is a simple example that unmarshals an XML document and then marshals
137     * it back out:
138     *
139     * <pre>
140     *        JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
141     *
142     *        // unmarshal from foo.xml
143     *        Unmarshaller u = jc.createUnmarshaller();
144     *        FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) );
145     *
146     *        // marshal to System.out
147     *        Marshaller m = jc.createMarshaller();
148     *        m.marshal( fooObj, System.out );
149     * </pre>
150     * </blockquote>
151     *
152     * <p>
153     * <b>Validation</b>
154     * <p>
155     * <blockquote>
156     * There are three varieties of validation available to JAXB client applications:
157     * <blockquote>
158     * <dl>
159     *   <dt>Unmarshal-time Validation</dt>
160     *   <dd>Validation performed on the XML data as it is being unmarshalled into
161     *       a Java content tree</dd>
162     *   <dt>On-Demand Validation</dt>
163     *   <dd>Validation performed on the Java content tree in memory</dd>
164     *   <dt>Fail-Fast Validation</dt>
165     *   <dd>Validation of Java property constraints at runtime when client
166     *       applications invoke the setter methods of the generated classes</dd>
167     * </dl>
168     * </blockquote>
169     *
170     * <p>
171     * See: <a href="Validator.html#validationtypes">Validator javadocs</a> for a 
172     * more detailed definition of the different type of validation.
173     *
174     * <p>
175     * Although unmarshal-time validation and on-demand validation are very similar, 
176     * they are completely orthogonal operations with no dependencies on each other.  
177     * Client applications are free to use one, both, or neither types of validation.
178     *
179     * <p>
180     * Validation errors and warnings encountered during the unmarshal and validate 
181     * operations are reported to the client application via a callback error handler 
182     * interface ({@link ValidationEventHandler ValidationEventHandler}) that receives
183     * {@link ValidationEvent ValidationEvent} objects.  The <tt>ValidationEvent</tt>
184     * objects contain information about the error or warning encountered.  JAXB 
185     * allows a few diffent methods of handling validation events which are described 
186     * in more detail in the 
187     * <a href="Validator.html#handlingerrors">Validator javadoc</a>.
188     * </blockquote>
189     *
190     * <p>
191     * <b>JAXB Runtime Binding Framework Compatibility</b><br>
192     * <blockquote>
193     * Since the JAXB Specification does not define a common runtime system, a JAXB 
194     * client application must not attempt to mix runtime objects (<tt>JAXBContext,
195     * Marshaller</tt>, etc. ) from different providers.  This does not 
196     * mean that the client application isn't portable, it simply means that a 
197     * client has to use a runtime system provided by the same provider that was 
198     * used to compile the schema.
199     * </blockquote>
200     *
201     * @author <ul><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul>
202     * @version $Revision: 1.28 $ $Date: 2003/01/23 22:08:06 $
203     * @see Marshaller
204     * @see Unmarshaller
205     * @see Validator
206     * @since JAXB1.0
207     */
208    public abstract class JAXBContext {
209        
210        /**
211         * The name of the property that contains the name of the class capable
212         * of creating new <tt>JAXBContext</tt> objects.
213         */
214        public static final String JAXB_CONTEXT_FACTORY = 
215            "javax.xml.bind.context.factory";
216           
217    
218        protected JAXBContext() {
219        }
220    
221        
222        /**
223         * <p>
224         * Obtain a new instance of a <tt>JAXBContext</tt> class.
225         *
226         * <p>
227         * This is a convenience method for the 
228         * {@link #newInstance(String,ClassLoader) newInstance} method.  It uses
229         * the context class loader of the current thread.  To specify the use of
230         * a different class loader, either set it via the 
231         * <tt>Thread.setContextClassLoader()</tt> api or use the 
232         * {@link #newInstance(String,ClassLoader) newInstance} method.
233         */
234        public static JAXBContext newInstance( String contextPath ) 
235            throws JAXBException {
236                
237            //return newInstance( contextPath, JAXBContext.class.getClassLoader() );
238            return newInstance( contextPath, Thread.currentThread().getContextClassLoader() );
239        }
240        
241        
242        
243        /**
244         * <p>
245         * Obtain a new instance of a <tt>JAXBContext</tt> class.
246         *
247         * <p>
248         * The client application must supply a context path which is a list of 
249         * colon (':', \u005Cu003A) separated java package names that contain schema 
250         * derived classes.
251         *
252         * The JAXB provider will ensure that each package on the context path
253         * has a <tt>jaxb.properties</tt> file which contains a value for the 
254         * <tt>javax.xml.bind.context.factory</tt> property and that all values
255         * resolve to the same provider.
256         *
257         * <p>
258         * If there are any global XML element name collisions across the various 
259         * packages listed on the <tt>contextPath</tt>, a <tt>JAXBException</tt> 
260         * will be thrown.  Mixing generated classes from multiple JAXB Providers 
261         * in the same context path will also result in a <tt>JAXBException</tt> 
262         * being thrown.
263         *  
264         * @param contextPath list of java package names that contain schema 
265         *                     derived classes
266         * @param classLoader
267         *      This class loader will be used to locate the implementation
268         *      classes.
269         *
270         * @return a new instance of a <tt>JAXBContext</tt>
271         * @throws JAXBException if an error was encountered while creating the
272         *                       <tt>JAXBContext</tt>, such as an ambiguity among
273         *                       global elements contained in the contextPath,
274         *                       failure to locate a value for the context factory
275         *                       property, or mixing schema derived packages from
276         *                       different providers on the same contextPath.
277         */
278        public static JAXBContext newInstance( String contextPath, ClassLoader classLoader ) 
279            throws JAXBException {
280                
281            return (JAXBContext) ContextFinder.find(
282                    /* The default property name according to the JAXB spec */
283                    JAXB_CONTEXT_FACTORY,
284                    
285                    /* the context path supplied by the client app */
286                    contextPath,
287                    
288                    /* class loader to be used */
289                    classLoader );
290        }
291        
292        
293        /** 
294         * Create an <tt>Unmarshaller</tt> object that can be used to convert XML
295         * data into a java content tree.
296         *
297         * @return an <tt>Unmarshaller</tt> object
298         *
299         * @throws JAXBException if an error was encountered while creating the
300         *                       <tt>Unmarshaller</tt> object
301         */    
302        public abstract Unmarshaller createUnmarshaller() throws JAXBException;
303        
304        
305        /** 
306         * Create a <tt>Marshaller</tt> object that can be used to convert a 
307         * java content tree into XML data.
308         *
309         * @return a <tt>Marshaller</tt> object
310         *
311         * @throws JAXBException if an error was encountered while creating the
312         *                       <tt>Marshaller</tt> object
313         */    
314        public abstract Marshaller createMarshaller() throws JAXBException;
315        
316        
317        /** 
318         * Create a <tt>Validator</tt> object that can be used to validate a
319         * java content tree against its source schema.
320         *
321         * @return a <tt>Validator</tt> object
322         *
323         * @throws JAXBException if an error was encountered while creating the
324         *                       <tt>Validator</tt> object
325         */    
326        public abstract Validator createValidator() throws JAXBException;
327        
328    }