XMLSerializer


1   package com.sun.tools.xjc.runtime;
2   
3   import javax.xml.bind.ValidationEvent;
4   
5   import org.xml.sax.SAXException  ;
6   
7   import com.sun.xml.bind.JAXBObject;
8   import com.sun.xml.bind.marshaller.IdentifiableObject;
9   import com.sun.xml.bind.serializer.AbortSerializationException;
10  
11  /**
12   * Receives XML serialization event
13   * 
14   * <p>
15   * This object coordinates the overall marshalling efforts across different
16   * content-tree objects and different target formats.
17   * 
18   * <p>
19   * The following CFG gives the proper sequence of method invocation.
20   * 
21   * <pre>
22   * MARSHALLING  :=  ELEMENT
23   * ELEMENT      :=  "startElement" NSDECL* "endNamespaceDecls"
24   *                        ATTRIBUTE* "endAttributes" BODY "endElement"
25   * 
26   * NSDECL       :=  "declareNamespace"
27   * 
28   * ATTRIBUTE    :=  "startAttribute" ATTVALUES "endAttribute"
29   * ATTVALUES    :=  "text"*
30   * 
31   * 
32   * BODY         :=  ( "text" | ELEMENT )*
33   * </pre>
34   * 
35   * <p>
36   * A marshalling of one element consists of two stages. The first stage is
37   * for marshalling attributes and collecting namespace declarations.
38   * The second stage is for marshalling characters/child elements of that element.
39   * 
40   * <p>
41   * Observe that multiple invocation of "text" is allowed.
42   * 
43   * <p>
44   * Also observe that the namespace declarations are allowed only between
45   * "startElement" and "endAttributes".
46   * 
47   * 
48   * @author  Kohsuke Kawaguchi
49   */
50  public interface XMLSerializer
51  {
52      /**
53       * Errors detected by the XMLSerializable should be either thrown
54       * as {@link SAXException} or reported through this method.
55       * 
56       * The callee should report an error to the client application
57       * and 
58       */
59      void reportError( ValidationEvent e ) throws AbortSerializationException;
60      
61      /**
62       * Starts marshalling of an element.
63       * Calling this method will push the internal state into the
64       * internal stack.
65       */
66      void startElement( String   uri, String   local ) throws SAXException  ;
67      
68      /**
69       * Switches to the mode to marshal attribute values.
70       * This method has to be called after the 1st pass is completed.
71       */
72      void endNamespaceDecls() throws SAXException  ;
73      
74      /**
75       * Switches to the mode to marshal child texts/elements.
76       * This method has to be called after the 2nd pass is completed.
77       */
78      void endAttributes() throws SAXException  ;
79      
80      /**
81       * Ends marshalling of an element.
82       * Pops the internal stack.
83       */
84      void endElement() throws SAXException  ;
85      
86      
87      /**
88       * Marshalls text.
89       * 
90       * <p>
91       * This method can be called (i) after the startAttribute method
92       * and (ii) before the endAttribute method, to marshal attribute values.
93       * If the method is called more than once, those texts are considered
94       * as separated by whitespaces. For example,
95       * 
96       * <pre>
97       * c.startAttribute();
98       * c.text("abc");
99       * c.text("def");
100      * c.endAttribute("","foo");
101      * </pre>
102      * 
103      * will generate foo="abc def".
104      * 
105      * <p>
106      * Similarly, this method can be called after the endAttributes
107      * method to marshal texts inside elements. The same rule about
108      * multiple invokations apply to this case, too. For example,
109      * 
110      * <pre>
111      * c.startElement("","foo");
112      * c.endNamespaceDecls();
113      * c.endAttributes();
114      * c.text("abc");
115      * c.text("def");
116      *   c.startElement("","bar");
117      *   c.endAttributes();
118      *   c.endElement();
119      * c.text("ghi");
120      * c.endElement();
121      * </pre>
122      * 
123      * will generate <code>&lt;foo>abc def&lt;bar/>ghi&lt;/foo></code>.
124      */
125     void text( String   text, String   fieldName ) throws SAXException  ;
126     
127     
128     /**
129      * Starts marshalling of an attribute.
130      * 
131      * The marshalling of an attribute will be done by
132      * <ol>
133      *  <li>call the startAttribute method
134      *  <li>call the text method (several times if necessary)
135      *  <li>call the endAttribute method
136      * </ol>
137      * 
138      * No two attributes can be marshalled at the same time.
139      * Note that the whole attribute marshalling must be happened
140      * after the startElement method and before the endAttributes method.
141      */
142     void startAttribute( String   uri, String   local ) throws SAXException  ;
143 
144     void endAttribute() throws SAXException  ;
145     
146     /**
147      * Obtains a namespace context object, which is used to
148      * declare/obtain namespace bindings.
149      */
150     NamespaceContext2 getNamespaceContext();
151     
152     
153     /**
154      * Notifies the serializer that an ID value has just marshalled.
155      * 
156      * The serializer may or may not check the consistency of ID/IDREFs
157      * and may throw a SAXException.
158      * 
159      * @param owner
160      *      JAXB content object that posesses the ID.
161      * @param value
162      *      The value of the ID.
163      * 
164      * @return
165      *      Return the value parameter without any modification,
166      *      so that the invocation of this method can be done transparently
167      *      by a transducer.
168      */
169     String   onID( IdentifiableObject owner, String   value ) throws SAXException  ;
170     
171     /**
172      * Notifies the serializer that an IDREF value has just marshalled.
173      * 
174      * The serializer may or may not check the consistency of ID/IDREFs
175      * and may throw a SAXException.
176      * 
177      * @return
178      *      Return the value parameter without any modification.
179      *      so that the invocation of this method can be done transparently
180      *      by a transducer.
181      */
182     String   onIDREF( IdentifiableObject obj ) throws SAXException  ;
183     
184     
185     // I suppose we don't want to use SAXException. -kk
186     
187     
188     
189     // those method signatures are purposely made to JAXBContext, not
190     // XMLSerializable, to avoid N^2 proxy overhead.  
191     
192     /**
193      * This method is called when an JAXBObject object is found
194      * while the marshaller is in the "element" mode (i.e. marshalling
195      * a content model of an element)
196      * 
197      * @param fieldName
198      *      property name of the parent objeect from which 'o' comes.
199      *      Used as a part of the error message in case anything goes wrong
200      *      with 'o'. 
201      */
202     void childAsBody( JAXBObject o, String   fieldName ) throws SAXException  ;
203     
204     /**
205      * This method is called when an JAXBObject object is found
206      * while the marshaller is in the "attribute" mode (i.e. marshalling
207      * attributes of an element)
208      * 
209      * @param fieldName
210      *      property name of the parent objeect from which 'o' comes.
211      *      Used as a part of the error message in case anything goes wrong
212      *      with 'o'. 
213      */
214     void childAsAttributes( JAXBObject o, String   fieldName ) throws SAXException  ;
215     
216     /**
217      * This method is called when an JAXBObject object is found
218      * while the marshaller is in the "URI" mode.
219      * 
220      * @param fieldName
221      *      property name of the parent objeect from which 'o' comes.
222      *      Used as a part of the error message in case anything goes wrong
223      *      with 'o'. 
224      */
225     void childAsURIs( JAXBObject o, String   fieldName ) throws SAXException  ;
226 }
227
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags