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