KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > sun > japex > testsuite > impl > runtime > XMLSerializer


1 //
2
// This file was generated by the JavaTM Architecture for XML Binding(JAXB) Reference Implementation, v1.0.3-b18-fcs
3
// See <a HREF="http://java.sun.com/xml/jaxb">http://java.sun.com/xml/jaxb</a>
4
// Any modifications to this file will be lost upon recompilation of the source schema.
5
// Generated on: 2005.06.14 at 12:02:17 PDT
6
//
7

8 package com.sun.japex.testsuite.impl.runtime;
9
10 import javax.xml.bind.ValidationEvent;
11
12 import org.xml.sax.SAXException JavaDoc;
13
14 import com.sun.xml.bind.JAXBObject;
15 import com.sun.xml.bind.marshaller.IdentifiableObject;
16 import com.sun.xml.bind.serializer.AbortSerializationException;
17
18 /**
19  * Receives XML serialization event
20  *
21  * <p>
22  * This object coordinates the overall marshalling efforts across different
23  * content-tree objects and different target formats.
24  *
25  * <p>
26  * The following CFG gives the proper sequence of method invocation.
27  *
28  * <pre>
29  * MARSHALLING := ELEMENT
30  * ELEMENT := "startElement" NSDECL* "endNamespaceDecls"
31  * ATTRIBUTE* "endAttributes" BODY "endElement"
32  *
33  * NSDECL := "declareNamespace"
34  *
35  * ATTRIBUTE := "startAttribute" ATTVALUES "endAttribute"
36  * ATTVALUES := "text"*
37  *
38  *
39  * BODY := ( "text" | ELEMENT )*
40  * </pre>
41  *
42  * <p>
43  * A marshalling of one element consists of two stages. The first stage is
44  * for marshalling attributes and collecting namespace declarations.
45  * The second stage is for marshalling characters/child elements of that element.
46  *
47  * <p>
48  * Observe that multiple invocation of "text" is allowed.
49  *
50  * <p>
51  * Also observe that the namespace declarations are allowed only between
52  * "startElement" and "endAttributes".
53  *
54  *
55  * @author Kohsuke Kawaguchi
56  */

