1 /* 2 * Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.xml.bind; 27 28 import org.w3c.dom.Node; 29 30 import java.util.Collections; 31 import java.util.Map; 32 import java.util.Properties; 33 import java.io.IOException; 34 import java.io.InputStream; 35 36 /** 37 * <p> 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 40 * information necessary to implement the JAXB binding framework operations: 41 * unmarshal, marshal and validate. 42 * 43 * <p>A client application normally obtains new instances of this class using 44 * one of these two styles for newInstance methods, although there are other 45 * specialized forms of the method available: 46 * 47 * <ul> 48 * <li>{@link #newInstance(String,ClassLoader) JAXBContext.newInstance( "com.acme.foo:com.acme.bar" )} <br> 49 * The JAXBContext instance is initialized from a list of colon 50 * separated Java package names. Each java package contains 51 * JAXB mapped classes, schema-derived classes and/or user annotated 52 * classes. Additionally, the java package may contain JAXB package annotations 53 * that must be processed. (see JLS, Section 7.4.1 "Named Packages"). 54 * </li> 55 * <li>{@link #newInstance(Class...) JAXBContext.newInstance( com.acme.foo.Foo.class )} <br> 56 * The JAXBContext instance is initialized with class(es) 57 * passed as parameter(s) and classes that are statically reachable from 58 * these class(es). See {@link #newInstance(Class...)} for details. 59 * </li> 60 * </ul> 61 * 62 * <p> 63 * <i><B>SPEC REQUIREMENT:</B> the provider must supply an implementation 64 * class containing the following method signatures:</i> 65 * 66 * <pre>{@code 67 * public static JAXBContext createContext( String contextPath, ClassLoader classLoader, Map<String,Object> properties ) throws JAXBException 68 * public static JAXBContext createContext( Class[] classes, Map<String,Object> properties ) throws JAXBException 69 * }</pre> 70 * 71 * <p><i> 72 * The following JAXB 1.0 requirement is only required for schema to 73 * java interface/implementation binding. It does not apply to JAXB annotated 74 * classes. JAXB Providers must generate a <tt>jaxb.properties</tt> file in 75 * each package containing schema derived classes. The property file must 76 * contain a property named <tt>javax.xml.bind.context.factory</tt> whose 77 * value is the name of the class that implements the <tt>createContext</tt> 78 * APIs.</i> 79 * 80 * <p><i> 81 * The class supplied by the provider does not have to be assignable to 82 * <tt>javax.xml.bind.JAXBContext</tt>, it simply has to provide a class that 83 * implements the <tt>createContext</tt> APIs.</i> 84 * 85 * <p><i> 86 * In addition, the provider must call the 87 * {@link DatatypeConverter#setDatatypeConverter(DatatypeConverterInterface) 88 * DatatypeConverter.setDatatypeConverter} api prior to any client 89 * invocations of the marshal and unmarshal methods. This is necessary to 90 * configure the datatype converter that will be used during these operations.</i> 91 * 92 * <a name="Unmarshalling"></a> 93 * <h3>Unmarshalling</h3> 94 * <p> 95 * The {@link Unmarshaller} class provides the client application the ability 96 * to convert XML data into a tree of Java content objects. 97 * The unmarshal method allows for 98 * any global XML element declared in the schema to be unmarshalled as 99 * the root of an instance document. 100 * Additionally, the unmarshal method allows for an unrecognized root element that 101 * has an xsi:type attribute's value that references a type definition declared in 102 * the schema to be unmarshalled as the root of an instance document. 103 * The <tt>JAXBContext</tt> object 104 * allows the merging of global elements and type definitions across a set of schemas (listed 105 * in the <tt>contextPath</tt>). Since each schema in the schema set can belong 106 * to distinct namespaces, the unification of schemas to an unmarshalling 107 * context should be namespace independent. This means that a client 108 * application is able to unmarshal XML documents that are instances of 109 * any of the schemas listed in the <tt>contextPath</tt>. For example: 110 * 111 * <pre> 112 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo:com.acme.bar" ); 113 * Unmarshaller u = jc.createUnmarshaller(); 114 * FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) ); // ok 115 * BarObject barObj = (BarObject)u.unmarshal( new File( "bar.xml" ) ); // ok 116 * BazObject bazObj = (BazObject)u.unmarshal( new File( "baz.xml" ) ); // error, "com.acme.baz" not in contextPath 117 * </pre> 118 * 119 * <p> 120 * The client application may also generate Java content trees explicitly rather 121 * than unmarshalling existing XML data. For all JAXB-annotated value classes, 122 * an application can create content using constructors. 123 * For schema-derived interface/implementation classes and for the 124 * creation of elements that are not bound to a JAXB-annotated 125 * class, an application needs to have access and knowledge about each of 126 * the schema derived <tt> ObjectFactory</tt> classes that exist in each of 127 * java packages contained in the <tt>contextPath</tt>. For each schema 128 * derived java class, there is a static factory method that produces objects 129 * of that type. For example, 130 * assume that after compiling a schema, you have a package <tt>com.acme.foo</tt> 131 * that contains a schema derived interface named <tt>PurchaseOrder</tt>. In 132 * order to create objects of that type, the client application would use the 133 * factory method like this: 134 * 135 * <pre> 136 * com.acme.foo.PurchaseOrder po = 137 * com.acme.foo.ObjectFactory.createPurchaseOrder(); 138 * </pre> 139 * 140 * <p> 141 * Once the client application has an instance of the the schema derived object, 142 * it can use the mutator methods to set content on it. 143 * 144 * <p> 145 * For more information on the generated <tt>ObjectFactory</tt> classes, see 146 * Section 4.2 <i>Java Package</i> of the specification. 147 * 148 * <p> 149 * <i><B>SPEC REQUIREMENT:</B> the provider must generate a class in each 150 * package that contains all of the necessary object factory methods for that 151 * package named ObjectFactory as well as the static 152 * <tt>newInstance( javaContentInterface )</tt> method</i> 153 * 154 * <h3>Marshalling</h3> 155 * <p> 156 * The {@link Marshaller} class provides the client application the ability 157 * to convert a Java content tree back into XML data. There is no difference 158 * between marshalling a content tree that is created manually using the factory 159 * methods and marshalling a content tree that is the result an <tt>unmarshal 160 * </tt> operation. Clients can marshal a java content tree back to XML data 161 * to a <tt>java.io.OutputStream</tt> or a <tt>java.io.Writer</tt>. The 162 * marshalling process can alternatively produce SAX2 event streams to a 163 * registered <tt>ContentHandler</tt> or produce a DOM Node object. 164 * Client applications have control over the output encoding as well as 165 * whether or not to marshal the XML data as a complete document or 166 * as a fragment. 167 * 168 * <p> 169 * Here is a simple example that unmarshals an XML document and then marshals 170 * it back out: 171 * 172 * <pre> 173 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); 174 * 175 * // unmarshal from foo.xml 176 * Unmarshaller u = jc.createUnmarshaller(); 177 * FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) ); 178 * 179 * // marshal to System.out 180 * Marshaller m = jc.createMarshaller(); 181 * m.marshal( fooObj, System.out ); 182 * </pre> 183 * 184 * 185 * <h3>Validation</h3> 186 * <p> 187 * Validation has been changed significantly since JAXB 1.0. The {@link Validator} 188 * class has been deprecated and made optional. This means that you are advised 189 * not to use this class and, in fact, it may not even be available depending on 190 * your JAXB provider. JAXB 1.0 client applications that rely on <tt>Validator</tt> 191 * will still work properly when deployed with the JAXB 1.0 runtime system. 192 * 193 * In JAXB 2.0, the {@link Unmarshaller} has included convenince methods that expose 194 * the JAXP 1.3 {@link javax.xml.validation} framework. Please refer to the 195 * {@link Unmarshaller#setSchema(javax.xml.validation.Schema)} API for more 196 * information. 197 * 198 * 199 * <h3>JAXB Runtime Binding Framework Compatibility</h3> 200 * <p> 201 * The following JAXB 1.0 restriction only applies to binding schema to 202 * interfaces/implementation classes. 203 * Since this binding does not require a common runtime system, a JAXB 204 * client application must not attempt to mix runtime objects (<tt>JAXBContext, 205 * Marshaller</tt>, etc. ) from different providers. This does not 206 * mean that the client application isn't portable, it simply means that a 207 * client has to use a runtime system provided by the same provider that was 208 * used to compile the schema. 209 * 210 * 211 * <h3>Discovery of JAXB implementation</h3> 212 * <p> 213 * When one of the <tt>newInstance</tt> methods is called, a JAXB implementation is discovered 214 * by the following steps. 215 * 216 * <ol> 217 * <li> 218 * For each package/class explicitly passed in to the {@link #newInstance} method, in the order they are specified, 219 * <tt>jaxb.properties</tt> file is looked up in its package, by using the associated classloader — 220 * this is {@link Class#getClassLoader() the owner class loader} for a {@link Class} argument, and for a package 221 * the specified {@link ClassLoader}. 222 * 223 * <p> 224 * If such a file is discovered, it is {@link Properties#load(InputStream) loaded} as a property file, and 225 * the value of the {@link #JAXB_CONTEXT_FACTORY} key will be assumed to be the provider factory class. 226 * This class is then loaded by the associated classloader discussed above. 227 * 228 * <p> 229 * This phase of the look up allows some packages to force the use of a certain JAXB implementation. 230 * (For example, perhaps the schema compiler has generated some vendor extension in the code.) 231 * 232 * <li> 233 * If the system property {@link #JAXB_CONTEXT_FACTORY} exists, then its value is assumed to be the provider 234 * factory class. This phase of the look up enables per-JVM override of the JAXB implementation. 235 * 236 * <li> 237 * Look for <tt>/META-INF/services/javax.xml.bind.JAXBContext</tt> file in the associated classloader. 238 * This file follows the standard service descriptor convention, and if such a file exists, its content 239 * is assumed to be the provider factory class. This phase of the look up is for automatic discovery. 240 * It allows users to just put a JAXB implementation in a classpath and use it without any furhter configuration. 241 * 242 * <li> 243 * Finally, if all the steps above fail, then the rest of the look up is unspecified. That said, 244 * the recommended behavior is to simply look for some hard-coded platform default JAXB implementation. 245 * This phase of the look up is so that JavaSE can have its own JAXB implementation as the last resort. 246 * </ol> 247 * 248 * <p> 249 * Once the provider factory class is discovered, its 250 * <tt>public static JAXBContext createContext(String,ClassLoader,Map)</tt> method 251 * (see {@link #newInstance(String, ClassLoader, Map)} for the parameter semantics.) 252 * or <tt>public static JAXBContext createContet(Class[],Map)</tt> method 253 * (see {@link #newInstance(Class[], Map)} for the parameter semantics) are invoked 254 * to create a {@link JAXBContext}. 255 * 256 * @author <ul><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul> 257 * @see Marshaller 258 * @see Unmarshaller 259 * @see <a href="http://docs.oracle.com/javase/specs/jls/se7/html/jls-7.html#jls-7.4.1">S 7.4.1 "Named Packages" in Java Language Specification</a> 260 * @since 1.6, JAXB 1.0 261 */ 262 public abstract class JAXBContext { 263 264 /** 265 * The name of the property that contains the name of the class capable 266 * of creating new <tt>JAXBContext</tt> objects. 267 */ 268 public static final String JAXB_CONTEXT_FACTORY = 269 "javax.xml.bind.context.factory"; 270 271 272 protected JAXBContext() { 273 } 274 275 276 /** 277 * <p> 278 * Obtain a new instance of a <tt>JAXBContext</tt> class. 279 * 280 * <p> 281 * This is a convenience method to invoke the 282 * {@link #newInstance(String,ClassLoader)} method with 283 * the context class loader of the current thread. 284 * 285 * @throws JAXBException if an error was encountered while creating the 286 * <tt>JAXBContext</tt> such as 287 * <ol> 288 * <li>failure to locate either ObjectFactory.class or jaxb.index in the packages</li> 289 * <li>an ambiguity among global elements contained in the contextPath</li> 290 * <li>failure to locate a value for the context factory provider property</li> 291 * <li>mixing schema derived packages from different providers on the same contextPath</li> 292 * </ol> 293 */ 294 public static JAXBContext newInstance( String contextPath ) 295 throws JAXBException { 296 297 //return newInstance( contextPath, JAXBContext.class.getClassLoader() ); 298 return newInstance( contextPath, getContextClassLoader()); 299 } 300 301 /** 302 * <p> 303 * Obtain a new instance of a <tt>JAXBContext</tt> class. 304 * 305 * <p> 306 * The client application must supply a context path which is a list of 307 * colon (':', \u005Cu003A) separated java package names that contain 308 * schema-derived classes and/or fully qualified JAXB-annotated classes. 309 * Schema-derived 310 * code is registered with the JAXBContext by the 311 * ObjectFactory.class generated per package. 312 * Alternatively than being listed in the context path, programmer 313 * annotated JAXB mapped classes can be listed in a 314 * <tt>jaxb.index</tt> resource file, format described below. 315 * Note that a java package can contain both schema-derived classes and 316 * user annotated JAXB classes. Additionally, the java package may 317 * contain JAXB package annotations that must be processed. (see JLS, 318 * Section 7.4.1 "Named Packages"). 319 * </p> 320 * 321 * <p> 322 * Every package listed on the contextPath must meet <b>one or both</b> of the 323 * following conditions otherwise a <tt>JAXBException</tt> will be thrown: 324 * </p> 325 * <ol> 326 * <li>it must contain ObjectFactory.class</li> 327 * <li>it must contain jaxb.index</li> 328 * </ol> 329 * 330 * <p> 331 * <b>Format for jaxb.index</b> 332 * <p> 333 * The file contains a newline-separated list of class names. 334 * Space and tab characters, as well as blank 335 * lines, are ignored. The comment character 336 * is '#' (0x23); on each line all characters following the first comment 337 * character are ignored. The file must be encoded in UTF-8. Classes that 338 * are reachable, as defined in {@link #newInstance(Class...)}, from the 339 * listed classes are also registered with JAXBContext. 340 * <p> 341 * Constraints on class name occuring in a <tt>jaxb.index</tt> file are: 342 * <ul> 343 * <li>Must not end with ".class".</li> 344 * <li>Class names are resolved relative to package containing 345 * <tt>jaxb.index</tt> file. Only classes occuring directly in package 346 * containing <tt>jaxb.index</tt> file are allowed.</li> 347 * <li>Fully qualified class names are not allowed. 348 * A qualified class name,relative to current package, 349 * is only allowed to specify a nested or inner class.</li> 350 * </ul> 351 * 352 * <p> 353 * To maintain compatibility with JAXB 1.0 schema to java 354 * interface/implementation binding, enabled by schema customization 355 * <tt>{@literal <jaxb:globalBindings valueClass="false">}</tt>, 356 * the JAXB provider will ensure that each package on the context path 357 * has a <tt>jaxb.properties</tt> file which contains a value for the 358 * <tt>javax.xml.bind.context.factory</tt> property and that all values 359 * resolve to the same provider. This requirement does not apply to 360 * JAXB annotated classes. 361 * 362 * <p> 363 * If there are any global XML element name collisions across the various 364 * packages listed on the <tt>contextPath</tt>, a <tt>JAXBException</tt> 365 * will be thrown. 366 * 367 * <p> 368 * Mixing generated interface/impl bindings from multiple JAXB Providers 369 * in the same context path may result in a <tt>JAXBException</tt> 370 * being thrown. 371 * 372 * <p> 373 * The steps involved in discovering the JAXB implementation is discussed in the class javadoc. 374 * 375 * @param contextPath list of java package names that contain schema 376 * derived class and/or java to schema (JAXB-annotated) 377 * mapped classes 378 * @param classLoader 379 * This class loader will be used to locate the implementation 380 * classes. 381 * 382 * @return a new instance of a <tt>JAXBContext</tt> 383 * @throws JAXBException if an error was encountered while creating the 384 * <tt>JAXBContext</tt> such as 385 * <ol> 386 * <li>failure to locate either ObjectFactory.class or jaxb.index in the packages</li> 387 * <li>an ambiguity among global elements contained in the contextPath</li> 388 * <li>failure to locate a value for the context factory provider property</li> 389 * <li>mixing schema derived packages from different providers on the same contextPath</li> 390 * </ol> 391 */ 392 public static JAXBContext newInstance( String contextPath, ClassLoader classLoader ) throws JAXBException { 393 394 return newInstance(contextPath,classLoader,Collections.<String,Object>emptyMap()); 395 } 396 397 /** 398 * <p> 399 * Obtain a new instance of a <tt>JAXBContext</tt> class. 400 * 401 * <p> 402 * This is mostly the same as {@link JAXBContext#newInstance(String, ClassLoader)}, 403 * but this version allows you to pass in provider-specific properties to configure 404 * the instantiation of {@link JAXBContext}. 405 * 406 * <p> 407 * The interpretation of properties is up to implementations. Implementations should 408 * throw <tt>JAXBException</tt> if it finds properties that it doesn't understand. 409 * 410 * @param contextPath list of java package names that contain schema derived classes 411 * @param classLoader 412 * This class loader will be used to locate the implementation classes. 413 * @param properties 414 * provider-specific properties. Can be null, which means the same thing as passing 415 * in an empty map. 416 * 417 * @return a new instance of a <tt>JAXBContext</tt> 418 * @throws JAXBException if an error was encountered while creating the 419 * <tt>JAXBContext</tt> such as 420 * <ol> 421 * <li>failure to locate either ObjectFactory.class or jaxb.index in the packages</li> 422 * <li>an ambiguity among global elements contained in the contextPath</li> 423 * <li>failure to locate a value for the context factory provider property</li> 424 * <li>mixing schema derived packages from different providers on the same contextPath</li> 425 * </ol> 426 * @since 1.6, JAXB 2.0 427 */ 428 public static JAXBContext newInstance( String contextPath, ClassLoader classLoader, Map<String,?> properties ) 429 throws JAXBException { 430 431 return ContextFinder.find( 432 /* The default property name according to the JAXB spec */ 433 JAXB_CONTEXT_FACTORY, 434 435 /* the context path supplied by the client app */ 436 contextPath, 437 438 /* class loader to be used */ 439 classLoader, 440 properties ); 441 } 442 443 // TODO: resurrect this once we introduce external annotations 444 // /** 445 // * <p> 446 // * Obtain a new instance of a <tt>JAXBContext</tt> class. 447 // * 448 // * <p> 449 // * The client application must supply a list of classes that the new 450 // * context object needs to recognize. 451 // * 452 // * Not only the new context will recognize all the classes specified, 453 // * but it will also recognize any classes that are directly/indirectly 454 // * referenced statically from the specified classes. 455 // * 456 // * For example, in the following Java code, if you do 457 // * <tt>newInstance(Foo.class)</tt>, the newly created {@link JAXBContext} 458 // * will recognize both <tt>Foo</tt> and <tt>Bar</tt>, but not <tt>Zot</tt>: 459 // * <pre> 460 // * class Foo { 461 // * Bar b; 462 // * } 463 // * class Bar { int x; } 464 // * class Zot extends Bar { int y; } 465 // * </pre> 466 // * 467 // * Therefore, a typical client application only needs to specify the 468 // * top-level classes, but it needs to be careful. 469 // * 470 // * TODO: if we are to define other mechanisms, refer to them. 471 // * 472 // * @param externalBindings 473 // * list of external binding files. Can be null or empty if none is used. 474 // * when specified, those files determine how the classes are bound. 475 // * 476 // * @param classesToBeBound 477 // * list of java classes to be recognized by the new {@link JAXBContext}. 478 // * Can be empty, in which case a {@link JAXBContext} that only knows about 479 // * spec-defined classes will be returned. 480 // * 481 // * @return 482 // * A new instance of a <tt>JAXBContext</tt>. Always non-null valid object. 483 // * 484 // * @throws JAXBException 485 // * if an error was encountered while creating the 486 // * <tt>JAXBContext</tt>, such as (but not limited to): 487 // * <ol> 488 // * <li>No JAXB implementation was discovered 489 // * <li>Classes use JAXB annotations incorrectly 490 // * <li>Classes have colliding annotations (i.e., two classes with the same type name) 491 // * <li>Specified external bindings are incorrect 492 // * <li>The JAXB implementation was unable to locate 493 // * provider-specific out-of-band information (such as additional 494 // * files generated at the development time.) 495 // * </ol> 496 // * 497 // * @throws IllegalArgumentException 498 // * if the parameter contains {@code null} (i.e., {@code newInstance(null);}) 499 // * 500 // * @since JAXB 2.0 501 // */ 502 // public static JAXBContext newInstance( Source[] externalBindings, Class... classesToBeBound ) 503 // throws JAXBException { 504 // 505 // // empty class list is not an error, because the context will still include 506 // // spec-specified classes like String and Integer. 507 // // if(classesToBeBound.length==0) 508 // // throw new IllegalArgumentException(); 509 // 510 // // but it is an error to have nulls in it. 511 // for( int i=classesToBeBound.length-1; i>=0; i-- ) 512 // if(classesToBeBound[i]==null) 513 // throw new IllegalArgumentException(); 514 // 515 // return ContextFinder.find(externalBindings,classesToBeBound); 516 // } 517 518 /** 519 * <p> 520 * Obtain a new instance of a <tt>JAXBContext</tt> class. 521 * 522 * <p> 523 * The client application must supply a list of classes that the new 524 * context object needs to recognize. 525 * 526 * Not only the new context will recognize all the classes specified, 527 * but it will also recognize any classes that are directly/indirectly 528 * referenced statically from the specified classes. Subclasses of 529 * referenced classes nor <tt>@XmlTransient</tt> referenced classes 530 * are not registered with JAXBContext. 531 * 532 * For example, in the following Java code, if you do 533 * <tt>newInstance(Foo.class)</tt>, the newly created {@link JAXBContext} 534 * will recognize both <tt>Foo</tt> and <tt>Bar</tt>, but not <tt>Zot</tt> or <tt>FooBar</tt>: 535 * <pre> 536 * class Foo { 537 * @XmlTransient FooBar c; 538 * Bar b; 539 * } 540 * class Bar { int x; } 541 * class Zot extends Bar { int y; } 542 * class FooBar { } 543 * </pre> 544 * 545 * Therefore, a typical client application only needs to specify the 546 * top-level classes, but it needs to be careful. 547 * 548 * <p> 549 * Note that for each java package registered with JAXBContext, 550 * when the optional package annotations exist, they must be processed. 551 * (see JLS, Section 7.4.1 "Named Packages"). 552 * 553 * <p> 554 * The steps involved in discovering the JAXB implementation is discussed in the class javadoc. 555 * 556 * @param classesToBeBound 557 * list of java classes to be recognized by the new {@link JAXBContext}. 558 * Can be empty, in which case a {@link JAXBContext} that only knows about 559 * spec-defined classes will be returned. 560 * 561 * @return 562 * A new instance of a <tt>JAXBContext</tt>. Always non-null valid object. 563 * 564 * @throws JAXBException 565 * if an error was encountered while creating the 566 * <tt>JAXBContext</tt>, such as (but not limited to): 567 * <ol> 568 * <li>No JAXB implementation was discovered 569 * <li>Classes use JAXB annotations incorrectly 570 * <li>Classes have colliding annotations (i.e., two classes with the same type name) 571 * <li>The JAXB implementation was unable to locate 572 * provider-specific out-of-band information (such as additional 573 * files generated at the development time.) 574 * </ol> 575 * 576 * @throws IllegalArgumentException 577 * if the parameter contains {@code null} (i.e., {@code newInstance(null);}) 578 * 579 * @since 1.6, JAXB 2.0 580 */ 581 public static JAXBContext newInstance( Class... classesToBeBound ) 582 throws JAXBException { 583 584 return newInstance(classesToBeBound,Collections.<String,Object>emptyMap()); 585 } 586 587 /** 588 * <p> 589 * Obtain a new instance of a <tt>JAXBContext</tt> class. 590 * 591 * <p> 592 * An overloading of {@link JAXBContext#newInstance(Class...)} 593 * to configure 'properties' for this instantiation of {@link JAXBContext}. 594 * 595 * <p> 596 * The interpretation of properties is up to implementations. Implementations should 597 * throw <tt>JAXBException</tt> if it finds properties that it doesn't understand. 598 * 599 * @param classesToBeBound 600 * list of java classes to be recognized by the new {@link JAXBContext}. 601 * Can be empty, in which case a {@link JAXBContext} that only knows about 602 * spec-defined classes will be returned. 603 * @param properties 604 * provider-specific properties. Can be null, which means the same thing as passing 605 * in an empty map. 606 * 607 * @return 608 * A new instance of a <tt>JAXBContext</tt>. Always non-null valid object. 609 * 610 * @throws JAXBException 611 * if an error was encountered while creating the 612 * <tt>JAXBContext</tt>, such as (but not limited to): 613 * <ol> 614 * <li>No JAXB implementation was discovered 615 * <li>Classes use JAXB annotations incorrectly 616 * <li>Classes have colliding annotations (i.e., two classes with the same type name) 617 * <li>The JAXB implementation was unable to locate 618 * provider-specific out-of-band information (such as additional 619 * files generated at the development time.) 620 * </ol> 621 * 622 * @throws IllegalArgumentException 623 * if the parameter contains {@code null} (i.e., {@code newInstance(null,someMap);}) 624 * 625 * @since 1.6, JAXB 2.0 626 */ 627 public static JAXBContext newInstance( Class[] classesToBeBound, Map<String,?> properties ) 628 throws JAXBException { 629 630 if (classesToBeBound == null) { 631 throw new IllegalArgumentException(); 632 } 633 634 // but it is an error to have nulls in it. 635 for (int i = classesToBeBound.length - 1; i >= 0; i--) { 636 if (classesToBeBound[i] == null) { 637 throw new IllegalArgumentException(); 638 } 639 } 640 641 return ContextFinder.find(classesToBeBound,properties); 642 } 643 644 /** 645 * Create an <tt>Unmarshaller</tt> object that can be used to convert XML 646 * data into a java content tree. 647 * 648 * @return an <tt>Unmarshaller</tt> object 649 * 650 * @throws JAXBException if an error was encountered while creating the 651 * <tt>Unmarshaller</tt> object 652 */ 653 public abstract Unmarshaller createUnmarshaller() throws JAXBException; 654 655 656 /** 657 * Create a <tt>Marshaller</tt> object that can be used to convert a 658 * java content tree into XML data. 659 * 660 * @return a <tt>Marshaller</tt> object 661 * 662 * @throws JAXBException if an error was encountered while creating the 663 * <tt>Marshaller</tt> object 664 */ 665 public abstract Marshaller createMarshaller() throws JAXBException; 666 667 668 /** 669 * {@link Validator} has been made optional and deprecated in JAXB 2.0. Please 670 * refer to the javadoc for {@link Validator} for more detail. 671 * <p> 672 * Create a <tt>Validator</tt> object that can be used to validate a 673 * java content tree against its source schema. 674 * 675 * @return a <tt>Validator</tt> object 676 * 677 * @throws JAXBException if an error was encountered while creating the 678 * <tt>Validator</tt> object 679 * @deprecated since JAXB2.0 680 */ 681 public abstract Validator createValidator() throws JAXBException; 682 683 /** 684 * Creates a <tt>Binder</tt> object that can be used for 685 * associative/in-place unmarshalling/marshalling. 686 * 687 * @param domType select the DOM API to use by passing in its DOM Node class. 688 * 689 * @return always a new valid <tt>Binder</tt> object. 690 * 691 * @throws UnsupportedOperationException 692 * if DOM API corresponding to <tt>domType</tt> is not supported by 693 * the implementation. 694 * 695 * @since 1.6, JAXB 2.0 696 */ 697 public <T> Binder<T> createBinder(Class<T> domType) { 698 // to make JAXB 1.0 implementations work, this method must not be 699 // abstract 700 throw new UnsupportedOperationException(); 701 } 702 703 /** 704 * Creates a <tt>Binder</tt> for W3C DOM. 705 * 706 * @return always a new valid <tt>Binder</tt> object. 707 * 708 * @since 1.6, JAXB 2.0 709 */ 710 public Binder<Node> createBinder() { 711 return createBinder(Node.class); 712 } 713 714 /** 715 * Creates a <tt>JAXBIntrospector</tt> object that can be used to 716 * introspect JAXB objects. 717 * 718 * @return 719 * always return a non-null valid <tt>JAXBIntrospector</tt> object. 720 * 721 * @throws UnsupportedOperationException 722 * Calling this method on JAXB 1.0 implementations will throw 723 * an UnsupportedOperationException. 724 * 725 * @since 1.6, JAXB 2.0 726 */ 727 public JAXBIntrospector createJAXBIntrospector() { 728 // to make JAXB 1.0 implementations work, this method must not be 729 // abstract 730 throw new UnsupportedOperationException(); 731 } 732 733 /** 734 * Generates the schema documents for this context. 735 * 736 * @param outputResolver 737 * this object controls the output to which schemas 738 * will be sent. 739 * 740 * @throws IOException 741 * if {@link SchemaOutputResolver} throws an {@link IOException}. 742 * 743 * @throws UnsupportedOperationException 744 * Calling this method on JAXB 1.0 implementations will throw 745 * an UnsupportedOperationException. 746 * 747 * @since 1.6, JAXB 2.0 748 */ 749 public void generateSchema(SchemaOutputResolver outputResolver) throws IOException { 750 // to make JAXB 1.0 implementations work, this method must not be 751 // abstract 752 throw new UnsupportedOperationException(); 753 } 754 755 private static ClassLoader getContextClassLoader() { 756 if (System.getSecurityManager() == null) { 757 return Thread.currentThread().getContextClassLoader(); 758 } else { 759 return (ClassLoader) java.security.AccessController.doPrivileged( 760 new java.security.PrivilegedAction() { 761 public java.lang.Object run() { 762 return Thread.currentThread().getContextClassLoader(); 763 } 764 }); 765 } 766 } 767 768 }