78 * 79 * @since 1.6, JAXB 2.0 80 */ 81 public abstract class Binder<XmlNode> { 82 /** 83 * Unmarshal XML infoset view to a JAXB object tree. 84 * 85 * <p> 86 * This method is similar to {@link Unmarshaller#unmarshal(Node)} 87 * with the addition of maintaining the association between XML nodes 88 * and the produced JAXB objects, enabling future update operations, 89 * {@link #updateXML(Object, Object)} or {@link #updateJAXB(Object)}. 90 * 91 * <p> 92 * When {@link #getSchema()} is non-null, <code>xmlNode</code> 93 * and its descendants is validated during this operation. 94 * 95 * <p> 96 * This method throws {@link UnmarshalException} when the Binder's 97 * {@link JAXBContext} does not have a mapping for the XML element name 98 * or the type, specifiable via <tt>@xsi:type</tt>, of <tt>xmlNode</tt> 99 * to a JAXB mapped class. The method {@link #unmarshal(Object, Class)} 100 * enables an application to specify the JAXB mapped class that 101 * the <tt>xmlNode</tt> should be mapped to. 102 * 103 * @param xmlNode 104 * the document/element to unmarshal XML data from. 105 * 106 * @return 107 * the newly created root object of the JAXB object tree. 108 * 109 * @throws JAXBException 110 * If any unexpected errors occur while unmarshalling 111 * @throws UnmarshalException 112 * If the {@link ValidationEventHandler ValidationEventHandler} 113 * returns false from its <tt>handleEvent</tt> method or the 114 * <tt>Binder</tt> is unable to perform the XML to Java 115 * binding. 116 * @throws IllegalArgumentException 117 * If the node parameter is null 118 */ 119 public abstract Object unmarshal( XmlNode xmlNode ) throws JAXBException; 120 121 /** 122 * Unmarshal XML root element by provided <tt>declaredType</tt> 123 * to a JAXB object tree. 124 * 125 * <p> 126 * Implements <a href="Unmarshaller.html#unmarshalByDeclaredType">Unmarshal by Declared Type</a> 127 * 128 * <p> 129 * This method is similar to {@link Unmarshaller#unmarshal(Node, Class)} 130 * with the addition of maintaining the association between XML nodes 131 * and the produced JAXB objects, enabling future update operations, 132 * {@link #updateXML(Object, Object)} or {@link #updateJAXB(Object)}. 133 * 134 * <p> 135 * When {@link #getSchema()} is non-null, <code>xmlNode</code> 136 * and its descendants is validated during this operation. 137 * 138 * @param xmlNode 139 * the document/element to unmarshal XML data from. 140 * @param declaredType 141 * appropriate JAXB mapped class to hold <tt>node</tt>'s XML data. 142 * 143 * @return 144 * <a href="JAXBElement.html">JAXB Element</a> representation 145 * of <tt>node</tt> 146 * 147 * @throws JAXBException 148 * If any unexpected errors occur while unmarshalling 149 * @throws UnmarshalException 150 * If the {@link ValidationEventHandler ValidationEventHandler} 151 * returns false from its <tt>handleEvent</tt> method or the 152 * <tt>Binder</tt> is unable to perform the XML to Java 153 * binding. 154 * @throws IllegalArgumentException 155 * If any of the input parameters are null 156 * @since 1.6, JAXB 2.0 157 */ 158 public abstract <T> JAXBElement<T> 159 unmarshal( XmlNode xmlNode, Class<T> declaredType ) 160 throws JAXBException; 161 162 /** 163 * Marshal a JAXB object tree to a new XML document. 164 * 165 * <p> 166 * This method is similar to {@link Marshaller#marshal(Object, Node)} 167 * with the addition of maintaining the association between JAXB objects 168 * and the produced XML nodes, 169 * enabling future update operations such as 170 * {@link #updateXML(Object, Object)} or {@link #updateJAXB(Object)}. 171 * 172 * <p> 173 * When {@link #getSchema()} is non-null, the marshalled 174 * xml content is validated during this operation. 175 * 176 * @param jaxbObject 177 * The content tree to be marshalled. 178 * @param xmlNode 179 * The parameter must be a Node that accepts children. 180 * 181 * @throws JAXBException 182 * If any unexpected problem occurs during the marshalling. 183 * @throws MarshalException 184 * If the {@link ValidationEventHandler ValidationEventHandler} 185 * returns false from its <tt>handleEvent</tt> method or the 186 * <tt>Binder</tt> is unable to marshal <tt>jaxbObject</tt> (or any 187 * object reachable from <tt>jaxbObject</tt>). 188 * 189 * @throws IllegalArgumentException 190 * If any of the method parameters are null 191 */ 192 public abstract void marshal( Object jaxbObject, XmlNode xmlNode ) throws JAXBException; 193 194 /** 195 * Gets the XML element associated with the given JAXB object. 196 * 197 * <p> 198 * Once a JAXB object tree is associated with an XML fragment, 199 * this method enables navigation between the two trees. 200 * 201 * <p> 202 * An association between an XML element and a JAXB object is 203 * established by the bind methods and the update methods. 204 * Note that this association is partial; not all XML elements 205 * have associated JAXB objects, and not all JAXB objects have 206 * associated XML elements. 207 * 326 327 /** 328 * Specifies whether marshal, unmarshal and update methods 329 * performs validation on their XML content. 330 * 331 * @param schema set to null to disable validation. 332 * 333 * @see Unmarshaller#setSchema(Schema) 334 */ 335 public abstract void setSchema( Schema schema ); 336 337 /** 338 * Gets the last {@link Schema} object (including null) set by the 339 * {@link #setSchema(Schema)} method. 340 * 341 * @return the Schema object for validation or null if not present 342 */ 343 public abstract Schema getSchema(); 344 345 /** 346 * Allow an application to register a <tt>ValidationEventHandler</tt>. 347 * <p> 348 * The <tt>ValidationEventHandler</tt> will be called by the JAXB Provider 349 * if any validation errors are encountered during calls to any of the 350 * Binder unmarshal, marshal and update methods. 351 * 352 * <p> 353 * Calling this method with a null parameter will cause the Binder 354 * to revert back to the default default event handler. 355 * 356 * @param handler the validation event handler 357 * @throws JAXBException if an error was encountered while setting the 358 * event handler 359 */ 360 public abstract void setEventHandler( ValidationEventHandler handler ) throws JAXBException; 361 362 /** 363 * Return the current event handler or the default event handler if one 364 * hasn't been set. 365 * 366 * @return the current ValidationEventHandler or the default event handler 367 * if it hasn't been set 368 * @throws JAXBException if an error was encountered while getting the 369 * current event handler 370 */ 371 public abstract ValidationEventHandler getEventHandler() throws JAXBException; 372 373 /** 374 * 375 * Set the particular property in the underlying implementation of 376 * <tt>Binder</tt>. This method can only be used to set one of 377 * the standard JAXB defined unmarshal/marshal properties 378 * or a provider specific property for binder, unmarshal or marshal. 379 * Attempting to set an undefined property will result in 380 * a PropertyException being thrown. See 381 * <a href="Unmarshaller.html#supportedProps">Supported Unmarshal Properties</a> 382 * and 383 * <a href="Marshaller.html#supportedProps">Supported Marshal Properties</a>. 384 * 385 * @param name the name of the property to be set. This value can either 386 * be specified using one of the constant fields or a user 387 * supplied string. 388 * @param value the value of the property to be set 389 * 390 * @throws PropertyException when there is an error processing the given 391 * property or value 392 * @throws IllegalArgumentException 393 * If the name parameter is null 394 */ 395 abstract public void setProperty( String name, Object value ) throws PropertyException; 396 397 398 /** 399 * Get the particular property in the underlying implementation of 400 * <tt>Binder</tt>. This method can only 401 * be used to get one of 402 * the standard JAXB defined unmarshal/marshal properties 403 * or a provider specific property for binder, unmarshal or marshal. 404 * Attempting to get an undefined property will result in 405 * a PropertyException being thrown. See 406 * <a href="Unmarshaller.html#supportedProps">Supported Unmarshal Properties</a> 407 * and 408 * <a href="Marshaller.html#supportedProps">Supported Marshal Properties</a>. 409 * 410 * @param name the name of the property to retrieve 411 * @return the value of the requested property 412 * 413 * @throws PropertyException 414 * when there is an error retrieving the given property or value 415 * property name 416 * @throws IllegalArgumentException 417 * If the name parameter is null 418 */ 419 abstract public Object getProperty( String name ) throws PropertyException; 420 | 78 * 79 * @since 1.6, JAXB 2.0 80 */ 81 public abstract class Binder<XmlNode> { 82 /** 83 * Unmarshal XML infoset view to a JAXB object tree. 84 * 85 * <p> 86 * This method is similar to {@link Unmarshaller#unmarshal(Node)} 87 * with the addition of maintaining the association between XML nodes 88 * and the produced JAXB objects, enabling future update operations, 89 * {@link #updateXML(Object, Object)} or {@link #updateJAXB(Object)}. 90 * 91 * <p> 92 * When {@link #getSchema()} is non-null, <code>xmlNode</code> 93 * and its descendants is validated during this operation. 94 * 95 * <p> 96 * This method throws {@link UnmarshalException} when the Binder's 97 * {@link JAXBContext} does not have a mapping for the XML element name 98 * or the type, specifiable via {@code @xsi:type}, of {@code xmlNode} 99 * to a JAXB mapped class. The method {@link #unmarshal(Object, Class)} 100 * enables an application to specify the JAXB mapped class that 101 * the {@code xmlNode} should be mapped to. 102 * 103 * @param xmlNode 104 * the document/element to unmarshal XML data from. 105 * 106 * @return 107 * the newly created root object of the JAXB object tree. 108 * 109 * @throws JAXBException 110 * If any unexpected errors occur while unmarshalling 111 * @throws UnmarshalException 112 * If the {@link ValidationEventHandler ValidationEventHandler} 113 * returns false from its {@code handleEvent} method or the 114 * {@code Binder} is unable to perform the XML to Java 115 * binding. 116 * @throws IllegalArgumentException 117 * If the node parameter is null 118 */ 119 public abstract Object unmarshal( XmlNode xmlNode ) throws JAXBException; 120 121 /** 122 * Unmarshal XML root element by provided {@code declaredType} 123 * to a JAXB object tree. 124 * 125 * <p> 126 * Implements <a href="Unmarshaller.html#unmarshalByDeclaredType">Unmarshal by Declared Type</a> 127 * 128 * <p> 129 * This method is similar to {@link Unmarshaller#unmarshal(Node, Class)} 130 * with the addition of maintaining the association between XML nodes 131 * and the produced JAXB objects, enabling future update operations, 132 * {@link #updateXML(Object, Object)} or {@link #updateJAXB(Object)}. 133 * 134 * <p> 135 * When {@link #getSchema()} is non-null, <code>xmlNode</code> 136 * and its descendants is validated during this operation. 137 * 138 * @param xmlNode 139 * the document/element to unmarshal XML data from. 140 * @param declaredType 141 * appropriate JAXB mapped class to hold {@code node}'s XML data. 142 * 143 * @return 144 * <a href="JAXBElement.html">JAXB Element</a> representation 145 * of {@code node} 146 * 147 * @throws JAXBException 148 * If any unexpected errors occur while unmarshalling 149 * @throws UnmarshalException 150 * If the {@link ValidationEventHandler ValidationEventHandler} 151 * returns false from its {@code handleEvent} method or the 152 * {@code Binder} is unable to perform the XML to Java 153 * binding. 154 * @throws IllegalArgumentException 155 * If any of the input parameters are null 156 * @since 1.6, JAXB 2.0 157 */ 158 public abstract <T> JAXBElement<T> 159 unmarshal( XmlNode xmlNode, Class<T> declaredType ) 160 throws JAXBException; 161 162 /** 163 * Marshal a JAXB object tree to a new XML document. 164 * 165 * <p> 166 * This method is similar to {@link Marshaller#marshal(Object, Node)} 167 * with the addition of maintaining the association between JAXB objects 168 * and the produced XML nodes, 169 * enabling future update operations such as 170 * {@link #updateXML(Object, Object)} or {@link #updateJAXB(Object)}. 171 * 172 * <p> 173 * When {@link #getSchema()} is non-null, the marshalled 174 * xml content is validated during this operation. 175 * 176 * @param jaxbObject 177 * The content tree to be marshalled. 178 * @param xmlNode 179 * The parameter must be a Node that accepts children. 180 * 181 * @throws JAXBException 182 * If any unexpected problem occurs during the marshalling. 183 * @throws MarshalException 184 * If the {@link ValidationEventHandler ValidationEventHandler} 185 * returns false from its {@code handleEvent} method or the 186 * {@code Binder} is unable to marshal {@code jaxbObject} (or any 187 * object reachable from {@code jaxbObject}). 188 * 189 * @throws IllegalArgumentException 190 * If any of the method parameters are null 191 */ 192 public abstract void marshal( Object jaxbObject, XmlNode xmlNode ) throws JAXBException; 193 194 /** 195 * Gets the XML element associated with the given JAXB object. 196 * 197 * <p> 198 * Once a JAXB object tree is associated with an XML fragment, 199 * this method enables navigation between the two trees. 200 * 201 * <p> 202 * An association between an XML element and a JAXB object is 203 * established by the bind methods and the update methods. 204 * Note that this association is partial; not all XML elements 205 * have associated JAXB objects, and not all JAXB objects have 206 * associated XML elements. 207 * 326 327 /** 328 * Specifies whether marshal, unmarshal and update methods 329 * performs validation on their XML content. 330 * 331 * @param schema set to null to disable validation. 332 * 333 * @see Unmarshaller#setSchema(Schema) 334 */ 335 public abstract void setSchema( Schema schema ); 336 337 /** 338 * Gets the last {@link Schema} object (including null) set by the 339 * {@link #setSchema(Schema)} method. 340 * 341 * @return the Schema object for validation or null if not present 342 */ 343 public abstract Schema getSchema(); 344 345 /** 346 * Allow an application to register a {@code ValidationEventHandler}. 347 * <p> 348 * The {@code ValidationEventHandler} will be called by the JAXB Provider 349 * if any validation errors are encountered during calls to any of the 350 * Binder unmarshal, marshal and update methods. 351 * 352 * <p> 353 * Calling this method with a null parameter will cause the Binder 354 * to revert back to the default default event handler. 355 * 356 * @param handler the validation event handler 357 * @throws JAXBException if an error was encountered while setting the 358 * event handler 359 */ 360 public abstract void setEventHandler( ValidationEventHandler handler ) throws JAXBException; 361 362 /** 363 * Return the current event handler or the default event handler if one 364 * hasn't been set. 365 * 366 * @return the current ValidationEventHandler or the default event handler 367 * if it hasn't been set 368 * @throws JAXBException if an error was encountered while getting the 369 * current event handler 370 */ 371 public abstract ValidationEventHandler getEventHandler() throws JAXBException; 372 373 /** 374 * 375 * Set the particular property in the underlying implementation of 376 * {@code Binder}. This method can only be used to set one of 377 * the standard JAXB defined unmarshal/marshal properties 378 * or a provider specific property for binder, unmarshal or marshal. 379 * Attempting to set an undefined property will result in 380 * a PropertyException being thrown. See 381 * <a href="Unmarshaller.html#supportedProps">Supported Unmarshal Properties</a> 382 * and 383 * <a href="Marshaller.html#supportedProps">Supported Marshal Properties</a>. 384 * 385 * @param name the name of the property to be set. This value can either 386 * be specified using one of the constant fields or a user 387 * supplied string. 388 * @param value the value of the property to be set 389 * 390 * @throws PropertyException when there is an error processing the given 391 * property or value 392 * @throws IllegalArgumentException 393 * If the name parameter is null 394 */ 395 abstract public void setProperty( String name, Object value ) throws PropertyException; 396 397 398 /** 399 * Get the particular property in the underlying implementation of 400 * {@code Binder}. This method can only 401 * be used to get one of 402 * the standard JAXB defined unmarshal/marshal properties 403 * or a provider specific property for binder, unmarshal or marshal. 404 * Attempting to get an undefined property will result in 405 * a PropertyException being thrown. See 406 * <a href="Unmarshaller.html#supportedProps">Supported Unmarshal Properties</a> 407 * and 408 * <a href="Marshaller.html#supportedProps">Supported Marshal Properties</a>. 409 * 410 * @param name the name of the property to retrieve 411 * @return the value of the requested property 412 * 413 * @throws PropertyException 414 * when there is an error retrieving the given property or value 415 * property name 416 * @throws IllegalArgumentException 417 * If the name parameter is null 418 */ 419 abstract public Object getProperty( String name ) throws PropertyException; 420 |