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 }