001: /*
002: * Copyright 2005 Sun Microsystems, Inc. All rights reserved.
003: * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
004: */
005:
006: package javax.xml.bind;
007:
008: import org.w3c.dom.Node;
009:
010: import javax.xml.validation.Schema;
011:
012: /**
013: * Enable synchronization between XML infoset nodes and JAXB objects
014: * representing same XML document.
015: *
016: * <p>
017: * An instance of this class maintains the association between XML nodes of
018: * an infoset preserving view and a JAXB representation of an XML document.
019: * Navigation between the two views is provided by the methods
020: * {@link #getXMLNode(Object)} and {@link #getJAXBNode(Object)}.
021: *
022: * <p>
023: * Modifications can be made to either the infoset preserving view or the
024: * JAXB representation of the document while the other view remains
025: * unmodified. The binder is able to synchronize the changes made in the
026: * modified view back into the other view using the appropriate
027: * Binder update methods, {@link #updateXML(Object, Object)} or
028: * {@link #updateJAXB(Object)}.
029: *
030: * <p>
031: * A typical usage scenario is the following:
032: * <ul>
033: * <li>load XML document into an XML infoset representation</li>
034: * <li>{@link #unmarshal(Object)} XML infoset view to JAXB view.
035: * (Note to conserve resources, it is possible to only unmarshal a
036: * subtree of the XML infoset view to the JAXB view.)</li>
037: * <li>application access/updates JAXB view of XML document.</li>
038: * <li>{@link #updateXML(Object)} synchronizes modifications to JAXB view
039: * back into the XML infoset view. Update operation preserves as
040: * much of original XML infoset as possible (i.e. comments, PI, ...)</li>
041: * </ul>
042: *
043: * <p>
044: * A Binder instance is created using the factory method
045: * {@link JAXBContext#createBinder()} or {@link JAXBContext#createBinder(Class)}.
046: *
047: * <p>
048: * The template parameter, <code>XmlNode</code>, is the
049: * root interface/class for the XML infoset preserving representation.
050: * A Binder implementation is required to minimally support
051: * an <code>XmlNode</code> value of <code>org.w3c.dom.Node.class</code>.
052: * A Binder implementation can support alternative XML infoset
053: * preserving representations.
054: *
055: * @author
056: * Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com)
057: * Joseph Fialli
058: *
059: * @since JAXB 2.0
060: */
061: public abstract class Binder<XmlNode> {
062: /**
063: * Unmarshal XML infoset view to a JAXB object tree.
064: *
065: * <p>
066: * This method is similar to {@link Unmarshaller#unmarshal(Node)}
067: * with the addition of maintaining the association between XML nodes
068: * and the produced JAXB objects, enabling future update operations,
069: * {@link #updateXML(Object, Object)} or {@link #updateJAXB(Object)}.
070: *
071: * <p>
072: * When {@link #getSchema()} is non-null, <code>xmlNode</code>
073: * and its descendants is validated during this operation.
074: *
075: * <p>
076: * This method throws {@link UnmarshalException} when the Binder's
077: * {@link JAXBContext} does not have a mapping for the XML element name
078: * or the type, specifiable via <tt>@xsi:type</tt>, of <tt>xmlNode</tt>
079: * to a JAXB mapped class. The method {@link #unmarshal(Object, Class)}
080: * enables an application to specify the JAXB mapped class that
081: * the <tt>xmlNode</tt> should be mapped to.
082: *
083: * @param xmlNode
084: * the document/element to unmarshal XML data from.
085: *
086: * @return
087: * the newly created root object of the JAXB object tree.
088: *
089: * @throws JAXBException
090: * If any unexpected errors occur while unmarshalling
091: * @throws UnmarshalException
092: * If the {@link ValidationEventHandler ValidationEventHandler}
093: * returns false from its <tt>handleEvent</tt> method or the
094: * <tt>Binder</tt> is unable to perform the XML to Java
095: * binding.
096: * @throws IllegalArgumentException
097: * If the node parameter is null
098: */
099: public abstract Object unmarshal(XmlNode xmlNode)
100: throws JAXBException;
101:
102: /**
103: * Unmarshal XML root element by provided <tt>declaredType</tt>
104: * to a JAXB object tree.
105: *
106: * <p>
107: * Implements <a href="Unmarshaller.html#unmarshalByDeclaredType">Unmarshal by Declared Type</a>
108: *
109: * <p>
110: * This method is similar to {@link Unmarshaller#unmarshal(Node, Class)}
111: * with the addition of maintaining the association between XML nodes
112: * and the produced JAXB objects, enabling future update operations,
113: * {@link #updateXML(Object, Object)} or {@link #updateJAXB(Object)}.
114: *
115: * <p>
116: * When {@link #getSchema()} is non-null, <code>xmlNode</code>
117: * and its descendants is validated during this operation.
118: *
119: * @param xmlNode
120: * the document/element to unmarshal XML data from.
121: * @param declaredType
122: * appropriate JAXB mapped class to hold <tt>node</tt>'s XML data.
123: *
124: * @return
125: * <a href="#unmarshalDeclaredTypeReturn">JAXB Element</a> representation
126: * of <tt>node</tt>
127: *
128: * @throws JAXBException
129: * If any unexpected errors occur while unmarshalling
130: * @throws UnmarshalException
131: * If the {@link ValidationEventHandler ValidationEventHandler}
132: * returns false from its <tt>handleEvent</tt> method or the
133: * <tt>Binder</tt> is unable to perform the XML to Java
134: * binding.
135: * @throws IllegalArgumentException
136: * If any of the input parameters are null
137: * @since JAXB2.0
138: */
139: public abstract <T> JAXBElement<T> unmarshal(XmlNode xmlNode,
140: Class<T> declaredType) 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)
173: throws JAXBException;
174:
175: /**
176: * Gets the XML element associated with the given JAXB object.
177: *
178: * <p>
179: * Once a JAXB object tree is associated with an XML fragment,
180: * this method enables navigation between the two trees.
181: *
182: * <p>
183: * An association between an XML element and a JAXB object is
184: * established by the bind methods and the update methods.
185: * Note that this association is partial; not all XML elements
186: * have associated JAXB objects, and not all JAXB objects have
187: * associated XML elements.
188: *
189: * @param jaxbObject An instance that is reachable from a prior
190: * call to a bind or update method that returned
191: * a JAXB object tree.
192: *
193: * @return
194: * null if the specified JAXB object is not known to this
195: * {@link Binder}, or if it is not associated with an
196: * XML element.
197: *
198: * @throws IllegalArgumentException
199: * If the jaxbObject parameter is null
200: */
201: public abstract XmlNode getXMLNode(Object jaxbObject);
202:
203: /**
204: * Gets the JAXB object associated with the given XML element.
205: *
206: * <p>
207: * Once a JAXB object tree is associated with an XML fragment,
208: * this method enables navigation between the two trees.
209: *
210: * <p>
211: * An association between an XML element and a JAXB object is
212: * established by the unmarshal, marshal and update methods.
213: * Note that this association is partial; not all XML elements
214: * have associated JAXB objects, and not all JAXB objects have
215: * associated XML elements.
216: *
217: * @return
218: * null if the specified XML node is not known to this
219: * {@link Binder}, or if it is not associated with a
220: * JAXB object.
221: *
222: * @throws IllegalArgumentException
223: * If the node parameter is null
224: */
225: public abstract Object getJAXBNode(XmlNode xmlNode);
226:
227: /**
228: * Takes an JAXB object and updates
229: * its associated XML node and its descendants.
230: *
231: * <p>
232: * This is a convenience method of:
233: * <pre>
234: * updateXML( jaxbObject, getXMLNode(jaxbObject));
235: * </pre>
236: *
237: * @throws JAXBException
238: * If any unexpected problem occurs updating corresponding XML content.
239: * @throws IllegalArgumentException
240: * If the jaxbObject parameter is null
241: */
242: public abstract XmlNode updateXML(Object jaxbObject)
243: throws JAXBException;
244:
245: /**
246: * Changes in JAXB object tree are updated in its associated XML parse tree.
247: *
248: * <p>
249: * This operation can be thought of as an "in-place" marshalling.
250: * The difference is that instead of creating a whole new XML tree,
251: * this operation updates an existing tree while trying to preserve
252: * the XML as much as possible.
253: *
254: * <p>
255: * For example, unknown elements/attributes in XML that were not bound
256: * to JAXB will be left untouched (whereas a marshalling operation
257: * would create a new tree that doesn't contain any of those.)
258: *
259: * <p>
260: * As a side-effect, this operation updates the association between
261: * XML nodes and JAXB objects.
262: *
263: * @param jaxbObject root of potentially modified JAXB object tree
264: * @param xmlNode root of update target XML parse tree
265: *
266: * @return
267: * Returns the updated XML node. Typically, this is the same
268: * node you passed in as <i>xmlNode</i>, but it maybe
269: * a different object, for example when the tag name of the object
270: * has changed.
271: *
272: * @throws JAXBException
273: * If any unexpected problem occurs updating corresponding XML content.
274: * @throws IllegalArgumentException
275: * If any of the input parameters are null
276: */
277: public abstract XmlNode updateXML(Object jaxbObject, XmlNode xmlNode)
278: throws JAXBException;
279:
280: /**
281: * Takes an XML node and updates its associated JAXB object and its descendants.
282: *
283: * <p>
284: * This operation can be thought of as an "in-place" unmarshalling.
285: * The difference is that instead of creating a whole new JAXB tree,
286: * this operation updates an existing tree, reusing as much JAXB objects
287: * as possible.
288: *
289: * <p>
290: * As a side-effect, this operation updates the association between
291: * XML nodes and JAXB objects.
292: *
293: * @return
294: * Returns the updated JAXB object. Typically, this is the same
295: * object that was returned from earlier
296: * {@link #marshal(Object,Object)} or
297: * {@link #updateJAXB(Object)} method invocation,
298: * but it maybe
299: * a different object, for example when the name of the XML
300: * element has changed.
301: *
302: * @throws JAXBException
303: * If any unexpected problem occurs updating corresponding JAXB mapped content.
304: * @throws IllegalArgumentException
305: * If node parameter is null
306: */
307: public abstract Object updateJAXB(XmlNode xmlNode)
308: throws JAXBException;
309:
310: /**
311: * Specifies whether marshal, unmarshal and update methods
312: * performs validation on their XML content.
313: *
314: * @param schema set to null to disable validation.
315: *
316: * @see Unmarshaller#setSchema(Schema)
317: */
318: public abstract void setSchema(Schema schema);
319:
320: /**
321: * Gets the last {@link Schema} object (including null) set by the
322: * {@link #setSchema(Schema)} method.
323: *
324: * @return the Schema object for validation or null if not present
325: */
326: public abstract Schema getSchema();
327:
328: /**
329: * Allow an application to register a <tt>ValidationEventHandler</tt>.
330: * <p>
331: * The <tt>ValidationEventHandler</tt> will be called by the JAXB Provider
332: * if any validation errors are encountered during calls to any of the
333: * Binder unmarshal, marshal and update methods.
334: *
335: * <p>
336: * Calling this method with a null parameter will cause the Binder
337: * to revert back to the default default event handler.
338: *
339: * @param handler the validation event handler
340: * @throws JAXBException if an error was encountered while setting the
341: * event handler
342: */
343: public abstract void setEventHandler(ValidationEventHandler handler)
344: throws JAXBException;
345:
346: /**
347: * Return the current event handler or the default event handler if one
348: * hasn't been set.
349: *
350: * @return the current ValidationEventHandler or the default event handler
351: * if it hasn't been set
352: * @throws JAXBException if an error was encountered while getting the
353: * current event handler
354: */
355: public abstract ValidationEventHandler getEventHandler()
356: throws JAXBException;
357:
358: /**
359: *
360: * Set the particular property in the underlying implementation of
361: * <tt>Binder</tt>. This method can only be used to set one of
362: * the standard JAXB defined unmarshal/marshal properties
363: * or a provider specific property for binder, unmarshal or marshal.
364: * Attempting to set an undefined property will result in
365: * a PropertyException being thrown. See
366: * <a href="Unmarshaller.html#supportedProps">Supported Unmarshal Properties</a>
367: * and
368: * <a href="Marshaller.html#supportedProps">Supported Marshal Properties</a>.
369: *
370: * @param name the name of the property to be set. This value can either
371: * be specified using one of the constant fields or a user
372: * supplied string.
373: * @param value the value of the property to be set
374: *
375: * @throws PropertyException when there is an error processing the given
376: * property or value
377: * @throws IllegalArgumentException
378: * If the name parameter is null
379: */
380: abstract public void setProperty(String name, Object value)
381: throws PropertyException;
382:
383: /**
384: * Get the particular property in the underlying implementation of
385: * <tt>Binder</tt>. This method can only
386: * be used to get one of
387: * the standard JAXB defined unmarshal/marshal properties
388: * or a provider specific property for binder, unmarshal or marshal.
389: * Attempting to get an undefined property will result in
390: * a PropertyException being thrown. See
391: * <a href="Unmarshaller.html#supportedProps">Supported Unmarshal Properties</a>
392: * and
393: * <a href="Marshaller.html#supportedProps">Supported Marshal Properties</a>.
394: *
395: * @param name the name of the property to retrieve
396: * @return the value of the requested property
397: *
398: * @throws PropertyException
399: * when there is an error retrieving the given property or value
400: * property name
401: * @throws IllegalArgumentException
402: * If the name parameter is null
403: */
404: abstract public Object getProperty(String name)
405: throws PropertyException;
406:
407: }
|