001//
002// This file was generated by the JavaTM Architecture for XML Binding(JAXB) Reference Implementation, v1.0.6-01/24/2006 06:15 PM(kohsuke)-fcs 
003// See <a href="http://java.sun.com/xml/jaxb">http://java.sun.com/xml/jaxb</a> 
004// Any modifications to this file will be lost upon recompilation of the source schema. 
005// Generated on: 2012.10.03 at 04:27:47 AM CEST 
006//
007
008package org.jdtaus.mojo.resource.model.impl.runtime;
009
010import javax.xml.bind.ValidationEvent;
011
012import org.xml.sax.SAXException;
013
014import com.sun.xml.bind.JAXBObject;
015import com.sun.xml.bind.marshaller.IdentifiableObject;
016import com.sun.xml.bind.serializer.AbortSerializationException;
017
018/**
019 * Receives XML serialization event
020 * 
021 * <p>
022 * This object coordinates the overall marshalling efforts across different
023 * content-tree objects and different target formats.
024 * 
025 * <p>
026 * The following CFG gives the proper sequence of method invocation.
027 * 
028 * <pre>
029 * MARSHALLING  :=  ELEMENT
030 * ELEMENT      :=  "startElement" NSDECL* "endNamespaceDecls"
031 *                        ATTRIBUTE* "endAttributes" BODY "endElement"
032 * 
033 * NSDECL       :=  "declareNamespace"
034 * 
035 * ATTRIBUTE    :=  "startAttribute" ATTVALUES "endAttribute"
036 * ATTVALUES    :=  "text"*
037 * 
038 * 
039 * BODY         :=  ( "text" | ELEMENT )*
040 * </pre>
041 * 
042 * <p>
043 * A marshalling of one element consists of two stages. The first stage is
044 * for marshalling attributes and collecting namespace declarations.
045 * The second stage is for marshalling characters/child elements of that element.
046 * 
047 * <p>
048 * Observe that multiple invocation of "text" is allowed.
049 * 
050 * <p>
051 * Also observe that the namespace declarations are allowed only between
052 * "startElement" and "endAttributes".
053 * 
054 * 
055 * @author  Kohsuke Kawaguchi
056 */
057public interface XMLSerializer
058{
059    /**
060     * Errors detected by the XMLSerializable should be either thrown
061     * as {@link SAXException} or reported through this method.
062     * 
063     * The callee should report an error to the client application
064     * and 
065     */
066    void reportError( ValidationEvent e ) throws AbortSerializationException;
067    
068    /**
069     * Starts marshalling of an element.
070     * Calling this method will push the internal state into the
071     * internal stack.
072     */
073    void startElement( String uri, String local ) throws SAXException;
074    
075    /**
076     * Switches to the mode to marshal attribute values.
077     * This method has to be called after the 1st pass is completed.
078     */
079    void endNamespaceDecls() throws SAXException;
080    
081    /**
082     * Switches to the mode to marshal child texts/elements.
083     * This method has to be called after the 2nd pass is completed.
084     */
085    void endAttributes() throws SAXException;
086    
087    /**
088     * Ends marshalling of an element.
089     * Pops the internal stack.
090     */
091    void endElement() throws SAXException;
092    
093    
094    /**
095     * Marshalls text.
096     * 
097     * <p>
098     * This method can be called (i) after the startAttribute method
099     * 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}