KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > xml > bind > annotation > DomHandler


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.annotation;
7
8 import javax.xml.bind.ValidationEventHandler;
9 import javax.xml.transform.Result JavaDoc;
10 import javax.xml.transform.Source JavaDoc;
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 JavaDoc> {
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 JavaDoc marshal( ElementT n, ValidationEventHandler errorHandler );
99 }
100
Popular Tags