57 public interface XMLSerializer
58 {
59     /**
60      * Errors detected by the XMLSerializable should be either thrown
61      * as {@link SAXException} or reported through this method.
62      *
63      * The callee should report an error to the client application
64      * and
65      */

66     void reportError( ValidationEvent e ) throws AbortSerializationException;
67     
68     /**
69      * Starts marshalling of an element.
70      * Calling this method will push the internal state into the
71      * internal stack.
72      */

73     void startElement( String JavaDoc uri, String JavaDoc local ) throws SAXException JavaDoc;
74     
75     /**
76      * Switches to the mode to marshal attribute values.
77      * This method has to be called after the 1st pass is completed.
78      */

79     void endNamespaceDecls() throws SAXException JavaDoc;
80     
81     /**
82      * Switches to the mode to marshal child texts/elements.
83      * This method has to be called after the 2nd pass is completed.
84      */

85     void endAttributes() throws SAXException JavaDoc;
86     
87     /**
88      * Ends marshalling of an element.
89      * Pops the internal stack.
90      */

91     void endElement() throws SAXException JavaDoc;
92     
93     
94     /**
95      * Marshalls text.
96      *
97      * <p>
98      * This method can be called (i) after the startAttribute method
99      * and (ii) before the endAttribute method, to marshal attribute values.
100      * If the method is called more than once, those texts are considered
101      * as separated by whitespaces. For example,
102      *
103      * <pre>
104      * c.startAttribute();
105      * c.text("abc");
106      * c.text("def");
107      * c.endAttribute("","foo");
108      * </pre>
109      *
110      * will generate foo="abc def".
111      *
112      * <p>
113      * Similarly, this method can be called after the endAttributes
114      * method to marshal texts inside elements. The same rule about
115      * multiple invokations apply to this case, too. For example,
116      *
117      * <pre>
118      * c.startElement("","foo");
119      * c.endNamespaceDecls();
120      * c.endAttributes();
121      * c.text("abc");
122      * c.text("def");
123      * c.startElement("","bar");
124      * c.endAttributes();
125      * c.endElement();
126      * c.text("ghi");
127      * c.endElement();
128      * </pre>
129      *
130      * will generate <code>&lt;foo>abc def&lt;bar/>ghi&lt;/foo></code>.
131      */

132     void text( String JavaDoc text, String JavaDoc fieldName ) throws SAXException JavaDoc;
133     
134     
135     /**
136      * Starts marshalling of an attribute.
137      *
138      * The marshalling of an attribute will be done by
139      * <ol>
140      * <li>call the startAttribute method
141      * <li>call the text method (several times if necessary)
142      * <li>call the endAttribute method
143      * </ol>
144      *
145      * No two attributes can be marshalled at the same time.
146      * Note that the whole attribute marshalling must be happened
147      * after the startElement method and before the endAttributes method.
148      */

149     void startAttribute( String JavaDoc uri, String JavaDoc local ) throws SAXException JavaDoc;
150
151     void endAttribute() throws SAXException JavaDoc;
152     
153     /**
154      * Obtains a namespace context object, which is used to
155      * declare/obtain namespace bindings.
156      */

157     NamespaceContext2 getNamespaceContext();
158     
159     
160     /**
161      * Notifies the serializer that an ID value has just marshalled.
162      *
163      * The serializer may or may not check the consistency of ID/IDREFs
164      * and may throw a SAXException.
165      *
166      * @param owner
167      * JAXB content object that posesses the ID.
168      * @param value
169      * The value of the ID.
170      *
171      * @return
172      * Return the value parameter without any modification,
173      * so that the invocation of this method can be done transparently
174      * by a transducer.
175      */

176     String JavaDoc onID( IdentifiableObject owner, String JavaDoc value ) throws SAXException JavaDoc;
177     
178     /**
179      * Notifies the serializer that an IDREF value has just marshalled.
180      *
181      * The serializer may or may not check the consistency of ID/IDREFs
182      * and may throw a SAXException.
183      *
184      * @return
185      * Return the value parameter without any modification.
186      * so that the invocation of this method can be done transparently
187      * by a transducer.
188      */

189     String JavaDoc onIDREF( IdentifiableObject obj ) throws SAXException JavaDoc;
190     
191     
192     // I suppose we don't want to use SAXException. -kk
193

194     
195     
196     // those method signatures are purposely made to JAXBContext, not
197
// XMLSerializable, to avoid N^2 proxy overhead.
198

199     /**
200      * This method is called when an JAXBObject object is found
201      * while the marshaller is in the "element" mode (i.e. marshalling
202      * a content model of an element)
203      *
204      * @param fieldName
205      * property name of the parent objeect from which 'o' comes.
206      * Used as a part of the error message in case anything goes wrong
207      * with 'o'.
208      */

209     void childAsBody( JAXBObject o, String JavaDoc fieldName ) throws SAXException JavaDoc;
210     
211     /**
212      * This method is called when an JAXBObject object is found
213      * while the marshaller is in the "attribute" mode (i.e. marshalling
214      * attributes of an element)
215      *
216      * @param fieldName
217      * property name of the parent objeect from which 'o' comes.
218      * Used as a part of the error message in case anything goes wrong
219      * with 'o'.
220      */

221     void childAsAttributes( JAXBObject o, String JavaDoc fieldName ) throws SAXException JavaDoc;
222     
223     /**
224      * This method is called when an JAXBObject object is found
225      * while the marshaller is in the "URI" mode.
226      *
227      * @param fieldName
228      * property name of the parent objeect from which 'o' comes.
229      * Used as a part of the error message in case anything goes wrong
230      * with 'o'.
231      */

232     void childAsURIs( JAXBObject o, String JavaDoc fieldName ) throws SAXException JavaDoc;
233 }
234
Popular Tags