001 /*
002 * $Id: Marshaller.java,v 1.28 2003/01/13 21:15:52 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>Marshaller</tt> class is responsible for governing the process
016 * of serializing Java content trees back into XML data. It provides the basic
017 * marshalling methods:
018 *
019 * <p>
020 * <i>Assume the following setup code in all following code fragments:</i>
021 * <blockquote>
022 * <pre>
023 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
024 * Unmarshaller u = jc.createUnmarshaller();
025 * FooObject obj = (FooObject)u.unmarshal( new File( "foo.xml" ) );
026 * Marshaller m = jc.createMarshaller();
027 * </pre>
028 * </blockquote>
029 *
030 * <p>
031 * Marshalling to a File:
032 * <blockquote>
033 * <pre>
034 * OutputStream os = new FileOutputStream( "nosferatu.xml" );
035 * m.marshal( obj, os );
036 * </pre>
037 * </blockquote>
038 *
039 * <p>
040 * Marshalling to a SAX ContentHandler:
041 * <blockquote>
042 * <pre>
043 * // assume MyContentHandler instanceof ContentHandler
044 * m.marshal( obj, new MyContentHandler() );
045 * </pre>
046 * </blockquote>
047 *
048 * <p>
049 * Marshalling to a DOM Node:
050 * <blockquote>
051 * <pre>
052 * DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
053 * dbf.setNamespaceAware(true);
054 * DocumentBuilder db = dbf.newDocumentBuilder();
055 * Document doc = db.newDocument();
056 *
057 * m.marshal( obj, doc );
058 * </pre>
059 * </blockquote>
060 *
061 * <p>
062 * Marshalling to a java.io.OutputStream:
063 * <blockquote>
064 * <pre>
065 * m.marshal( obj, System.out );
066 * </pre>
067 * </blockquote>
068 *
069 * <p>
070 * Marshalling to a java.io.Writer:
071 * <blockquote>
072 * <pre>
073 * m.marshal( obj, new PrintWriter( System.out ) );
074 * </pre>
075 * </blockquote>
076 *
077 * <p>
078 * Marshalling to a javax.xml.transform.SAXResult:
079 * <blockquote>
080 * <pre>
081 * // assume MyContentHandler instanceof ContentHandler
082 * SAXResult result = new SAXResult( new MyContentHandler() );
083 *
084 * m.marshal( obj, result );
085 * </pre>
086 * </blockquote>
087 *
088 * <p>
089 * Marshalling to a javax.xml.transform.DOMResult:
090 * <blockquote>
091 * <pre>
092 * DOMResult result = new DOMResult();
093 *
094 * m.marshal( obj, result );
095 * </pre>
096 * </blockquote>
097 *
098 * <p>
099 * Marshalling to a javax.xml.transform.StreamResult:
100 * <blockquote>
101 * <pre>
102 * StreamResult result = new StreamResult( System.out );
103 *
104 * m.marshal( obj, result );
105 * </pre>
106 * </blockquote>
107 *
108 * <p>
109 * <a name="objMarshalling"></a>
110 * <b>Marshalling <tt>java.lang.Object</tt> Objects</b><br>
111 * <blockquote>
112 * Although each of the marshal methods accepts a <tt>java.lang.Object</tt> as
113 * its first parameter, JAXB Providers are not required to be able to marshal
114 * <b>any</b> arbitrary <tt>java.lang.Object</tt>. If the <tt>JAXBContext</tt>
115 * object that was used to create this <tt>Marshaller</tt> does not have enough
116 * information to know how to marshal the object parameter (or any objects
117 * reachable from it), then the marshal operation will throw a
118 * {@link MarshalException MarshalException}. Even though JAXB Providers are not
119 * required to be able to marshal arbitrary <tt>java.lang.Object</tt> objects,
120 * some providers may allow it.
121 * </blockquote>
122 *
123 * <p>
124 * <b>Encoding</b><br>
125 * <blockquote>
126 * By default, the Marshaller will use UTF-8 encoding when generating XML data
127 * to a <tt>java.io.OutputStream</tt>, or a <tt>java.io.Writer</tt>. Use the
128 * {@link #setProperty(String,Object) setProperty} API to change the ouput
129 * encoding used during these marshal operations. Client applications are
130 * expected to supply a valid character encoding name as defined in the
131 * <a href="http://www.w3.org/TR/2000/REC-xml-20001006#charencoding">W3C XML 1.0
132 * Recommendation</a> and supported by your
133 * <a href="http://java.sun.com/j2se/1.3/docs/api/java/lang/package-summary.html#charenc">
134 * Java Platform</a>.
135 * </blockquote>
136 *
137 * <p>
138 * <b>Validation and Well-Formedness</b><br>
139 * <blockquote>
140 * <p>
141 * Client applications are not required to validate the Java content tree prior
142 * to calling any of the marshal API's. Furthermore, there is no requirement
143 * that the Java content tree be valid with respect to its original schema in
144 * order to marshal it back into XML data. Different JAXB Providers will
145 * support marshalling invalid Java content trees at varying levels, however
146 * all JAXB Providers must be able to marshal a valid content tree back to
147 * XML data. A JAXB Provider must throw a <tt>MarshalException</tt> when it
148 * is unable to complete the marshal operation due to invalid content. Some
149 * JAXB Providers will fully allow marshalling invalid content, others will fail
150 * on the first validation error.
151 * <p>
152 * Although there is no way to enable validation during the marshal operation,
153 * it is possible that certain types of validation events will be detected
154 * during the operation. These events will be reported to the registered
155 * event handler. If the client application has not registered an event handler
156 * prior to invoking one of the marshal API's, then events will be delivered to
157 * the default event handler which will terminate the marshal operation after
158 * encountering the first error or fatal error.
159 * </blockquote>
160 *
161 * <p>
162 * <a name="supportedProps"></a>
163 * <b>Supported Properties</b><br>
164 * <blockquote>
165 * <p>
166 * All JAXB Providers are required to support the following set of properties.
167 * Some providers may support additional properties.
168 * <dl>
169 * <dt><tt>jaxb.encoding</tt> - value must be a java.lang.String</dd>
170 * <dd>The output encoding to use when marshalling the XML data. The
171 * Marshaller will use "UTF-8" by default if this property is not
172 * specified.</dd>
173 * <dt><tt>jaxb.formatted.output</tt> - value must be a java.lang.Boolean</dd>
174 * <dd>This property controls whether or not the Marshaller will format
175 * the resulting XML data with line breaks and indentation. A
176 * true value for this property indicates human readable indented
177 * xml data, while a false value indicates unformatted xml data.
178 * The Marshaller will default to false (unformatted) if this
179 * property is not specified.</dd>
180 * <dt><tt>jaxb.schemaLocation</tt> - value must be a java.lang.String</dd>
181 * <dd>This property allows the client application to specify an
182 * xsi:schemaLocation attribute in the generated XML data. The format of
183 * the schemaLocation attribute value is discussed in an easy to
184 * understand, non-normative form in
185 * <a href="http://www.w3.org/TR/xmlschema-0/#schemaLocation">Section 5.6
186 * of the W3C XML Schema Part 0: Primer</a> and specified in
187 * <a href="http://www.w3.org/TR/xmlschema-1/#Instance_Document_Constructions">
188 * Section 2.6 of the W3C XML Schema Part 1: Structures</a>.</dd>
189 * <dt><tt>jaxb.noNamespaceSchemaLocation</tt> - value must be a java.lang.String</dd>
190 * <dd>This property allows the client application to specify an
191 * xsi:noNamespaceSchemaLocation attribute in the generated XML
192 * data. The format of the schemaLocation attribute value is discussed in
193 * an easy to understand, non-normative form in
194 * <a href="http://www.w3.org/TR/xmlschema-0/#schemaLocation">Section 5.6
195 * of the W3C XML Schema Part 0: Primer</a> and specified in
196 * <a href="http://www.w3.org/TR/xmlschema-1/#Instance_Document_Constructions">
197 * Section 2.6 of the W3C XML Schema Part 1: Structures</a>.</dd>
198 * </dl>
199 * </blockquote>
200 *
201 * @author <ul><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul>
202 * @version $Revision: 1.28 $ $Date: 2003/01/13 21:15:52 $
203 * @see JAXBContext
204 * @see Validator
205 * @see Unmarshaller
206 * @since JAXB1.0
207 */
208 public interface Marshaller {
209
210 /**
211 * The name of the property used to specify the output encoding in
212 * the marshalled XML data.
213 */
214 public static final String JAXB_ENCODING =
215 "jaxb.encoding";
216
217 /**
218 * The name of the property used to specify whether or not the marshalled
219 * XML data is formated with linefeeds and indentation.
220 */
221 public static final String JAXB_FORMATTED_OUTPUT =
222 "jaxb.formatted.output";
223
224 /**
225 * The name of the property used to specify the xsi:schemaLocation
226 * attribute value to place in the marshalled XML output.
227 */
228 public static final String JAXB_SCHEMA_LOCATION =
229 "jaxb.schemaLocation";
230
231 /**
232 * The name of the property used to specify the the
233 * xsi:noNamespaceSchemaLocation attribute value to place in the marshalled
234 * XML output.
235 */
236 public static final String JAXB_NO_NAMESPACE_SCHEMA_LOCATION =
237 "jaxb.noNamespaceSchemaLocation";
238
239 /**
240 * Marshal the content tree rooted at obj into the specified
241 * <tt>javax.xml.transform.Result</tt>.
242 *
243 * <p>
244 * All JAXB Providers must at least support
245 * {@link javax.xml.transform.dom.DOMResult},
246 * {@link javax.xml.transform.sax.SAXResult}, and
247 * {@link javax.xml.transform.stream.StreamResult}. It can
248 * support other derived classes of <tt>Result</tt> as well.
249 *
250 * @param obj
251 * The content tree to be marshalled.
252 * @param result
253 * XML will be sent to this Result
254 *
255 * @throws JAXBException
256 * If any unexpected problem occurs during the marshalling.
257 * @throws MarshalException
258 * If the {@link ValidationEventHandler ValidationEventHandler}
259 * returns false from its <tt>handleEvent</tt> method or the
260 * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
261 * object reachable from <tt>obj</tt>). See <a href="#objMarshalling">
262 * Marshalling objects</a>.
263 * @throws IllegalArgumentException
264 * If any of the method parameters are null
265 */
266 public void marshal( Object obj, javax.xml.transform.Result result )
267 throws JAXBException;
268
269 /**
270 * Marshal the content tree rooted at obj into an output stream.
271 *
272 * @param obj
273 * The content tree to be marshalled.
274 * @param os
275 * XML will be added to this stream.
276 *
277 * @throws JAXBException
278 * If any unexpected problem occurs during the marshalling.
279 * @throws MarshalException
280 * If the {@link ValidationEventHandler ValidationEventHandler}
281 * returns false from its <tt>handleEvent</tt> method or the
282 * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
283 * object reachable from <tt>obj</tt>). See <a href="#objMarshalling">
284 * Marshalling objects</a>.
285 * @throws IllegalArgumentException
286 * If any of the method parameters are null
287 */
288 public void marshal( Object obj, java.io.OutputStream os )
289 throws JAXBException;
290
291 /**
292 * Marshal the content tree rooted at obj into a Writer.
293 *
294 * @param obj
295 * The content tree to be marshalled.
296 * @param writer
297 * XML will be sent to this writer.
298 *
299 * @throws JAXBException
300 * If any unexpected problem occurs during the marshalling.
301 * @throws MarshalException
302 * If the {@link ValidationEventHandler ValidationEventHandler}
303 * returns false from its <tt>handleEvent</tt> method or the
304 * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
305 * object reachable from <tt>obj</tt>). See <a href="#objMarshalling">
306 * Marshalling objects</a>.
307 * @throws IllegalArgumentException
308 * If any of the method parameters are null
309 */
310 public void marshal( Object obj, java.io.Writer writer )
311 throws JAXBException;
312
313 /**
314 * Marshal the content tree rooted at obj into SAX2 events.
315 *
316 * @param obj
317 * The content tree to be marshalled.
318 * @param handler
319 * XML will be sent to this handler as SAX2 events.
320 *
321 * @throws JAXBException
322 * If any unexpected problem occurs during the marshalling.
323 * @throws MarshalException
324 * If the {@link ValidationEventHandler ValidationEventHandler}
325 * returns false from its <tt>handleEvent</tt> method or the
326 * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
327 * object reachable from <tt>obj</tt>). See <a href="#objMarshalling">
328 * Marshalling objects</a>.
329 * @throws IllegalArgumentException
330 * If any of the method parameters are null
331 */
332 public void marshal( Object obj, org.xml.sax.ContentHandler handler )
333 throws JAXBException;
334
335 /**
336 * Marshal the content tree rooted at obj into a DOM tree.
337 *
338 * @param obj
339 * The content tree to be marshalled.
340 * @param node
341 * DOM nodes will be added as children of this node.
342 * This parameter must be a Node that accepts children
343 * ({@link org.w3c.dom.Document},
344 * {@link org.w3c.dom.DocumentFragment}, or
345 * {@link org.w3c.dom.Element})
346 *
347 * @throws JAXBException
348 * If any unexpected problem occurs during the marshalling.
349 * @throws MarshalException
350 * If the {@link ValidationEventHandler ValidationEventHandler}
351 * returns false from its <tt>handleEvent</tt> method or the
352 * <tt>Marshaller</tt> is unable to marshal <tt>obj</tt> (or any
353 * object reachable from <tt>obj</tt>). See <a href="#objMarshalling">
354 * Marshalling objects</a>.
355 * @throws IllegalArgumentException
356 * If any of the method parameters are null
357 */
358 public void marshal( Object obj, org.w3c.dom.Node node )
359 throws JAXBException;
360
361 /**
362 * Get a DOM tree view of the content tree(Optional).
363 *
364 * If the returned DOM tree is updated, these changes are also
365 * visible in the content tree.
366 * Use {@link #marshal(Object, org.w3c.dom.Node)} to force
367 * a deep copy of the content tree to a DOM representation.
368 *
369 * @param contentTree - JAXB Java representation of XML content
370 *
371 * @return the DOM tree view of the contentTree
372 *
373 * @throws UnsupportedOperationException
374 * If the JAXB provider implementation does not support a
375 * DOM view of the content tree
376 *
377 * @throws IllegalArgumentException
378 * If any of the method parameters are null
379 *
380 * @throws JAXBException
381 * If any unexpected problem occurs
382 *
383 */
384 public org.w3c.dom.Node getNode( java.lang.Object contentTree )
385 throws JAXBException;
386
387 /**
388 * Set the particular property in the underlying implementation of
389 * <tt>Marshaller</tt>. This method can only be used to set one of
390 * the standard JAXB defined properties above or a provider specific
391 * property. Attempting to set an undefined property will result in
392 * a PropertyException being thrown. See <a href="#supportedProps">
393 * Supported Properties</a>.
394 *
395 * @param name the name of the property to be set. This value can either
396 * be specified using one of the constant fields or a user
397 * supplied string.
398 * @param value the value of the property to be set
399 *
400 * @throws PropertyException when there is an error processing the given
401 * property or value
402 * @throws IllegalArgumentException
403 * If the name parameter is null
404 */
405 public void setProperty( String name, Object value )
406 throws PropertyException;
407
408 /**
409 * Get the particular property in the underlying implementation of
410 * <tt>Marshaller</tt>. This method can only be used to get one of
411 * the standard JAXB defined properties above or a provider specific
412 * property. Attempting to get an undefined property will result in
413 * a PropertyException being thrown. See <a href="#supportedProps">
414 * Supported Properties</a>.
415 *
416 * @param name the name of the property to retrieve
417 * @return the value of the requested property
418 *
419 * @throws PropertyException
420 * when there is an error retrieving the given property or value
421 * property name
422 * @throws IllegalArgumentException
423 * If the name parameter is null
424 */
425 public Object getProperty( String name ) throws PropertyException;
426
427 /**
428 * Allow an application to register a validation event handler.
429 * <p>
430 * The validation event handler will be called by the JAXB Provider if any
431 * validation errors are encountered during calls to any of the marshal
432 * API's. If the client application does not register a validation event
433 * handler before invoking one of the marshal methods, then validation
434 * events will be handled by the default event handler which will terminate
435 * the marshal operation after the first error or fatal error is encountered.
436 * <p>
437 * Calling this method with a null parameter will cause the Marshaller
438 * to revert back to the default vefault event handler.
439 *
440 * @param handler the validation event handler
441 * @throws JAXBException if an error was encountered while setting the
442 * event handler
443 */
444 public void setEventHandler( ValidationEventHandler handler )
445 throws JAXBException;
446
447 /**
448 * Return the current event handler or the default event handler if one
449 * hasn't been set.
450 *
451 * @return the current ValidationEventHandler or the default event handler
452 * if it hasn't been set
453 * @throws JAXBException if an error was encountered while getting the
454 * current event handler
455 */
456 public ValidationEventHandler getEventHandler()
457 throws JAXBException;
458
459
460 }
461
462
463