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