001 /* 002 * $Id: JAXBContext.java,v 1.28 2003/01/23 22:08:06 ryans Exp $ 003 * 004 * Copyright 2001 Sun Microsystems, Inc. All Rights Reserved. 005 * 006 * This software is the proprietary information of Sun Microsystems, Inc. 007 * Use is subject to license terms. 008 * 009 */ 010 011 package javax.xml.bind; 012 013 /** 014 * <p> 015 * The <tt>JAXBContext</tt> class provides the client's entry point to the 016 * JAXB API. It provides an abstraction for managing the XML/Java binding 017 * information necessary to implement the JAXB binding framework operations: 018 * unmarshal, marshal and validate. A client application obtains new instances 019 * of this class via the {@link #newInstance(String) newInstance(contextPath)} 020 * method. 021 * 022 * <pre> 023 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo:com.acme.bar" ); 024 * </pre> 025 * 026 * <p> 027 * The <tt>contextPath</tt> contains a list of Java package names that contain 028 * schema derived interfaces. The value of this parameter initializes the 029 * <tt>JAXBContext</tt> object so that it is capable of managing the 030 * schema derived interfaces. 031 * 032 * <p> 033 * <blockquote> 034 * <i><B>SPEC REQUIREMENT:</B> the provider must supply an implementation 035 * class containing a method with the following signature:</i> 036 * 037 * <pre> 038 * public static JAXBContext createContext( String contextPath, ClassLoader classLoader ) 039 * throws JAXBException; 040 * </pre> 041 * 042 * <p><i> 043 * JAXB Providers must generate a <tt>jaxb.properties</tt> file in each package 044 * containing schema derived classes. The property file must contain a 045 * property named <tt>javax.xml.bind.context.factory</tt> whose value is 046 * the name of the class that implements the <tt>createContext</tt> API.</i> 047 * 048 * <p><i> 049 * The class supplied by the provider does not have to be assignable to 050 * <tt>javax.xml.bind.JAXBContext</tt>, it simply has to provide a class that 051 * implements the <tt>createContext</tt> API.</i> 052 * 053 * <p><i> 054 * In addition, the provider must call the 055 * {@link DatatypeConverter#setDatatypeConverter(DatatypeConverterInterface) 056 * DatatypeConverter.setDatatypeConverter} api prior to any client 057 * invocations of the marshal and unmarshal methods. This is necessary to 058 * configure the datatype converter that will be used during these operations.</i> 059 * </blockquote> 060 * 061 * <p> 062 * <b>Unmarshalling</b> 063 * <p> 064 * <blockquote> 065 * The {@link Unmarshaller} class provides the client application the ability 066 * to convert XML data into a tree of Java content objects. 067 * The unmarshal method for a schema (within a namespace) allows for 068 * any global XML element declared in the schema to be unmarshalled as 069 * the root of an instance document. The <tt>JAXBContext</tt> object 070 * allows the merging of global elements across a set of schemas (listed 071 * in the <tt>contextPath</tt>). Since each schema in the schema set can belong 072 * to distinct namespaces, the unification of schemas to an unmarshalling 073 * context should be namespace independent. This means that a client 074 * application is able to unmarshal XML documents that are instances of 075 * any of the schemas listed in the <tt>contextPath</tt>. For example: 076 * 077 * <pre> 078 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo:com.acme.bar" ); 079 * Unmarshaller u = jc.createUnmarshaller(); 080 * FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) ); // ok 081 * BarObject barObj = (BarObject)u.unmarshal( new File( "bar.xml" ) ); // ok 082 * BazObject bazObj = (BazObject)u.unmarshal( new File( "baz.xml" ) ); // error, "com.acme.baz" not in contextPath 083 * </pre> 084 * 085 * <p> 086 * The client application may also generate Java content trees explicitly rather 087 * than unmarshalling existing XML data. To do so, the application needs to 088 * have access and knowledge about each of the schema derived <tt> 089 * ObjectFactory</tt> classes that exist in each of java packages contained 090 * in the <tt>contextPath</tt>. For each schema derived java class, there will 091 * be a static factory method that produces objects of that type. For example, 092 * assume that after compiling a schema, you have a package <tt>com.acme.foo</tt> 093 * that contains a schema derived interface named <tt>PurchaseOrder</tt>. In 094 * order to create objects of that type, the client application would use the 095 * factory method like this: 096 * 097 * <pre> 098 * com.acme.foo.PurchaseOrder po = 099 * com.acme.foo.ObjectFactory.createPurchaseOrder(); 100 * </pre> 101 * 102 * <p> 103 * Once the client application has an instance of the the schema derived object, 104 * it can use the mutator methods to set content on it. 105 * 106 * <p> 107 * For more information on the generated <tt>ObjectFactory</tt> classes, see 108 * Section 4.2 <i>Java Package</i> of the specification. 109 * 110 * <p> 111 * <i><B>SPEC REQUIREMENT:</B> the provider must generate a class in each 112 * package that contains all of the necessary object factory methods for that 113 * package named ObjectFactory as well as the static 114 * <tt>newInstance( javaContentInterface )</tt> method</i> 115 * </blockquote> 116 * 117 * <p> 118 * <b>Marshalling</b> 119 * <p> 120 * <blockquote> 121 * The {@link Marshaller} class provides the client application the ability 122 * to convert a Java content tree back into XML data. There is no difference 123 * between marshalling a content tree that is created manually using the factory 124 * methods and marshalling a content tree that is the result an <tt>unmarshal 125 * </tt> operation. Clients can marshal a java content tree back to XML data 126 * to a <tt>java.io.OutputStream</tt> or a <tt>java.io.Writer</tt>. The 127 * marshalling process can alternatively produce SAX2 event streams to a 128 * registered <tt>ContentHandler</tt> or produce a DOM Node object. 129 * <!-- don't expose fragment support yet 130 * Client applications 131 * have control over the output encoding as well as whether or not to marshal 132 * the XML data as a complete document or as a fragment. 133 * --> 134 * 135 * <p> 136 * Here is a simple example that unmarshals an XML document and then marshals 137 * it back out: 138 * 139 * <pre> 140 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); 141 * 142 * // unmarshal from foo.xml 143 * Unmarshaller u = jc.createUnmarshaller(); 144 * FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) ); 145 * 146 * // marshal to System.out 147 * Marshaller m = jc.createMarshaller(); 148 * m.marshal( fooObj, System.out ); 149 * </pre> 150 * </blockquote> 151 * 152 * <p> 153 * <b>Validation</b> 154 * <p> 155 * <blockquote> 156 * There are three varieties of validation available to JAXB client applications: 157 * <blockquote> 158 * <dl> 159 * <dt>Unmarshal-time Validation</dt> 160 * <dd>Validation performed on the XML data as it is being unmarshalled into 161 * a Java content tree</dd> 162 * <dt>On-Demand Validation</dt> 163 * <dd>Validation performed on the Java content tree in memory</dd> 164 * <dt>Fail-Fast Validation</dt> 165 * <dd>Validation of Java property constraints at runtime when client 166 * applications invoke the setter methods of the generated classes</dd> 167 * </dl> 168 * </blockquote> 169 * 170 * <p> 171 * See: <a href="Validator.html#validationtypes">Validator javadocs</a> for a 172 * more detailed definition of the different type of validation. 173 * 174 * <p> 175 * Although unmarshal-time validation and on-demand validation are very similar, 176 * they are completely orthogonal operations with no dependencies on each other. 177 * Client applications are free to use one, both, or neither types of validation. 178 * 179 * <p> 180 * Validation errors and warnings encountered during the unmarshal and validate 181 * operations are reported to the client application via a callback error handler 182 * interface ({@link ValidationEventHandler ValidationEventHandler}) that receives 183 * {@link ValidationEvent ValidationEvent} objects. The <tt>ValidationEvent</tt> 184 * objects contain information about the error or warning encountered. JAXB 185 * allows a few diffent methods of handling validation events which are described 186 * in more detail in the 187 * <a href="Validator.html#handlingerrors">Validator javadoc</a>. 188 * </blockquote> 189 * 190 * <p> 191 * <b>JAXB Runtime Binding Framework Compatibility</b><br> 192 * <blockquote> 193 * Since the JAXB Specification does not define a common runtime system, a JAXB 194 * client application must not attempt to mix runtime objects (<tt>JAXBContext, 195 * Marshaller</tt>, etc. ) from different providers. This does not 196 * mean that the client application isn't portable, it simply means that a 197 * client has to use a runtime system provided by the same provider that was 198 * used to compile the schema. 199 * </blockquote> 200 * 201 * @author <ul><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul> 202 * @version $Revision: 1.28 $ $Date: 2003/01/23 22:08:06 $ 203 * @see Marshaller 204 * @see Unmarshaller 205 * @see Validator 206 * @since JAXB1.0 207 */ 208 public abstract class JAXBContext { 209 210 /** 211 * The name of the property that contains the name of the class capable 212 * of creating new <tt>JAXBContext</tt> objects. 213 */ 214 public static final String JAXB_CONTEXT_FACTORY = 215 "javax.xml.bind.context.factory"; 216 217 218 protected JAXBContext() { 219 } 220 221 222 /** 223 * <p> 224 * Obtain a new instance of a <tt>JAXBContext</tt> class. 225 * 226 * <p> 227 * This is a convenience method for the 228 * {@link #newInstance(String,ClassLoader) newInstance} method. It uses 229 * the context class loader of the current thread. To specify the use of 230 * a different class loader, either set it via the 231 * <tt>Thread.setContextClassLoader()</tt> api or use the 232 * {@link #newInstance(String,ClassLoader) newInstance} method. 233 */ 234 public static JAXBContext newInstance( String contextPath ) 235 throws JAXBException { 236 237 //return newInstance( contextPath, JAXBContext.class.getClassLoader() ); 238 return newInstance( contextPath, Thread.currentThread().getContextClassLoader() ); 239 } 240 241 242 243 /** 244 * <p> 245 * Obtain a new instance of a <tt>JAXBContext</tt> class. 246 * 247 * <p> 248 * The client application must supply a context path which is a list of 249 * colon (':', \u005Cu003A) separated java package names that contain schema 250 * derived classes. 251 * 252 * The JAXB provider will ensure that each package on the context path 253 * has a <tt>jaxb.properties</tt> file which contains a value for the 254 * <tt>javax.xml.bind.context.factory</tt> property and that all values 255 * resolve to the same provider. 256 * 257 * <p> 258 * If there are any global XML element name collisions across the various 259 * packages listed on the <tt>contextPath</tt>, a <tt>JAXBException</tt> 260 * will be thrown. Mixing generated classes from multiple JAXB Providers 261 * in the same context path will also result in a <tt>JAXBException</tt> 262 * being thrown. 263 * 264 * @param contextPath list of java package names that contain schema 265 * derived classes 266 * @param classLoader 267 * This class loader will be used to locate the implementation 268 * classes. 269 * 270 * @return a new instance of a <tt>JAXBContext</tt> 271 * @throws JAXBException if an error was encountered while creating the 272 * <tt>JAXBContext</tt>, such as an ambiguity among 273 * global elements contained in the contextPath, 274 * failure to locate a value for the context factory 275 * property, or mixing schema derived packages from 276 * different providers on the same contextPath. 277 */ 278 public static JAXBContext newInstance( String contextPath, ClassLoader classLoader ) 279 throws JAXBException { 280 281 return (JAXBContext) ContextFinder.find( 282 /* The default property name according to the JAXB spec */ 283 JAXB_CONTEXT_FACTORY, 284 285 /* the context path supplied by the client app */ 286 contextPath, 287 288 /* class loader to be used */ 289 classLoader ); 290 } 291 292 293 /** 294 * Create an <tt>Unmarshaller</tt> object that can be used to convert XML 295 * data into a java content tree. 296 * 297 * @return an <tt>Unmarshaller</tt> object 298 * 299 * @throws JAXBException if an error was encountered while creating the 300 * <tt>Unmarshaller</tt> object 301 */ 302 public abstract Unmarshaller createUnmarshaller() throws JAXBException; 303 304 305 /** 306 * Create a <tt>Marshaller</tt> object that can be used to convert a 307 * java content tree into XML data. 308 * 309 * @return a <tt>Marshaller</tt> object 310 * 311 * @throws JAXBException if an error was encountered while creating the 312 * <tt>Marshaller</tt> object 313 */ 314 public abstract Marshaller createMarshaller() throws JAXBException; 315 316 317 /** 318 * Create a <tt>Validator</tt> object that can be used to validate a 319 * java content tree against its source schema. 320 * 321 * @return a <tt>Validator</tt> object 322 * 323 * @throws JAXBException if an error was encountered while creating the 324 * <tt>Validator</tt> object 325 */ 326 public abstract Validator createValidator() throws JAXBException; 327 328 }