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