32 import java.util.Properties; |
32 import java.util.Properties; |
33 import java.io.IOException; |
33 import java.io.IOException; |
34 import java.io.InputStream; |
34 import java.io.InputStream; |
35 |
35 |
36 /** |
36 /** |
37 * <p> |
37 * The {@code JAXBContext} class provides the client's entry point to the |
38 * The <tt>JAXBContext</tt> class provides the client's entry point to the |
|
39 * JAXB API. It provides an abstraction for managing the XML/Java binding |
38 * JAXB API. It provides an abstraction for managing the XML/Java binding |
40 * information necessary to implement the JAXB binding framework operations: |
39 * information necessary to implement the JAXB binding framework operations: |
41 * unmarshal, marshal and validate. |
40 * unmarshal, marshal and validate. |
42 * |
41 * |
43 * <p>A client application normally obtains new instances of this class using |
42 * <p>A client application normally obtains new instances of this class using |
60 * </ul> |
59 * </ul> |
61 * |
60 * |
62 * <p><i> |
61 * <p><i> |
63 * The following JAXB 1.0 requirement is only required for schema to |
62 * The following JAXB 1.0 requirement is only required for schema to |
64 * java interface/implementation binding. It does not apply to JAXB annotated |
63 * java interface/implementation binding. It does not apply to JAXB annotated |
65 * classes. JAXB Providers must generate a <tt>jaxb.properties</tt> file in |
64 * classes. JAXB Providers must generate a {@code jaxb.properties} file in |
66 * each package containing schema derived classes. The property file must |
65 * each package containing schema derived classes. The property file must |
67 * contain a property named <tt>javax.xml.bind.context.factory</tt> whose |
66 * contain a property named {@code javax.xml.bind.context.factory} whose |
68 * value is the name of the class that implements the <tt>createContext</tt> |
67 * value is the name of the class that implements the {@code createContext} |
69 * APIs.</i> |
68 * APIs.</i> |
70 * |
69 * |
71 * <p><i> |
70 * <p><i> |
72 * The class supplied by the provider does not have to be assignable to |
71 * The class supplied by the provider does not have to be assignable to |
73 * <tt>javax.xml.bind.JAXBContext</tt>, it simply has to provide a class that |
72 * {@code javax.xml.bind.JAXBContext}, it simply has to provide a class that |
74 * implements the <tt>createContext</tt> APIs.</i> |
73 * implements the {@code createContext} APIs.</i> |
75 * |
74 * |
76 * <p><i> |
75 * <p><i> |
77 * In addition, the provider must call the |
76 * In addition, the provider must call the |
78 * {@link DatatypeConverter#setDatatypeConverter(DatatypeConverterInterface) |
77 * {@link DatatypeConverter#setDatatypeConverter(DatatypeConverterInterface) |
79 * DatatypeConverter.setDatatypeConverter} api prior to any client |
78 * DatatypeConverter.setDatatypeConverter} api prior to any client |
89 * any global XML element declared in the schema to be unmarshalled as |
88 * any global XML element declared in the schema to be unmarshalled as |
90 * the root of an instance document. |
89 * the root of an instance document. |
91 * Additionally, the unmarshal method allows for an unrecognized root element that |
90 * Additionally, the unmarshal method allows for an unrecognized root element that |
92 * has an xsi:type attribute's value that references a type definition declared in |
91 * has an xsi:type attribute's value that references a type definition declared in |
93 * the schema to be unmarshalled as the root of an instance document. |
92 * the schema to be unmarshalled as the root of an instance document. |
94 * The <tt>JAXBContext</tt> object |
93 * The {@code JAXBContext} object |
95 * allows the merging of global elements and type definitions across a set of schemas (listed |
94 * allows the merging of global elements and type definitions across a set of schemas (listed |
96 * in the <tt>contextPath</tt>). Since each schema in the schema set can belong |
95 * in the {@code contextPath}). Since each schema in the schema set can belong |
97 * to distinct namespaces, the unification of schemas to an unmarshalling |
96 * to distinct namespaces, the unification of schemas to an unmarshalling |
98 * context should be namespace independent. This means that a client |
97 * context should be namespace independent. This means that a client |
99 * application is able to unmarshal XML documents that are instances of |
98 * application is able to unmarshal XML documents that are instances of |
100 * any of the schemas listed in the <tt>contextPath</tt>. For example: |
99 * any of the schemas listed in the {@code contextPath}. For example: |
101 * |
100 * |
102 * <pre> |
101 * <pre> |
103 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo:com.acme.bar" ); |
102 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo:com.acme.bar" ); |
104 * Unmarshaller u = jc.createUnmarshaller(); |
103 * Unmarshaller u = jc.createUnmarshaller(); |
105 * FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) ); // ok |
104 * FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) ); // ok |
112 * than unmarshalling existing XML data. For all JAXB-annotated value classes, |
111 * than unmarshalling existing XML data. For all JAXB-annotated value classes, |
113 * an application can create content using constructors. |
112 * an application can create content using constructors. |
114 * For schema-derived interface/implementation classes and for the |
113 * For schema-derived interface/implementation classes and for the |
115 * creation of elements that are not bound to a JAXB-annotated |
114 * creation of elements that are not bound to a JAXB-annotated |
116 * class, an application needs to have access and knowledge about each of |
115 * class, an application needs to have access and knowledge about each of |
117 * the schema derived <tt> ObjectFactory</tt> classes that exist in each of |
116 * the schema derived {@code ObjectFactory} classes that exist in each of |
118 * java packages contained in the <tt>contextPath</tt>. For each schema |
117 * java packages contained in the {@code contextPath}. For each schema |
119 * derived java class, there is a static factory method that produces objects |
118 * derived java class, there is a static factory method that produces objects |
120 * of that type. For example, |
119 * of that type. For example, |
121 * assume that after compiling a schema, you have a package <tt>com.acme.foo</tt> |
120 * assume that after compiling a schema, you have a package {@code com.acme.foo} |
122 * that contains a schema derived interface named <tt>PurchaseOrder</tt>. In |
121 * that contains a schema derived interface named {@code PurchaseOrder}. In |
123 * order to create objects of that type, the client application would use the |
122 * order to create objects of that type, the client application would use the |
124 * factory method like this: |
123 * factory method like this: |
125 * |
124 * |
126 * <pre> |
125 * <pre> |
127 * com.acme.foo.PurchaseOrder po = |
126 * com.acme.foo.PurchaseOrder po = |
131 * <p> |
130 * <p> |
132 * Once the client application has an instance of the the schema derived object, |
131 * Once the client application has an instance of the the schema derived object, |
133 * it can use the mutator methods to set content on it. |
132 * it can use the mutator methods to set content on it. |
134 * |
133 * |
135 * <p> |
134 * <p> |
136 * For more information on the generated <tt>ObjectFactory</tt> classes, see |
135 * For more information on the generated {@code ObjectFactory} classes, see |
137 * Section 4.2 <i>Java Package</i> of the specification. |
136 * Section 4.2 <i>Java Package</i> of the specification. |
138 * |
137 * |
139 * <p> |
138 * <p> |
140 * <i>The provider must generate a class in each |
139 * <i>The provider must generate a class in each |
141 * package that contains all of the necessary object factory methods for that |
140 * package that contains all of the necessary object factory methods for that |
142 * package named ObjectFactory as well as the static |
141 * package named ObjectFactory as well as the static |
143 * <tt>newInstance( javaContentInterface )</tt> method</i> |
142 * {@code newInstance( javaContentInterface )} method</i> |
144 * |
143 * |
145 * <h3>Marshalling</h3> |
144 * <h3>Marshalling</h3> |
146 * <p> |
145 * <p> |
147 * The {@link Marshaller} class provides the client application the ability |
146 * The {@link Marshaller} class provides the client application the ability |
148 * to convert a Java content tree back into XML data. There is no difference |
147 * to convert a Java content tree back into XML data. There is no difference |
149 * between marshalling a content tree that is created manually using the factory |
148 * between marshalling a content tree that is created manually using the factory |
150 * methods and marshalling a content tree that is the result an <tt>unmarshal |
149 * methods and marshalling a content tree that is the result an {@code unmarshal} |
151 * </tt> operation. Clients can marshal a java content tree back to XML data |
150 * operation. Clients can marshal a java content tree back to XML data |
152 * to a <tt>java.io.OutputStream</tt> or a <tt>java.io.Writer</tt>. The |
151 * to a {@code java.io.OutputStream} or a {@code java.io.Writer}. The |
153 * marshalling process can alternatively produce SAX2 event streams to a |
152 * marshalling process can alternatively produce SAX2 event streams to a |
154 * registered <tt>ContentHandler</tt> or produce a DOM Node object. |
153 * registered {@code ContentHandler} or produce a DOM Node object. |
155 * Client applications have control over the output encoding as well as |
154 * Client applications have control over the output encoding as well as |
156 * whether or not to marshal the XML data as a complete document or |
155 * whether or not to marshal the XML data as a complete document or |
157 * as a fragment. |
156 * as a fragment. |
158 * |
157 * |
159 * <p> |
158 * <p> |
176 * <h3>Validation</h3> |
175 * <h3>Validation</h3> |
177 * <p> |
176 * <p> |
178 * Validation has been changed significantly since JAXB 1.0. The {@link Validator} |
177 * Validation has been changed significantly since JAXB 1.0. The {@link Validator} |
179 * class has been deprecated and made optional. This means that you are advised |
178 * class has been deprecated and made optional. This means that you are advised |
180 * not to use this class and, in fact, it may not even be available depending on |
179 * not to use this class and, in fact, it may not even be available depending on |
181 * your JAXB provider. JAXB 1.0 client applications that rely on <tt>Validator</tt> |
180 * your JAXB provider. JAXB 1.0 client applications that rely on {@code Validator} |
182 * will still work properly when deployed with the JAXB 1.0 runtime system. |
181 * will still work properly when deployed with the JAXB 1.0 runtime system. |
183 * |
182 * |
184 * In JAXB 2.0, the {@link Unmarshaller} has included convenince methods that expose |
183 * In JAXB 2.0, the {@link Unmarshaller} has included convenince methods that expose |
185 * the JAXP 1.3 {@link javax.xml.validation} framework. Please refer to the |
184 * the JAXP 1.3 {@link javax.xml.validation} framework. Please refer to the |
186 * {@link Unmarshaller#setSchema(javax.xml.validation.Schema)} API for more |
185 * {@link Unmarshaller#setSchema(javax.xml.validation.Schema)} API for more |
190 * <h3>JAXB Runtime Binding Framework Compatibility</h3> |
189 * <h3>JAXB Runtime Binding Framework Compatibility</h3> |
191 * <p> |
190 * <p> |
192 * The following JAXB 1.0 restriction only applies to binding schema to |
191 * The following JAXB 1.0 restriction only applies to binding schema to |
193 * interfaces/implementation classes. |
192 * interfaces/implementation classes. |
194 * Since this binding does not require a common runtime system, a JAXB |
193 * Since this binding does not require a common runtime system, a JAXB |
195 * client application must not attempt to mix runtime objects (<tt>JAXBContext, |
194 * client application must not attempt to mix runtime objects ({@code JAXBContext, |
196 * Marshaller</tt>, etc. ) from different providers. This does not |
195 * Marshaller}, etc. ) from different providers. This does not |
197 * mean that the client application isn't portable, it simply means that a |
196 * mean that the client application isn't portable, it simply means that a |
198 * client has to use a runtime system provided by the same provider that was |
197 * client has to use a runtime system provided by the same provider that was |
199 * used to compile the schema. |
198 * used to compile the schema. |
200 * |
199 * |
201 * |
200 * |
202 * <h3>Discovery of JAXB implementation</h3> |
201 * <h3>Discovery of JAXB implementation</h3> |
203 * <p> |
202 * <p> |
204 * When one of the <tt>newInstance</tt> methods is called, a JAXB implementation is discovered |
203 * When one of the {@code newInstance} methods is called, a JAXB implementation is discovered |
205 * by the following steps. |
204 * by the following steps. |
206 * |
205 * |
207 * <ol> |
206 * <ol> |
208 * |
207 * |
209 * <li> |
208 * <li> |
210 * For each package/class explicitly passed in to the {@link #newInstance} method, in the order they are specified, |
209 * For each package/class explicitly passed in to the {@link #newInstance} method, in the order they are specified, |
211 * <tt>jaxb.properties</tt> file is looked up in its package, by using the associated classloader — |
210 * {@code jaxb.properties} file is looked up in its package, by using the associated classloader — |
212 * this is {@link Class#getClassLoader() the owner class loader} for a {@link Class} argument, and for a package |
211 * this is {@link Class#getClassLoader() the owner class loader} for a {@link Class} argument, and for a package |
213 * the specified {@link ClassLoader}. |
212 * the specified {@link ClassLoader}. |
214 * |
213 * |
215 * <p> |
214 * <p> |
216 * If such a file is discovered, it is {@link Properties#load(InputStream) loaded} as a property file, and |
215 * If such a file is discovered, it is {@link Properties#load(InputStream) loaded} as a property file, and |
267 * Once the provider factory class {@link javax.xml.bind.JAXBContextFactory} is discovered, one of its methods |
266 * Once the provider factory class {@link javax.xml.bind.JAXBContextFactory} is discovered, one of its methods |
268 * {@link javax.xml.bind.JAXBContextFactory#createContext(String, ClassLoader, java.util.Map)} or |
267 * {@link javax.xml.bind.JAXBContextFactory#createContext(String, ClassLoader, java.util.Map)} or |
269 * {@link javax.xml.bind.JAXBContextFactory#createContext(Class[], java.util.Map)} is invoked |
268 * {@link javax.xml.bind.JAXBContextFactory#createContext(Class[], java.util.Map)} is invoked |
270 * to create a {@link JAXBContext}. |
269 * to create a {@link JAXBContext}. |
271 * |
270 * |
272 * <p/> |
|
273 * |
|
274 * @apiNote |
271 * @apiNote |
275 * <p>Service discovery method using file /META-INF/services/javax.xml.bind.JAXBContext (described in step 4) |
272 * <p>Service discovery method using file /META-INF/services/javax.xml.bind.JAXBContext (described in step 4) |
276 * and leveraging provider's static methods is supported only to allow backwards compatibility, but it is strongly |
273 * and leveraging provider's static methods is supported only to allow backwards compatibility, but it is strongly |
277 * recommended to migrate to standard ServiceLoader mechanism (described in step 3). |
274 * recommended to migrate to standard ServiceLoader mechanism (described in step 3). |
278 * |
275 * |
292 */ |
289 */ |
293 public abstract class JAXBContext { |
290 public abstract class JAXBContext { |
294 |
291 |
295 /** |
292 /** |
296 * The name of the property that contains the name of the class capable |
293 * The name of the property that contains the name of the class capable |
297 * of creating new <tt>JAXBContext</tt> objects. |
294 * of creating new {@code JAXBContext} objects. |
298 */ |
295 */ |
299 public static final String JAXB_CONTEXT_FACTORY = "javax.xml.bind.JAXBContextFactory"; |
296 public static final String JAXB_CONTEXT_FACTORY = "javax.xml.bind.JAXBContextFactory"; |
300 |
297 |
301 protected JAXBContext() { |
298 protected JAXBContext() { |
302 } |
299 } |
303 |
300 |
304 |
301 |
305 /** |
302 /** |
306 * <p> |
303 * Create a new instance of a {@code JAXBContext} class. |
307 * Create a new instance of a <tt>JAXBContext</tt> class. |
|
308 * |
304 * |
309 * <p> |
305 * <p> |
310 * This is a convenience method to invoke the |
306 * This is a convenience method to invoke the |
311 * {@link #newInstance(String,ClassLoader)} method with |
307 * {@link #newInstance(String,ClassLoader)} method with |
312 * the context class loader of the current thread. |
308 * the context class loader of the current thread. |
313 * |
309 * |
314 * @throws JAXBException if an error was encountered while creating the |
310 * @throws JAXBException if an error was encountered while creating the |
315 * <tt>JAXBContext</tt> such as |
311 * {@code JAXBContext} such as |
316 * <ol> |
312 * <ol> |
317 * <li>failure to locate either ObjectFactory.class or jaxb.index in the packages</li> |
313 * <li>failure to locate either ObjectFactory.class or jaxb.index in the packages</li> |
318 * <li>an ambiguity among global elements contained in the contextPath</li> |
314 * <li>an ambiguity among global elements contained in the contextPath</li> |
319 * <li>failure to locate a value for the context factory provider property</li> |
315 * <li>failure to locate a value for the context factory provider property</li> |
320 * <li>mixing schema derived packages from different providers on the same contextPath</li> |
316 * <li>mixing schema derived packages from different providers on the same contextPath</li> |
326 //return newInstance( contextPath, JAXBContext.class.getClassLoader() ); |
322 //return newInstance( contextPath, JAXBContext.class.getClassLoader() ); |
327 return newInstance( contextPath, getContextClassLoader()); |
323 return newInstance( contextPath, getContextClassLoader()); |
328 } |
324 } |
329 |
325 |
330 /** |
326 /** |
331 * <p> |
327 * Create a new instance of a {@code JAXBContext} class. |
332 * Create a new instance of a <tt>JAXBContext</tt> class. |
|
333 * |
328 * |
334 * <p> |
329 * <p> |
335 * The client application must supply a context path which is a list of |
330 * The client application must supply a context path which is a list of |
336 * colon (':', \u005Cu003A) separated java package names that contain |
331 * colon (':', \u005Cu003A) separated java package names that contain |
337 * schema-derived classes and/or fully qualified JAXB-annotated classes. |
332 * schema-derived classes and/or fully qualified JAXB-annotated classes. |
338 * Schema-derived |
333 * Schema-derived |
339 * code is registered with the JAXBContext by the |
334 * code is registered with the JAXBContext by the |
340 * ObjectFactory.class generated per package. |
335 * ObjectFactory.class generated per package. |
341 * Alternatively than being listed in the context path, programmer |
336 * Alternatively than being listed in the context path, programmer |
342 * annotated JAXB mapped classes can be listed in a |
337 * annotated JAXB mapped classes can be listed in a |
343 * <tt>jaxb.index</tt> resource file, format described below. |
338 * {@code jaxb.index} resource file, format described below. |
344 * Note that a java package can contain both schema-derived classes and |
339 * Note that a java package can contain both schema-derived classes and |
345 * user annotated JAXB classes. Additionally, the java package may |
340 * user annotated JAXB classes. Additionally, the java package may |
346 * contain JAXB package annotations that must be processed. (see JLS, |
341 * contain JAXB package annotations that must be processed. (see JLS, |
347 * Section 7.4.1 "Named Packages"). |
342 * Section 7.4.1 "Named Packages"). |
348 * </p> |
343 * </p> |
349 * |
344 * |
350 * <p> |
345 * <p> |
351 * Every package listed on the contextPath must meet <b>one or both</b> of the |
346 * Every package listed on the contextPath must meet <b>one or both</b> of the |
352 * following conditions otherwise a <tt>JAXBException</tt> will be thrown: |
347 * following conditions otherwise a {@code JAXBException} will be thrown: |
353 * </p> |
348 * </p> |
354 * <ol> |
349 * <ol> |
355 * <li>it must contain ObjectFactory.class</li> |
350 * <li>it must contain ObjectFactory.class</li> |
356 * <li>it must contain jaxb.index</li> |
351 * <li>it must contain jaxb.index</li> |
357 * </ol> |
352 * </ol> |
365 * is '#' (0x23); on each line all characters following the first comment |
360 * is '#' (0x23); on each line all characters following the first comment |
366 * character are ignored. The file must be encoded in UTF-8. Classes that |
361 * character are ignored. The file must be encoded in UTF-8. Classes that |
367 * are reachable, as defined in {@link #newInstance(Class...)}, from the |
362 * are reachable, as defined in {@link #newInstance(Class...)}, from the |
368 * listed classes are also registered with JAXBContext. |
363 * listed classes are also registered with JAXBContext. |
369 * <p> |
364 * <p> |
370 * Constraints on class name occuring in a <tt>jaxb.index</tt> file are: |
365 * Constraints on class name occuring in a {@code jaxb.index} file are: |
371 * <ul> |
366 * <ul> |
372 * <li>Must not end with ".class".</li> |
367 * <li>Must not end with ".class".</li> |
373 * <li>Class names are resolved relative to package containing |
368 * <li>Class names are resolved relative to package containing |
374 * <tt>jaxb.index</tt> file. Only classes occuring directly in package |
369 * {@code jaxb.index} file. Only classes occuring directly in package |
375 * containing <tt>jaxb.index</tt> file are allowed.</li> |
370 * containing {@code jaxb.index} file are allowed.</li> |
376 * <li>Fully qualified class names are not allowed. |
371 * <li>Fully qualified class names are not allowed. |
377 * A qualified class name,relative to current package, |
372 * A qualified class name,relative to current package, |
378 * is only allowed to specify a nested or inner class.</li> |
373 * is only allowed to specify a nested or inner class.</li> |
379 * </ul> |
374 * </ul> |
380 * |
375 * |
381 * <p> |
376 * <p> |
382 * To maintain compatibility with JAXB 1.0 schema to java |
377 * To maintain compatibility with JAXB 1.0 schema to java |
383 * interface/implementation binding, enabled by schema customization |
378 * interface/implementation binding, enabled by schema customization |
384 * <tt>{@literal <jaxb:globalBindings valueClass="false">}</tt>, |
379 * {@code <jaxb:globalBindings valueClass="false">}, |
385 * the JAXB provider will ensure that each package on the context path |
380 * the JAXB provider will ensure that each package on the context path |
386 * has a <tt>jaxb.properties</tt> file which contains a value for the |
381 * has a {@code jaxb.properties} file which contains a value for the |
387 * <tt>javax.xml.bind.context.factory</tt> property and that all values |
382 * {@code javax.xml.bind.context.factory} property and that all values |
388 * resolve to the same provider. This requirement does not apply to |
383 * resolve to the same provider. This requirement does not apply to |
389 * JAXB annotated classes. |
384 * JAXB annotated classes. |
390 * |
385 * |
391 * <p> |
386 * <p> |
392 * If there are any global XML element name collisions across the various |
387 * If there are any global XML element name collisions across the various |
393 * packages listed on the <tt>contextPath</tt>, a <tt>JAXBException</tt> |
388 * packages listed on the {@code contextPath}, a {@code JAXBException} |
394 * will be thrown. |
389 * will be thrown. |
395 * |
390 * |
396 * <p> |
391 * <p> |
397 * Mixing generated interface/impl bindings from multiple JAXB Providers |
392 * Mixing generated interface/impl bindings from multiple JAXB Providers |
398 * in the same context path may result in a <tt>JAXBException</tt> |
393 * in the same context path may result in a {@code JAXBException} |
399 * being thrown. |
394 * being thrown. |
400 * |
395 * |
401 * <p> |
396 * <p> |
402 * The steps involved in discovering the JAXB implementation is discussed in the class javadoc. |
397 * The steps involved in discovering the JAXB implementation is discussed in the class javadoc. |
403 * |
398 * |
406 * mapped classes |
401 * mapped classes |
407 * @param classLoader |
402 * @param classLoader |
408 * This class loader will be used to locate the implementation |
403 * This class loader will be used to locate the implementation |
409 * classes. |
404 * classes. |
410 * |
405 * |
411 * @return a new instance of a <tt>JAXBContext</tt> |
406 * @return a new instance of a {@code JAXBContext} |
412 * @throws JAXBException if an error was encountered while creating the |
407 * @throws JAXBException if an error was encountered while creating the |
413 * <tt>JAXBContext</tt> such as |
408 * {@code JAXBContext} such as |
414 * <ol> |
409 * <ol> |
415 * <li>failure to locate either ObjectFactory.class or jaxb.index in the packages</li> |
410 * <li>failure to locate either ObjectFactory.class or jaxb.index in the packages</li> |
416 * <li>an ambiguity among global elements contained in the contextPath</li> |
411 * <li>an ambiguity among global elements contained in the contextPath</li> |
417 * <li>failure to locate a value for the context factory provider property</li> |
412 * <li>failure to locate a value for the context factory provider property</li> |
418 * <li>mixing schema derived packages from different providers on the same contextPath</li> |
413 * <li>mixing schema derived packages from different providers on the same contextPath</li> |
422 |
417 |
423 return newInstance(contextPath,classLoader,Collections.<String,Object>emptyMap()); |
418 return newInstance(contextPath,classLoader,Collections.<String,Object>emptyMap()); |
424 } |
419 } |
425 |
420 |
426 /** |
421 /** |
427 * <p> |
422 * Create a new instance of a {@code JAXBContext} class. |
428 * Create a new instance of a <tt>JAXBContext</tt> class. |
|
429 * |
423 * |
430 * <p> |
424 * <p> |
431 * This is mostly the same as {@link JAXBContext#newInstance(String, ClassLoader)}, |
425 * This is mostly the same as {@link JAXBContext#newInstance(String, ClassLoader)}, |
432 * but this version allows you to pass in provider-specific properties to configure |
426 * but this version allows you to pass in provider-specific properties to configure |
433 * the instantiation of {@link JAXBContext}. |
427 * the instantiation of {@link JAXBContext}. |
434 * |
428 * |
435 * <p> |
429 * <p> |
436 * The interpretation of properties is up to implementations. Implementations should |
430 * The interpretation of properties is up to implementations. Implementations should |
437 * throw <tt>JAXBException</tt> if it finds properties that it doesn't understand. |
431 * throw {@code JAXBException} if it finds properties that it doesn't understand. |
438 * |
432 * |
439 * @param contextPath list of java package names that contain schema derived classes |
433 * @param contextPath list of java package names that contain schema derived classes |
440 * @param classLoader |
434 * @param classLoader |
441 * This class loader will be used to locate the implementation classes. |
435 * This class loader will be used to locate the implementation classes. |
442 * @param properties |
436 * @param properties |
443 * provider-specific properties. Can be null, which means the same thing as passing |
437 * provider-specific properties. Can be null, which means the same thing as passing |
444 * in an empty map. |
438 * in an empty map. |
445 * |
439 * |
446 * @return a new instance of a <tt>JAXBContext</tt> |
440 * @return a new instance of a {@code JAXBContext} |
447 * @throws JAXBException if an error was encountered while creating the |
441 * @throws JAXBException if an error was encountered while creating the |
448 * <tt>JAXBContext</tt> such as |
442 * {@code JAXBContext} such as |
449 * <ol> |
443 * <ol> |
450 * <li>failure to locate either ObjectFactory.class or jaxb.index in the packages</li> |
444 * <li>failure to locate either ObjectFactory.class or jaxb.index in the packages</li> |
451 * <li>an ambiguity among global elements contained in the contextPath</li> |
445 * <li>an ambiguity among global elements contained in the contextPath</li> |
452 * <li>failure to locate a value for the context factory provider property</li> |
446 * <li>failure to locate a value for the context factory provider property</li> |
453 * <li>mixing schema derived packages from different providers on the same contextPath</li> |
447 * <li>mixing schema derived packages from different providers on the same contextPath</li> |
470 properties ); |
464 properties ); |
471 } |
465 } |
472 |
466 |
473 // TODO: resurrect this once we introduce external annotations |
467 // TODO: resurrect this once we introduce external annotations |
474 // /** |
468 // /** |
475 // * <p> |
469 // * Create a new instance of a {@code JAXBContext} class. |
476 // * Create a new instance of a <tt>JAXBContext</tt> class. |
|
477 // * |
470 // * |
478 // * <p> |
471 // * <p> |
479 // * The client application must supply a list of classes that the new |
472 // * The client application must supply a list of classes that the new |
480 // * context object needs to recognize. |
473 // * context object needs to recognize. |
481 // * |
474 // * |
482 // * Not only the new context will recognize all the classes specified, |
475 // * Not only the new context will recognize all the classes specified, |
483 // * but it will also recognize any classes that are directly/indirectly |
476 // * but it will also recognize any classes that are directly/indirectly |
484 // * referenced statically from the specified classes. |
477 // * referenced statically from the specified classes. |
485 // * |
478 // * |
486 // * For example, in the following Java code, if you do |
479 // * For example, in the following Java code, if you do |
487 // * <tt>newInstance(Foo.class)</tt>, the newly created {@link JAXBContext} |
480 // * {@code newInstance(Foo.class)}, the newly created {@link JAXBContext} |
488 // * will recognize both <tt>Foo</tt> and <tt>Bar</tt>, but not <tt>Zot</tt>: |
481 // * will recognize both {@code Foo} and {@code Bar}, but not {@code Zot}: |
489 // * <pre> |
482 // * <pre> |
490 // * class Foo { |
483 // * class Foo { |
491 // * Bar b; |
484 // * Bar b; |
492 // * } |
485 // * } |
493 // * class Bar { int x; } |
486 // * class Bar { int x; } |
507 // * list of java classes to be recognized by the new {@link JAXBContext}. |
500 // * list of java classes to be recognized by the new {@link JAXBContext}. |
508 // * Can be empty, in which case a {@link JAXBContext} that only knows about |
501 // * Can be empty, in which case a {@link JAXBContext} that only knows about |
509 // * spec-defined classes will be returned. |
502 // * spec-defined classes will be returned. |
510 // * |
503 // * |
511 // * @return |
504 // * @return |
512 // * A new instance of a <tt>JAXBContext</tt>. |
505 // * A new instance of a {@code JAXBContext}. |
513 // * |
506 // * |
514 // * @throws JAXBException |
507 // * @throws JAXBException |
515 // * if an error was encountered while creating the |
508 // * if an error was encountered while creating the |
516 // * <tt>JAXBContext</tt>, such as (but not limited to): |
509 // * {@code JAXBContext}, such as (but not limited to): |
517 // * <ol> |
510 // * <ol> |
518 // * <li>No JAXB implementation was discovered |
511 // * <li>No JAXB implementation was discovered |
519 // * <li>Classes use JAXB annotations incorrectly |
512 // * <li>Classes use JAXB annotations incorrectly |
520 // * <li>Classes have colliding annotations (i.e., two classes with the same type name) |
513 // * <li>Classes have colliding annotations (i.e., two classes with the same type name) |
521 // * <li>Specified external bindings are incorrect |
514 // * <li>Specified external bindings are incorrect |
544 // |
537 // |
545 // return ContextFinder.find(externalBindings,classesToBeBound); |
538 // return ContextFinder.find(externalBindings,classesToBeBound); |
546 // } |
539 // } |
547 |
540 |
548 /** |
541 /** |
549 * <p> |
542 * Create a new instance of a {@code JAXBContext} class. |
550 * Create a new instance of a <tt>JAXBContext</tt> class. |
|
551 * |
543 * |
552 * <p> |
544 * <p> |
553 * The client application must supply a list of classes that the new |
545 * The client application must supply a list of classes that the new |
554 * context object needs to recognize. |
546 * context object needs to recognize. |
555 * |
547 * |
556 * Not only the new context will recognize all the classes specified, |
548 * Not only the new context will recognize all the classes specified, |
557 * but it will also recognize any classes that are directly/indirectly |
549 * but it will also recognize any classes that are directly/indirectly |
558 * referenced statically from the specified classes. Subclasses of |
550 * referenced statically from the specified classes. Subclasses of |
559 * referenced classes nor <tt>@XmlTransient</tt> referenced classes |
551 * referenced classes nor {@code @XmlTransient} referenced classes |
560 * are not registered with JAXBContext. |
552 * are not registered with JAXBContext. |
561 * |
553 * |
562 * For example, in the following Java code, if you do |
554 * For example, in the following Java code, if you do |
563 * <tt>newInstance(Foo.class)</tt>, the newly created {@link JAXBContext} |
555 * {@code newInstance(Foo.class)}, the newly created {@link JAXBContext} |
564 * will recognize both <tt>Foo</tt> and <tt>Bar</tt>, but not <tt>Zot</tt> or <tt>FooBar</tt>: |
556 * will recognize both {@code Foo} and {@code Bar}, but not {@code Zot} or {@code FooBar}: |
565 * <pre> |
557 * <pre> |
566 * class Foo { |
558 * class Foo { |
567 * @XmlTransient FooBar c; |
559 * @XmlTransient FooBar c; |
568 * Bar b; |
560 * Bar b; |
569 * } |
561 * } |
587 * list of java classes to be recognized by the new {@link JAXBContext}. |
579 * list of java classes to be recognized by the new {@link JAXBContext}. |
588 * Can be empty, in which case a {@link JAXBContext} that only knows about |
580 * Can be empty, in which case a {@link JAXBContext} that only knows about |
589 * spec-defined classes will be returned. |
581 * spec-defined classes will be returned. |
590 * |
582 * |
591 * @return |
583 * @return |
592 * A new instance of a <tt>JAXBContext</tt>. |
584 * A new instance of a {@code JAXBContext}. |
593 * |
585 * |
594 * @throws JAXBException |
586 * @throws JAXBException |
595 * if an error was encountered while creating the |
587 * if an error was encountered while creating the |
596 * <tt>JAXBContext</tt>, such as (but not limited to): |
588 * {@code JAXBContext}, such as (but not limited to): |
597 * <ol> |
589 * <ol> |
598 * <li>No JAXB implementation was discovered |
590 * <li>No JAXB implementation was discovered |
599 * <li>Classes use JAXB annotations incorrectly |
591 * <li>Classes use JAXB annotations incorrectly |
600 * <li>Classes have colliding annotations (i.e., two classes with the same type name) |
592 * <li>Classes have colliding annotations (i.e., two classes with the same type name) |
601 * <li>The JAXB implementation was unable to locate |
593 * <li>The JAXB implementation was unable to locate |
613 |
605 |
614 return newInstance(classesToBeBound,Collections.<String,Object>emptyMap()); |
606 return newInstance(classesToBeBound,Collections.<String,Object>emptyMap()); |
615 } |
607 } |
616 |
608 |
617 /** |
609 /** |
618 * <p> |
610 * Create a new instance of a {@code JAXBContext} class. |
619 * Create a new instance of a <tt>JAXBContext</tt> class. |
|
620 * |
611 * |
621 * <p> |
612 * <p> |
622 * An overloading of {@link JAXBContext#newInstance(Class...)} |
613 * An overloading of {@link JAXBContext#newInstance(Class...)} |
623 * to configure 'properties' for this instantiation of {@link JAXBContext}. |
614 * to configure 'properties' for this instantiation of {@link JAXBContext}. |
624 * |
615 * |
625 * <p> |
616 * <p> |
626 * The interpretation of properties is up to implementations. Implementations should |
617 * The interpretation of properties is up to implementations. Implementations should |
627 * throw <tt>JAXBException</tt> if it finds properties that it doesn't understand. |
618 * throw {@code JAXBException} if it finds properties that it doesn't understand. |
628 * |
619 * |
629 * @param classesToBeBound |
620 * @param classesToBeBound |
630 * list of java classes to be recognized by the new {@link JAXBContext}. |
621 * list of java classes to be recognized by the new {@link JAXBContext}. |
631 * Can be empty, in which case a {@link JAXBContext} that only knows about |
622 * Can be empty, in which case a {@link JAXBContext} that only knows about |
632 * spec-defined classes will be returned. |
623 * spec-defined classes will be returned. |
633 * @param properties |
624 * @param properties |
634 * provider-specific properties. Can be null, which means the same thing as passing |
625 * provider-specific properties. Can be null, which means the same thing as passing |
635 * in an empty map. |
626 * in an empty map. |
636 * |
627 * |
637 * @return |
628 * @return |
638 * A new instance of a <tt>JAXBContext</tt>. |
629 * A new instance of a {@code JAXBContext}. |
639 * |
630 * |
640 * @throws JAXBException |
631 * @throws JAXBException |
641 * if an error was encountered while creating the |
632 * if an error was encountered while creating the |
642 * <tt>JAXBContext</tt>, such as (but not limited to): |
633 * {@code JAXBContext}, such as (but not limited to): |
643 * <ol> |
634 * <ol> |
644 * <li>No JAXB implementation was discovered |
635 * <li>No JAXB implementation was discovered |
645 * <li>Classes use JAXB annotations incorrectly |
636 * <li>Classes use JAXB annotations incorrectly |
646 * <li>Classes have colliding annotations (i.e., two classes with the same type name) |
637 * <li>Classes have colliding annotations (i.e., two classes with the same type name) |
647 * <li>The JAXB implementation was unable to locate |
638 * <li>The JAXB implementation was unable to locate |
670 |
661 |
671 return ContextFinder.find(classesToBeBound,properties); |
662 return ContextFinder.find(classesToBeBound,properties); |
672 } |
663 } |
673 |
664 |
674 /** |
665 /** |
675 * Create an <tt>Unmarshaller</tt> object that can be used to convert XML |
666 * Create an {@code Unmarshaller} object that can be used to convert XML |
676 * data into a java content tree. |
667 * data into a java content tree. |
677 * |
668 * |
678 * @return an <tt>Unmarshaller</tt> object |
669 * @return an {@code Unmarshaller} object |
679 * |
670 * |
680 * @throws JAXBException if an error was encountered while creating the |
671 * @throws JAXBException if an error was encountered while creating the |
681 * <tt>Unmarshaller</tt> object |
672 * {@code Unmarshaller} object |
682 */ |
673 */ |
683 public abstract Unmarshaller createUnmarshaller() throws JAXBException; |
674 public abstract Unmarshaller createUnmarshaller() throws JAXBException; |
684 |
675 |
685 |
676 |
686 /** |
677 /** |
687 * Create a <tt>Marshaller</tt> object that can be used to convert a |
678 * Create a {@code Marshaller} object that can be used to convert a |
688 * java content tree into XML data. |
679 * java content tree into XML data. |
689 * |
680 * |
690 * @return a <tt>Marshaller</tt> object |
681 * @return a {@code Marshaller} object |
691 * |
682 * |
692 * @throws JAXBException if an error was encountered while creating the |
683 * @throws JAXBException if an error was encountered while creating the |
693 * <tt>Marshaller</tt> object |
684 * {@code Marshaller} object |
694 */ |
685 */ |
695 public abstract Marshaller createMarshaller() throws JAXBException; |
686 public abstract Marshaller createMarshaller() throws JAXBException; |
696 |
687 |
697 |
688 |
698 /** |
689 /** |
699 * {@link Validator} has been made optional and deprecated in JAXB 2.0. Please |
690 * {@link Validator} has been made optional and deprecated in JAXB 2.0. Please |
700 * refer to the javadoc for {@link Validator} for more detail. |
691 * refer to the javadoc for {@link Validator} for more detail. |
701 * <p> |
692 * <p> |
702 * Create a <tt>Validator</tt> object that can be used to validate a |
693 * Create a {@code Validator} object that can be used to validate a |
703 * java content tree against its source schema. |
694 * java content tree against its source schema. |
704 * |
695 * |
705 * @return a <tt>Validator</tt> object |
696 * @return a {@code Validator} object |
706 * |
697 * |
707 * @throws JAXBException if an error was encountered while creating the |
698 * @throws JAXBException if an error was encountered while creating the |
708 * <tt>Validator</tt> object |
699 * {@code Validator} object |
709 * @deprecated since JAXB2.0 |
700 * @deprecated since JAXB2.0 |
710 */ |
701 */ |
711 public abstract Validator createValidator() throws JAXBException; |
702 public abstract Validator createValidator() throws JAXBException; |
712 |
703 |
713 /** |
704 /** |
714 * Creates a <tt>Binder</tt> object that can be used for |
705 * Creates a {@code Binder} object that can be used for |
715 * associative/in-place unmarshalling/marshalling. |
706 * associative/in-place unmarshalling/marshalling. |
716 * |
707 * |
717 * @param domType select the DOM API to use by passing in its DOM Node class. |
708 * @param domType select the DOM API to use by passing in its DOM Node class. |
718 * |
709 * |
719 * @return always a new valid <tt>Binder</tt> object. |
710 * @return always a new valid {@code Binder} object. |
720 * |
711 * |
721 * @throws UnsupportedOperationException |
712 * @throws UnsupportedOperationException |
722 * if DOM API corresponding to <tt>domType</tt> is not supported by |
713 * if DOM API corresponding to {@code domType} is not supported by |
723 * the implementation. |
714 * the implementation. |
724 * |
715 * |
725 * @since 1.6, JAXB 2.0 |
716 * @since 1.6, JAXB 2.0 |
726 */ |
717 */ |
727 public <T> Binder<T> createBinder(Class<T> domType) { |
718 public <T> Binder<T> createBinder(Class<T> domType) { |
729 // abstract |
720 // abstract |
730 throw new UnsupportedOperationException(); |
721 throw new UnsupportedOperationException(); |
731 } |
722 } |
732 |
723 |
733 /** |
724 /** |
734 * Creates a <tt>Binder</tt> for W3C DOM. |
725 * Creates a {@code Binder} for W3C DOM. |
735 * |
726 * |
736 * @return always a new valid <tt>Binder</tt> object. |
727 * @return always a new valid {@code Binder} object. |
737 * |
728 * |
738 * @since 1.6, JAXB 2.0 |
729 * @since 1.6, JAXB 2.0 |
739 */ |
730 */ |
740 public Binder<Node> createBinder() { |
731 public Binder<Node> createBinder() { |
741 return createBinder(Node.class); |
732 return createBinder(Node.class); |
742 } |
733 } |
743 |
734 |
744 /** |
735 /** |
745 * Creates a <tt>JAXBIntrospector</tt> object that can be used to |
736 * Creates a {@code JAXBIntrospector} object that can be used to |
746 * introspect JAXB objects. |
737 * introspect JAXB objects. |
747 * |
738 * |
748 * @return |
739 * @return |
749 * always return a non-null valid <tt>JAXBIntrospector</tt> object. |
740 * always return a non-null valid {@code JAXBIntrospector} object. |
750 * |
741 * |
751 * @throws UnsupportedOperationException |
742 * @throws UnsupportedOperationException |
752 * Calling this method on JAXB 1.0 implementations will throw |
743 * Calling this method on JAXB 1.0 implementations will throw |
753 * an UnsupportedOperationException. |
744 * an UnsupportedOperationException. |
754 * |
745 * |