001 /*
002 * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.xml.bind;
027
028 import org.w3c.dom.Node;
029
030 import java.util.Collections;
031 import java.util.Map;
032 import java.io.IOException;
033
034 /**
035 * <p>
036 * The <tt>JAXBContext</tt> class provides the client's entry point to the
037 * JAXB API. It provides an abstraction for managing the XML/Java binding
038 * information necessary to implement the JAXB binding framework operations:
039 * unmarshal, marshal and validate.
040 *
041 * <p>A client application normally obtains new instances of this class using
042 * one of these two styles for newInstance methods, although there are other
043 * specialized forms of the method available:
044 *
045 * <ul>
046 * <li>{@link #newInstance(String,ClassLoader) JAXBContext.newInstance( "com.acme.foo:com.acme.bar" )} <br/>
047 * The JAXBContext instance is initialized from a list of colon
048 * separated Java package names. Each java package contains
049 * JAXB mapped classes, schema-derived classes and/or user annotated
050 * classes. Additionally, the java package may contain JAXB package annotations
051 * that must be processed. (see JLS 3rd Edition, Section 7.4.1. Package Annotations).
052 * </li>
053 * <li>{@link #newInstance(Class...) JAXBContext.newInstance( com.acme.foo.Foo.class )} <br/>
054 * The JAXBContext instance is intialized with class(es)
055 * passed as parameter(s) and classes that are statically reachable from
056 * these class(es). See {@link #newInstance(Class...)} for details.
057 * </li>
058 * </ul>
059 *
060 * <p>
061 * <blockquote>
062 * <i><B>SPEC REQUIREMENT:</B> the provider must supply an implementation
063 * class containing the following method signatures:</i>
064 *
065 * <pre>
066 * public static JAXBContext createContext( String contextPath, ClassLoader classLoader, Map<String,Object> properties ) throws JAXBException
067 * public static JAXBContext createContext( Class[] classes, Map<String,Object> properties ) throws JAXBException
068 * </pre>
069 *
070 * <p><i>
071 * The following JAXB 1.0 requirement is only required for schema to
072 * java interface/implementation binding. It does not apply to JAXB annotated
073 * classes. JAXB Providers must generate a <tt>jaxb.properties</tt> file in
074 * each package containing schema derived classes. The property file must
075 * contain a property named <tt>javax.xml.bind.context.factory</tt> whose
076 * value is the name of the class that implements the <tt>createContext</tt>
077 * APIs.</i>
078 *
079 * <p><i>
080 * The class supplied by the provider does not have to be assignable to
081 * <tt>javax.xml.bind.JAXBContext</tt>, it simply has to provide a class that
082 * implements the <tt>createContext</tt> APIs.</i>
083 *
084 * <p><i>
085 * In addition, the provider must call the
086 * {@link DatatypeConverter#setDatatypeConverter(DatatypeConverterInterface)
087 * DatatypeConverter.setDatatypeConverter} api prior to any client
088 * invocations of the marshal and unmarshal methods. This is necessary to
089 * configure the datatype converter that will be used during these operations.</i>
090 * </blockquote>
091 *
092 * <p>
093 * <a name="Unmarshalling"></a>
094 * <b>Unmarshalling</b>
095 * <p>
096 * <blockquote>
097 * The {@link Unmarshaller} class provides the client application the ability
098 * to convert XML data into a tree of Java content objects.
099 * The unmarshal method allows for
100 * any global XML element declared in the schema to be unmarshalled as
101 * the root of an instance document.
102 * Additionally, the unmarshal method allows for an unrecognized root element that
103 * has an xsi:type attribute's value that references a type definition declared in
104 * the schema to be unmarshalled as the root of an instance document.
105 * The <tt>JAXBContext</tt> object
106 * allows the merging of global elements and type definitions across a set of schemas (listed
107 * in the <tt>contextPath</tt>). Since each schema in the schema set can belong
108 * to distinct namespaces, the unification of schemas to an unmarshalling
109 * context should be namespace independent. This means that a client
110 * application is able to unmarshal XML documents that are instances of
111 * any of the schemas listed in the <tt>contextPath</tt>. For example:
112 *
113 * <pre>
114 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo:com.acme.bar" );
115 * Unmarshaller u = jc.createUnmarshaller();
116 * FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) ); // ok
117 * BarObject barObj = (BarObject)u.unmarshal( new File( "bar.xml" ) ); // ok
118 * BazObject bazObj = (BazObject)u.unmarshal( new File( "baz.xml" ) ); // error, "com.acme.baz" not in contextPath
119 * </pre>
120 *
121 * <p>
122 * The client application may also generate Java content trees explicitly rather
123 * than unmarshalling existing XML data. For all JAXB-annotated value classes,
124 * an application can create content using constructors.
125 * For schema-derived interface/implementation classes and for the
126 * creation of elements that are not bound to a JAXB-annotated
127 * class, an application needs to have access and knowledge about each of
128 * the schema derived <tt> ObjectFactory</tt> classes that exist in each of
129 * java packages contained in the <tt>contextPath</tt>. For each schema
130 * derived java class, there is a static factory method that produces objects
131 * of that type. For example,
132 * assume that after compiling a schema, you have a package <tt>com.acme.foo</tt>
133 * that contains a schema derived interface named <tt>PurchaseOrder</tt>. In
134 * order to create objects of that type, the client application would use the
135 * factory method like this:
136 *
137 * <pre>
138 * com.acme.foo.PurchaseOrder po =
139 * com.acme.foo.ObjectFactory.createPurchaseOrder();
140 * </pre>
141 *
142 * <p>
143 * Once the client application has an instance of the the schema derived object,
144 * it can use the mutator methods to set content on it.
145 *
146 * <p>
147 * For more information on the generated <tt>ObjectFactory</tt> classes, see
148 * Section 4.2 <i>Java Package</i> of the specification.
149 *
150 * <p>
151 * <i><B>SPEC REQUIREMENT:</B> the provider must generate a class in each
152 * package that contains all of the necessary object factory methods for that
153 * package named ObjectFactory as well as the static
154 * <tt>newInstance( javaContentInterface )</tt> method</i>
155 * </blockquote>
156 *
157 * <p>
158 * <b>Marshalling</b>
159 * <p>
160 * <blockquote>
161 * The {@link Marshaller} class provides the client application the ability
162 * to convert a Java content tree back into XML data. There is no difference
163 * between marshalling a content tree that is created manually using the factory
164 * methods and marshalling a content tree that is the result an <tt>unmarshal
165 * </tt> operation. Clients can marshal a java content tree back to XML data
166 * to a <tt>java.io.OutputStream</tt> or a <tt>java.io.Writer</tt>. The
167 * marshalling process can alternatively produce SAX2 event streams to a
168 * registered <tt>ContentHandler</tt> or produce a DOM Node object.
169 * Client applications have control over the output encoding as well as
170 * whether or not to marshal the XML data as a complete document or
171 * as a fragment.
172 *
173 * <p>
174 * Here is a simple example that unmarshals an XML document and then marshals
175 * it back out:
176 *
177 * <pre>
178 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
179 *
180 * // unmarshal from foo.xml
181 * Unmarshaller u = jc.createUnmarshaller();
182 * FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) );
183 *
184 * // marshal to System.out
185 * Marshaller m = jc.createMarshaller();
186 * m.marshal( fooObj, System.out );
187 * </pre>
188 * </blockquote>
189 *
190 * <p>
191 * <b>Validation</b>
192 * <p>
193 * <blockquote>
194 * Validation has been changed significantly since JAXB 1.0. The {@link Validator}
195 * class has been deprecated and made optional. This means that you are advised
196 * not to use this class and, in fact, it may not even be available depending on
197 * your JAXB provider. JAXB 1.0 client applications that rely on <tt>Validator</tt>
198 * will still work properly when deployed with the JAXB 1.0 runtime system.
199 *
200 * In JAXB 2.0, the {@link Unmarshaller} has included convenince methods that expose
201 * the JAXP 1.3 {@link javax.xml.validation} framework. Please refer to the
202 * {@link Unmarshaller#setSchema(javax.xml.validation.Schema)} API for more
203 * information.
204 * </blockquote>
205 *
206 * <p>
207 * <b>JAXB Runtime Binding Framework Compatibility</b><br>
208 * <blockquote>
209 * The following JAXB 1.0 restriction only applies to binding schema to
210 * interfaces/implementation classes.
211 * Since this binding does not require a common runtime system, a JAXB
212 * client application must not attempt to mix runtime objects (<tt>JAXBContext,
213 * Marshaller</tt>, etc. ) from different providers. This does not
214 * mean that the client application isn't portable, it simply means that a
215 * client has to use a runtime system provided by the same provider that was
216 * used to compile the schema.
217 * </blockquote>
218 *
219 * @author <ul><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul>
220 * @version $Revision: 1.23 $ $Date: 2005/08/31 20:57:57 $
221 * @see Marshaller
222 * @see Unmarshaller
223 * @see <a href="http://java.sun.com/docs/books/jls">S 7.4.1.1 "Package Annotations" in Java Language Specification, 3rd Edition</a>
224 * @since JAXB1.0
225 */
226 public abstract class JAXBContext {
227
228 /**
229 * The name of the property that contains the name of the class capable
230 * of creating new <tt>JAXBContext</tt> objects.
231 */
232 public static final String JAXB_CONTEXT_FACTORY = "javax.xml.bind.context.factory";
233
234 protected JAXBContext() {
235 }
236
237 /**
238 * <p>
239 * Obtain a new instance of a <tt>JAXBContext</tt> class.
240 *
241 * <p>
242 * This is a convenience method for the
243 * {@link #newInstance(String,ClassLoader) newInstance} method. It uses
244 * the context class loader of the current thread. To specify the use of
245 * a different class loader, either set it via the
246 * <tt>Thread.setContextClassLoader()</tt> api or use the
247 * {@link #newInstance(String,ClassLoader) newInstance} method.
248 * @throws JAXBException if an error was encountered while creating the
249 * <tt>JAXBContext</tt> such as
250 * <ol>
251 * <li>failure to locate either ObjectFactory.class or jaxb.index in the packages</li>
252 * <li>an ambiguity among global elements contained in the contextPath</li>
253 * <li>failure to locate a value for the context factory provider property</li>
254 * <li>mixing schema derived packages from different providers on the same contextPath</li>
255 * </ol>
256 */
257 public static JAXBContext newInstance(String contextPath)
258 throws JAXBException {
259
260 //return newInstance( contextPath, JAXBContext.class.getClassLoader() );
261 return newInstance(contextPath, Thread.currentThread()
262 .getContextClassLoader());
263 }
264
265 /**
266 * <p>
267 * Obtain a new instance of a <tt>JAXBContext</tt> class.
268 *
269 * <p>
270 * The client application must supply a context path which is a list of
271 * colon (':', \u005Cu003A) separated java package names that contain
272 * schema-derived classes and/or fully qualified JAXB-annotated classes.
273 * Schema-derived
274 * code is registered with the JAXBContext by the
275 * ObjectFactory.class generated per package.
276 * Alternatively than being listed in the context path, programmer
277 * annotated JAXB mapped classes can be listed in a
278 * <tt>jaxb.index</tt> resource file, format described below.
279 * Note that a java package can contain both schema-derived classes and
280 * user annotated JAXB classes. Additionally, the java package may
281 * contain JAXB package annotations that must be processed. (see JLS 3rd Edition,
282 * Section 7.4.1. "Package Annotations").
283 * </p>
284 *
285 * <p>
286 * Every package listed on the contextPath must meet <b>one or both</b> of the
287 * following conditions otherwise a <tt>JAXBException</tt> will be thrown:
288 * </p>
289 * <ol>
290 * <li>it must contain ObjectFactory.class</li>
291 * <li>it must contain jaxb.index</li>
292 * </ol>
293 *
294 * <p>
295 * <b>Format for jaxb.index</b>
296 * <p>
297 * The file contains a newline-separated list of class names.
298 * Space and tab characters, as well as blank
299 * lines, are ignored. The comment character
300 * is '#' (0x23); on each line all characters following the first comment
301 * character are ignored. The file must be encoded in UTF-8. Classes that
302 * are reachable, as defined in {@link #newInstance(Class...)}, from the
303 * listed classes are also registered with JAXBContext.
304 * <p>
305 * Constraints on class name occuring in a <tt>jaxb.index</tt> file are:
306 * <ul>
307 * <li>Must not end with ".class".</li>
308 * <li>Class names are resolved relative to package containing
309 * <tt>jaxb.index</tt> file. Only classes occuring directly in package
310 * containing <tt>jaxb.index</tt> file are allowed.</li>
311 * <li>Fully qualified class names are not allowed.
312 * A qualified class name,relative to current package,
313 * is only allowed to specify a nested or inner class.</li>
314 * </ul>
315 *
316 * <p>
317 * To maintain compatibility with JAXB 1.0 schema to java
318 * interface/implementation binding, enabled by schema customization
319 * <tt><jaxb:globalBindings valueClass="false"></tt>,
320 * the JAXB provider will ensure that each package on the context path
321 * has a <tt>jaxb.properties</tt> file which contains a value for the
322 * <tt>javax.xml.bind.context.factory</tt> property and that all values
323 * resolve to the same provider. This requirement does not apply to
324 * JAXB annotated classes.
325 *
326 * <p>
327 * If there are any global XML element name collisions across the various
328 * packages listed on the <tt>contextPath</tt>, a <tt>JAXBException</tt>
329 * will be thrown.
330 *
331 * <p>
332 * Mixing generated interface/impl bindings from multiple JAXB Providers
333 * in the same context path may result in a <tt>JAXBException</tt>
334 * being thrown.
335 *
336 * @param contextPath list of java package names that contain schema
337 * derived class and/or java to schema (JAXB-annotated)
338 * mapped classes
339 * @param classLoader
340 * This class loader will be used to locate the implementation
341 * classes.
342 *
343 * @return a new instance of a <tt>JAXBContext</tt>
344 * @throws JAXBException if an error was encountered while creating the
345 * <tt>JAXBContext</tt> such as
346 * <ol>
347 * <li>failure to locate either ObjectFactory.class or jaxb.index in the packages</li>
348 * <li>an ambiguity among global elements contained in the contextPath</li>
349 * <li>failure to locate a value for the context factory provider property</li>
350 * <li>mixing schema derived packages from different providers on the same contextPath</li>
351 * </ol>
352 */
353 public static JAXBContext newInstance(String contextPath,
354 ClassLoader classLoader) throws JAXBException {
355
356 return newInstance(contextPath, classLoader, Collections
357 .<String, Object> emptyMap());
358 }
359
360 /**
361 * <p>
362 * Obtain a new instance of a <tt>JAXBContext</tt> class.
363 *
364 * <p>
365 * This is mostly the same as {@link JAXBContext#newInstance(String, ClassLoader)},
366 * but this version allows you to pass in provider-specific properties to configure
367 * the instanciation of {@link JAXBContext}.
368 *
369 * <p>
370 * The interpretation of properties is up to implementations.
371 *
372 * @param contextPath list of java package names that contain schema derived classes
373 * @param classLoader
374 * This class loader will be used to locate the implementation classes.
375 * @param properties
376 * provider-specific properties
377 *
378 * @return a new instance of a <tt>JAXBContext</tt>
379 * @throws JAXBException if an error was encountered while creating the
380 * <tt>JAXBContext</tt> such as
381 * <ol>
382 * <li>failure to locate either ObjectFactory.class or jaxb.index in the packages</li>
383 * <li>an ambiguity among global elements contained in the contextPath</li>
384 * <li>failure to locate a value for the context factory provider property</li>
385 * <li>mixing schema derived packages from different providers on the same contextPath</li>
386 * </ol>
387 * @since JAXB2.0
388 */
389 public static JAXBContext newInstance(String contextPath,
390 ClassLoader classLoader, Map<String, ?> properties)
391 throws JAXBException {
392
393 return ContextFinder.find(
394 /* The default property name according to the JAXB spec */
395 JAXB_CONTEXT_FACTORY,
396
397 /* the context path supplied by the client app */
398 contextPath,
399
400 /* class loader to be used */
401 classLoader, properties);
402 }
403
404 // TODO: resurrect this once we introduce external annotations
405 // /**
406 // * <p>
407 // * Obtain a new instance of a <tt>JAXBContext</tt> class.
408 // *
409 // * <p>
410 // * The client application must supply a list of classes that the new
411 // * context object needs to recognize.
412 // *
413 // * Not only the new context will recognize all the classes specified,
414 // * but it will also recognize any classes that are directly/indirectly
415 // * referenced statically from the specified classes.
416 // *
417 // * For example, in the following Java code, if you do
418 // * <tt>newInstance(Foo.class)</tt>, the newly created {@link JAXBContext}
419 // * will recognize both <tt>Foo</tt> and <tt>Bar</tt>, but not <tt>Zot</tt>:
420 // * <pre><xmp>
421 // * class Foo {
422 // * Bar b;
423 // * }
424 // * class Bar { int x; }
425 // * class Zot extends Bar { int y; }
426 // * </xmp></pre>
427 // *
428 // * Therefore, a typical client application only needs to specify the
429 // * top-level classes, but it needs to be careful.
430 // *
431 // * TODO: if we are to define other mechanisms, refer to them.
432 // *
433 // * @param externalBindings
434 // * list of external binding files. Can be null or empty if none is used.
435 // * when specified, those files determine how the classes are bound.
436 // *
437 // * @param classesToBeBound
438 // * list of java classes to be recognized by the new {@link JAXBContext}.
439 // * Can be empty, in which case a {@link JAXBContext} that only knows about
440 // * spec-defined classes will be returned.
441 // *
442 // * @return
443 // * A new instance of a <tt>JAXBContext</tt>. Always non-null valid object.
444 // *
445 // * @throws JAXBException
446 // * if an error was encountered while creating the
447 // * <tt>JAXBContext</tt>, such as (but not limited to):
448 // * <ol>
449 // * <li>No JAXB implementation was discovered
450 // * <li>Classes use JAXB annotations incorrectly
451 // * <li>Classes have colliding annotations (i.e., two classes with the same type name)
452 // * <li>Specified external bindings are incorrect
453 // * <li>The JAXB implementation was unable to locate
454 // * provider-specific out-of-band information (such as additional
455 // * files generated at the development time.)
456 // * </ol>
457 // *
458 // * @throws IllegalArgumentException
459 // * if the parameter contains {@code null} (i.e., {@code newInstance(null);})
460 // *
461 // * @since JAXB2.0
462 // */
463 // public static JAXBContext newInstance( Source[] externalBindings, Class... classesToBeBound )
464 // throws JAXBException {
465 //
466 // // empty class list is not an error, because the context will still include
467 // // spec-specified classes like String and Integer.
468 // // if(classesToBeBound.length==0)
469 // // throw new IllegalArgumentException();
470 //
471 // // but it is an error to have nulls in it.
472 // for( int i=classesToBeBound.length-1; i>=0; i-- )
473 // if(classesToBeBound[i]==null)
474 // throw new IllegalArgumentException();
475 //
476 // return ContextFinder.find(externalBindings,classesToBeBound);
477 // }
478
479 /**
480 * <p>
481 * Obtain a new instance of a <tt>JAXBContext</tt> class.
482 *
483 * <p>
484 * The client application must supply a list of classes that the new
485 * context object needs to recognize.
486 *
487 * Not only the new context will recognize all the classes specified,
488 * but it will also recognize any classes that are directly/indirectly
489 * referenced statically from the specified classes. Subclasses of
490 * referenced classes nor <tt>@XmlTransient</tt> referenced classes
491 * are not registered with JAXBContext.
492 *
493 * For example, in the following Java code, if you do
494 * <tt>newInstance(Foo.class)</tt>, the newly created {@link JAXBContext}
495 * will recognize both <tt>Foo</tt> and <tt>Bar</tt>, but not <tt>Zot</tt> or <tt>FooBar</tt>:
496 * <pre>
497 * class Foo {
498 * @XmlTransient FooBar c;
499 * Bar b;
500 * }
501 * class Bar { int x; }
502 * class Zot extends Bar { int y; }
503 * class FooBar { }
504 * </pre>
505 *
506 * Therefore, a typical client application only needs to specify the
507 * top-level classes, but it needs to be careful.
508 *
509 * <p>
510 * Note that for each java package registered with JAXBContext,
511 * when the optional package annotations exist, they must be processed.
512 * (see JLS 3rd Edition, Section 7.4.1. "Package Annotations").
513 *
514 * @param classesToBeBound
515 * list of java classes to be recognized by the new {@link JAXBContext}.
516 * Can be empty, in which case a {@link JAXBContext} that only knows about
517 * spec-defined classes will be returned.
518 *
519 * @return
520 * A new instance of a <tt>JAXBContext</tt>. Always non-null valid object.
521 *
522 * @throws JAXBException
523 * if an error was encountered while creating the
524 * <tt>JAXBContext</tt>, such as (but not limited to):
525 * <ol>
526 * <li>No JAXB implementation was discovered
527 * <li>Classes use JAXB annotations incorrectly
528 * <li>Classes have colliding annotations (i.e., two classes with the same type name)
529 * <li>The JAXB implementation was unable to locate
530 * provider-specific out-of-band information (such as additional
531 * files generated at the development time.)
532 * </ol>
533 *
534 * @throws IllegalArgumentException
535 * if the parameter contains {@code null} (i.e., {@code newInstance(null);})
536 *
537 * @since JAXB2.0
538 */
539 public static JAXBContext newInstance(Class... classesToBeBound)
540 throws JAXBException {
541
542 return newInstance(classesToBeBound, Collections
543 .<String, Object> emptyMap());
544 }
545
546 /**
547 * <p>
548 * Obtain a new instance of a <tt>JAXBContext</tt> class.
549 *
550 * <p>
551 * An overloading of {@link JAXBContext#newInstance(Class...)}
552 * to configure 'properties' for this instantiation of {@link JAXBContext}.
553 *
554 * <p>
555 * The interpretation of properties is implementation specific.
556 *
557 * @param classesToBeBound
558 * list of java classes to be recognized by the new {@link JAXBContext}.
559 * Can be empty, in which case a {@link JAXBContext} that only knows about
560 * spec-defined classes will be returned.
561 *
562 * @return
563 * A new instance of a <tt>JAXBContext</tt>. Always non-null valid object.
564 *
565 * @throws JAXBException
566 * if an error was encountered while creating the
567 * <tt>JAXBContext</tt>, such as (but not limited to):
568 * <ol>
569 * <li>No JAXB implementation was discovered
570 * <li>Classes use JAXB annotations incorrectly
571 * <li>Classes have colliding annotations (i.e., two classes with the same type name)
572 * <li>The JAXB implementation was unable to locate
573 * provider-specific out-of-band information (such as additional
574 * files generated at the development time.)
575 * </ol>
576 *
577 * @throws IllegalArgumentException
578 * if the parameter contains {@code null} (i.e., {@code newInstance(null);})
579 *
580 * @since JAXB2.0
581 */
582 public static JAXBContext newInstance(Class[] classesToBeBound,
583 Map<String, ?> properties) throws JAXBException {
584
585 // empty class list is not an error, because the context will still include
586 // spec-specified classes like String and Integer.
587 // if(classesToBeBound.length==0)
588 // throw new IllegalArgumentException();
589
590 // but it is an error to have nulls in it.
591 for (int i = classesToBeBound.length - 1; i >= 0; i--)
592 if (classesToBeBound[i] == null)
593 throw new IllegalArgumentException();
594
595 return ContextFinder.find(classesToBeBound, properties);
596 }
597
598 /**
599 * Create an <tt>Unmarshaller</tt> object that can be used to convert XML
600 * data into a java content tree.
601 *
602 * @return an <tt>Unmarshaller</tt> object
603 *
604 * @throws JAXBException if an error was encountered while creating the
605 * <tt>Unmarshaller</tt> object
606 */
607 public abstract Unmarshaller createUnmarshaller()
608 throws JAXBException;
609
610 /**
611 * Create a <tt>Marshaller</tt> object that can be used to convert a
612 * java content tree into XML data.
613 *
614 * @return a <tt>Marshaller</tt> object
615 *
616 * @throws JAXBException if an error was encountered while creating the
617 * <tt>Marshaller</tt> object
618 */
619 public abstract Marshaller createMarshaller() throws JAXBException;
620
621 /**
622 * {@link Validator} has been made optional and deprecated in JAXB 2.0. Please
623 * refer to the javadoc for {@link Validator} for more detail.
624 * <p>
625 * Create a <tt>Validator</tt> object that can be used to validate a
626 * java content tree against its source schema.
627 *
628 * @return a <tt>Validator</tt> object
629 *
630 * @throws JAXBException if an error was encountered while creating the
631 * <tt>Validator</tt> object
632 * @deprecated since JAXB2.0
633 */
634 public abstract Validator createValidator() throws JAXBException;
635
636 /**
637 * Creates a <tt>Binder</tt> object that can be used for
638 * associative/in-place unmarshalling/marshalling.
639 *
640 * @param domType select the DOM API to use by passing in its DOM Node class.
641 *
642 * @return always a new valid <tt>Binder</tt> object.
643 *
644 * @throws UnsupportedOperationException
645 * if DOM API corresponding to <tt>domType</tt> is not supported by
646 * the implementation.
647 *
648 * @since JAXB2.0
649 */
650 public <T> Binder<T> createBinder(Class<T> domType) {
651 // to make JAXB 1.0 implementations work, this method must not be
652 // abstract
653 throw new UnsupportedOperationException();
654 }
655
656 /**
657 * Creates a <tt>Binder</tt> for W3C DOM.
658 *
659 * @return always a new valid <tt>Binder</tt> object.
660 *
661 * @since JAXB2.0
662 */
663 public Binder<Node> createBinder() {
664 return createBinder(Node.class);
665 }
666
667 /**
668 * Creates a <tt>JAXBIntrospector</tt> object that can be used to
669 * introspect JAXB objects.
670 *
671 * @return
672 * always return a non-null valid <tt>JAXBIntrospector</tt> object.
673 *
674 * @throws UnsupportedOperationException
675 * Calling this method on JAXB 1.0 implementations will throw
676 * an UnsupportedOperationException.
677 *
678 * @since JAXB2.0
679 */
680 public JAXBIntrospector createJAXBIntrospector() {
681 // to make JAXB 1.0 implementations work, this method must not be
682 // abstract
683 throw new UnsupportedOperationException();
684 }
685
686 /**
687 * Generates the schema documents for this context.
688 *
689 * @param outputResolver
690 * this object controls the output to which schemas
691 * will be sent.
692 *
693 * @throws IOException
694 * if {@link SchemaOutputResolver} throws an {@link IOException}.
695 *
696 * @throws UnsupportedOperationException
697 * Calling this method on JAXB 1.0 implementations will throw
698 * an UnsupportedOperationException.
699 *
700 * @since JAXB 2.0
701 */
702 public void generateSchema(SchemaOutputResolver outputResolver)
703 throws IOException {
704 // to make JAXB 1.0 implementations work, this method must not be
705 // abstract
706 throw new UnsupportedOperationException();
707 }
708 }
|