Binder


1   /*
2    * Copyright 2005 Sun Microsystems, Inc. All rights reserved.
3    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
4    */
5   
6   package javax.xml.bind;
7   
8   import org.w3c.dom.Node  ;
9   
10  import javax.xml.validation.Schema  ;
11  
12  /**
13   * Enable synchronization between XML infoset nodes and JAXB objects 
14   * representing same XML document.
15   *
16   * <p>
17   * An instance of this class maintains the association between XML nodes of
18   * an infoset preserving view and a JAXB representation of an XML document. 
19   * Navigation between the two views is provided by the methods
20   * {@link #getXMLNode(Object)} and {@link #getJAXBNode(Object)}.
21   * 
22   * <p>
23   * Modifications can be made to either the infoset preserving view or the 
24   * JAXB representation of the document while the other view remains 
25   * unmodified. The binder is able to synchronize the changes made in the 
26   * modified view back into the other view using the appropriate
27   * Binder update methods, {@link #updateXML(Object, Object)} or 
28   * {@link #updateJAXB(Object)}.
29   * 
30   * <p>
31   * A typical usage scenario is the following:
32   * <ul>
33   *   <li>load XML document into an XML infoset representation</li>
34   *   <li>{@link #unmarshal(Object)} XML infoset view to JAXB view.
35   *       (Note to conserve resources, it is possible to only unmarshal a
36   *       subtree of the XML infoset view to the JAXB view.)</li>
37   *   <li>application access/updates JAXB view of XML document.</li>
38   *   <li>{@link #updateXML(Object)} synchronizes modifications to JAXB view 
39   *       back into the XML infoset view. Update operation preserves as 
40   *       much of original XML infoset as possible (i.e. comments, PI, ...)</li>
41   * </ul>
42   * 
43   * <p>
44   * A Binder instance is created using the factory method 
45   * {@link JAXBContext#createBinder()} or {@link JAXBContext#createBinder(Class)}.
46   *
47   * <p>
48   * The template parameter, <code>XmlNode</code>, is the
49   * root interface/class for the XML infoset preserving representation.
50   * A Binder implementation is required to minimally support
51   * an <code>XmlNode</code> value of <code>org.w3c.dom.Node.class</code>. 
52   * A Binder implementation can support alternative XML infoset 
53   * preserving representations.
54   *
55   * @author
56   *     Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com)
57   *     Joseph Fialli
58   * 
59   * @since JAXB 2.0
60   */
61  public abstract class Binder<XmlNode> {
62      /**
63       * Unmarshal XML infoset view to a JAXB object tree.
64       *
65       * <p>
66       * This method is similar to {@link Unmarshaller#unmarshal(Node)}
67       * with the addition of maintaining the association between XML nodes 
68       * and the produced JAXB objects, enabling future update operations,
69       * {@link #updateXML(Object, Object)} or {@link #updateJAXB(Object)}.
70       *
71       * <p>
72       * When {@link #getSchema()} is non-null, <code>xmlNode</code>
73       * and its descendants is validated during this operation.
74       *
75       * <p>
76       * This method throws {@link UnmarshalException} when the Binder's
77       * {@link JAXBContext} does not have a mapping for the XML element name
78       * or the type, specifiable via <tt>@xsi:type</tt>, of <tt>xmlNode</tt>
79       * to a JAXB mapped class. The method {@link #unmarshal(Object, Class)} 
80       * enables an application to specify the JAXB mapped class that
81       * the <tt>xmlNode</tt> should be mapped to. 
82       *
83       * @param xmlNode 
84       *      the document/element to unmarshal XML data from.
85       *
86       * @return
87       *      the newly created root object of the JAXB object tree.
88       *
89       * @throws JAXBException
90       *      If any unexpected errors occur while unmarshalling
91       * @throws UnmarshalException
92       *     If the {@link ValidationEventHandler ValidationEventHandler}
93       *     returns false from its <tt>handleEvent</tt> method or the 
94       *     <tt>Binder</tt> is unable to perform the XML to Java
95       *     binding.
96       * @throws IllegalArgumentException
97       *      If the node parameter is null
98       */
99      public abstract Object   unmarshal( XmlNode xmlNode ) throws JAXBException;
100 
101     /**
102      * Unmarshal XML root element by provided <tt>declaredType</tt> 
103      * to a JAXB object tree.
104      *
105      * <p>
106      * Implements <a HREF="Unmarshaller.html#unmarshalByDeclaredType">Unmarshal by Declared Type</a>
107      * 
108      * <p>
109      * This method is similar to {@link Unmarshaller#unmarshal(Node, Class)}
110      * with the addition of maintaining the association between XML nodes 
111      * and the produced JAXB objects, enabling future update operations,
112      * {@link #updateXML(Object, Object)} or {@link #updateJAXB(Object)}.
113      *
114      * <p>
115      * When {@link #getSchema()} is non-null, <code>xmlNode</code>
116      * and its descendants is validated during this operation.
117      *
118      * @param xmlNode 
119      *      the document/element to unmarshal XML data from.
120      * @param declaredType
121      *      appropriate JAXB mapped class to hold <tt>node</tt>'s XML data.
122      *
123      * @return
124      * <a HREF="#unmarshalDeclaredTypeReturn">JAXB Element</a> representation 
125      * of <tt>node</tt>
126      *
127      * @throws JAXBException
128      *      If any unexpected errors occur while unmarshalling
129      * @throws UnmarshalException
130      *     If the {@link ValidationEventHandler ValidationEventHandler}
131      *     returns false from its <tt>handleEvent</tt> method or the 
132      *     <tt>Binder</tt> is unable to perform the XML to Java
133      *     binding.
134      * @throws IllegalArgumentException
135      *      If any of the input parameters are null
136      * @since JAXB2.0
137      */
138     public abstract <T> JAXBElement<T> 
139     unmarshal( XmlNode xmlNode, Class  <T> declaredType ) 
140     throws JAXBException;
141 
142     /**
143      * Marshal a JAXB object tree to a new XML document.
144      *
145      * <p>
146      * This method is similar to {@link Marshaller#marshal(Object, Node)}
147      * with the addition of maintaining the association between JAXB objects 
148      * and the produced XML nodes,
149      * enabling future update operations such as 
150      * {@link #updateXML(Object, Object)} or {@link #updateJAXB(Object)}.
151      *
152      * <p>
153      * When {@link #getSchema()} is non-null, the marshalled
154      * xml content is validated during this operation.
155      *
156      * @param jaxbObject
157      *      The content tree to be marshalled. 
158      * @param xmlNode
159      *      The parameter must be a Node that accepts children.
160      *
161      * @throws JAXBException
162      *      If any unexpected problem occurs during the marshalling.
163      * @throws MarshalException
164      *      If the {@link ValidationEventHandler ValidationEventHandler}
165      *      returns false from its <tt>handleEvent</tt> method or the 
166      *      <tt>Binder</tt> is unable to marshal <tt>jaxbObject</tt> (or any 
167      *      object reachable from <tt>jaxbObject</tt>).
168      * 
169      * @throws IllegalArgumentException
170      *      If any of the method parameters are null
171      */
172     public abstract void marshal( Object   jaxbObject, XmlNode xmlNode ) throws JAXBException;
173 
174     /**
175      * Gets the XML element associated with the given JAXB object.
176      *
177      * <p>
178      * Once a JAXB object tree is associated with an XML fragment,
179      * this method enables navigation between the two trees.
180      *
181      * <p>
182      * An association between an XML element and a JAXB object is
183      * established by the bind methods and the update methods.
184      * Note that this association is partial; not all XML elements
185      * have associated JAXB objects, and not all JAXB objects have
186      * associated XML elements.
187      *
188      * @param jaxbObject An instance that is reachable from a prior 
189      *                   call to a bind or update method that returned
190      *                   a JAXB object tree.
191      *
192      * @return
193      *      null if the specified JAXB object is not known to this
194      *      {@link Binder}, or if it is not associated with an
195      *      XML element.
196      *
197      * @throws IllegalArgumentException
198      *      If the jaxbObject parameter is null
199      */
200     public abstract XmlNode getXMLNode( Object   jaxbObject );
201 
202     /**
203      * Gets the JAXB object associated with the given XML element.
204      *
205      * <p>
206      * Once a JAXB object tree is associated with an XML fragment,
207      * this method enables navigation between the two trees.
208      *
209      * <p>
210      * An association between an XML element and a JAXB object is
211      * established by the unmarshal, marshal and update methods.
212      * Note that this association is partial; not all XML elements
213      * have associated JAXB objects, and not all JAXB objects have
214      * associated XML elements.
215      *
216      * @return
217      *      null if the specified XML node is not known to this
218      *      {@link Binder}, or if it is not associated with a
219      *      JAXB object.
220      *
221      * @throws IllegalArgumentException
222      *      If the node parameter is null
223      */
224     public abstract Object   getJAXBNode( XmlNode xmlNode );
225 
226     /**
227      * Takes an JAXB object and updates
228      * its associated XML node and its descendants.
229      *
230      * <p>
231      * This is a convenience method of:
232      * <pre>
233      * updateXML( jaxbObject, getXMLNode(jaxbObject));
234      * </pre>
235      *
236      * @throws JAXBException
237      *      If any unexpected problem occurs updating corresponding XML content.
238      * @throws IllegalArgumentException
239      *      If the jaxbObject parameter is null
240      */
241     public abstract XmlNode updateXML( Object   jaxbObject ) throws JAXBException;
242 
243     /**
244      * Changes in JAXB object tree are updated in its associated XML parse tree.
245      *
246      * <p>
247      * This operation can be thought of as an "in-place" marshalling.
248      * The difference is that instead of creating a whole new XML tree,
249      * this operation updates an existing tree while trying to preserve
250      * the XML as much as possible.
251      *
252      * <p>
253      * For example, unknown elements/attributes in XML that were not bound
254      * to JAXB will be left untouched (whereas a marshalling operation
255      * would create a new tree that doesn't contain any of those.)
256      *
257      * <p>
258      * As a side-effect, this operation updates the association between
259      * XML nodes and JAXB objects.
260      *
261      * @param jaxbObject root of potentially modified JAXB object tree
262      * @param xmlNode    root of update target XML parse tree
263      *
264      * @return
265      *      Returns the updated XML node. Typically, this is the same
266      *      node you passed in as <i>xmlNode</i>, but it maybe
267      *      a different object, for example when the tag name of the object
268      *      has changed.
269      *
270      * @throws JAXBException
271      *      If any unexpected problem occurs updating corresponding XML content.
272      * @throws IllegalArgumentException
273      *      If any of the input parameters are null
274      */
275     public abstract XmlNode updateXML( Object   jaxbObject, XmlNode xmlNode ) throws JAXBException;
276 
277     /**
278      * Takes an XML node and updates its associated JAXB object and its descendants.
279      *
280      * <p>
281      * This operation can be thought of as an "in-place" unmarshalling.
282      * The difference is that instead of creating a whole new JAXB tree,
283      * this operation updates an existing tree, reusing as much JAXB objects
284      * as possible.
285      *
286      * <p>
287      * As a side-effect, this operation updates the association between
288      * XML nodes and JAXB objects.
289      *
290      * @return
291      *      Returns the updated JAXB object. Typically, this is the same
292      *      object that was returned from earlier
293      *      {@link #marshal(Object,Object)} or
294      *      {@link #updateJAXB(Object)} method invocation,
295      *      but it maybe
296      *      a different object, for example when the name of the XML
297      *      element has changed.
298      * 
299      * @throws JAXBException
300      *      If any unexpected problem occurs updating corresponding JAXB mapped content.
301      * @throws IllegalArgumentException
302      *      If node parameter is null
303      */
304     public abstract Object   updateJAXB( XmlNode xmlNode ) throws JAXBException;
305 
306 
307     /**
308      * Specifies whether marshal, unmarshal and update methods
309      * performs validation on their XML content.
310      *
311      * @param schema set to null to disable validation.
312      *
313      * @see Unmarshaller#setSchema(Schema)
314      */
315     public abstract void setSchema( Schema   schema );
316 
317     /**
318      * Gets the last {@link Schema} object (including null) set by the
319      * {@link #setSchema(Schema)} method.
320      *
321      * @return the Schema object for validation or null if not present
322      */
323     public abstract Schema   getSchema();
324 
325     /**
326      * Allow an application to register a <tt>ValidationEventHandler</tt>.
327      * <p>
328      * The <tt>ValidationEventHandler</tt> will be called by the JAXB Provider
329      * if any validation errors are encountered during calls to any of the
330      * Binder unmarshal, marshal and update methods.  
331      * 
332      * <p>
333      * Calling this method with a null parameter will cause the Binder
334      * to revert back to the default default event handler.
335      *
336      * @param handler the validation event handler
337      * @throws JAXBException if an error was encountered while setting the
338      *         event handler
339      */
340     public abstract void setEventHandler( ValidationEventHandler handler ) throws JAXBException;
341 
342     /**
343      * Return the current event handler or the default event handler if one
344      * hasn't been set.
345      *
346      * @return the current ValidationEventHandler or the default event handler
347      *         if it hasn't been set
348      * @throws JAXBException if an error was encountered while getting the
349      *         current event handler
350      */
351     public abstract ValidationEventHandler getEventHandler() throws JAXBException;
352 
353     /**
354      * 
355      * Set the particular property in the underlying implementation of
356      * <tt>Binder</tt>.  This method can only be used to set one of
357      * the standard JAXB defined unmarshal/marshal properties 
358      * or a provider specific property for binder, unmarshal or marshal.
359      * Attempting to set an undefined property will result in
360      * a PropertyException being thrown.  See 
361      * <a HREF="Unmarshaller.html#supportedProps">Supported Unmarshal Properties</a>
362      * and
363      * <a HREF="Marshaller.html#supportedProps">Supported Marshal Properties</a>.
364      *
365      * @param name the name of the property to be set. This value can either
366      *              be specified using one of the constant fields or a user
367      *              supplied string.
368      * @param value the value of the property to be set
369      *
370      * @throws PropertyException when there is an error processing the given
371      *                            property or value
372      * @throws IllegalArgumentException
373      *      If the name parameter is null
374      */
375     abstract public void setProperty( String   name, Object   value ) throws PropertyException;
376 
377 
378     /**
379      * Get the particular property in the underlying implementation of
380      * <tt>Binder</tt>.  This method can only 
381      * be used to get one of
382      * the standard JAXB defined unmarshal/marshal properties 
383      * or a provider specific property for binder, unmarshal or marshal.  
384      * Attempting to get an undefined property will result in
385      * a PropertyException being thrown.  See 
386      * <a HREF="Unmarshaller.html#supportedProps">Supported Unmarshal Properties</a>
387      * and
388      * <a HREF="Marshaller.html#supportedProps">Supported Marshal Properties</a>.
389      *
390      * @param name the name of the property to retrieve
391      * @return the value of the requested property
392      *
393      * @throws PropertyException
394      *      when there is an error retrieving the given property or value
395      *      property name
396      * @throws IllegalArgumentException
397      *      If the name parameter is null
398      */
399     abstract public Object   getProperty( String   name ) throws PropertyException;
400 
401 }
402
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags