01: /*
02: * Copyright 2005 Sun Microsystems, Inc. All rights reserved.
03: * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
04: */
05:
06: package javax.xml.bind.annotation;
07:
08: import javax.xml.bind.ValidationEventHandler;
09: import javax.xml.transform.Result;
10: import javax.xml.transform.Source;
11:
12: /**
13: * Converts an element (and its descendants)
14: * from/to DOM (or similar) representation.
15: *
16: * <p>
17: * Implementations of this interface will be used in conjunction with
18: * {@link XmlAnyElement} annotation to map an element of XML into a representation
19: * of infoset such as W3C DOM.
20: *
21: * <p>
22: * Implementations hide how a portion of XML is converted into/from such
23: * DOM-like representation, allowing JAXB providers to work with arbitrary
24: * such library.
25: *
26: * <P>
27: * This interface is intended to be implemented by library writers
28: * and consumed by JAXB providers. None of those methods are intended to
29: * be called from applications.
30: *
31: * @author Kohsuke Kawaguchi
32: * @since JAXB2.0
33: */
34: public interface DomHandler<ElementT, ResultT extends Result> {
35: /**
36: * When a JAXB provider needs to unmarshal a part of a document into an
37: * infoset representation, it first calls this method to create a
38: * {@link Result} object.
39: *
40: * <p>
41: * A JAXB provider will then send a portion of the XML
42: * into the given result. Such a portion always form a subtree
43: * of the whole XML document rooted at an element.
44: *
45: * @param errorHandler
46: * if any error happens between the invocation of this method
47: * and the invocation of {@link #getElement(Result)}, they
48: * must be reported to this handler.
49: *
50: * The caller must provide a non-null error handler.
51: *
52: * The {@link Result} object created from this method
53: * may hold a reference to this error handler.
54: *
55: * @return
56: * null if the operation fails. The error must have been reported
57: * to the error handler.
58: */
59: ResultT createUnmarshaller(ValidationEventHandler errorHandler);
60:
61: /**
62: * Once the portion is sent to the {@link Result}. This method is called
63: * by a JAXB provider to obtain the unmarshalled element representation.
64: *
65: * <p>
66: * Multiple invocations of this method may return different objects.
67: * This method can be invoked only when the whole sub-tree are fed
68: * to the {@link Result} object.
69: *
70: * @param rt
71: * The {@link Result} object created by {@link #createUnmarshaller(ValidationEventHandler)}.
72: *
73: * @return
74: * null if the operation fails. The error must have been reported
75: * to the error handler.
76: */
77: ElementT getElement(ResultT rt);
78:
79: /**
80: * This method is called when a JAXB provider needs to marshal an element
81: * to XML.
82: *
83: * <p>
84: * If non-null, the returned {@link Source} must contain a whole document
85: * rooted at one element, which will then be weaved into a bigger document
86: * that the JAXB provider is marshalling.
87: *
88: * @param errorHandler
89: * Receives any errors happened during the process of converting
90: * an element into a {@link Source}.
91: *
92: * The caller must provide a non-null error handler.
93: *
94: * @return
95: * null if there was an error. The error should have been reported
96: * to the handler.
97: */
98: Source marshal(ElementT n, ValidationEventHandler errorHandler);
99: }
|