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  ;
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   uri, String   local ) throws SAXException  ;
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  ;
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  ;
86      
87      /**
88       * Ends marshalling of an element.
89       * Pops the internal stack.
90       */
91      void endElement() throws SAXException  ;
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   text, String   fieldName ) throws SAXException  ;
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   uri, String   local ) throws SAXException  ;
150 
151     void endAttribute() throws SAXException  ;
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   onID( IdentifiableObject owner, String   value ) throws SAXException  ;
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   onIDREF( IdentifiableObject obj ) throws SAXException  ;
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   fieldName ) throws SAXException  ;
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   fieldName ) throws SAXException  ;
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   fieldName ) throws SAXException  ;
233 }
234
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags