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