001 //
002 // This file was generated by the JavaTM Architecture for XML Binding(JAXB) Reference Implementation, v1.0.1-05/30/2003 05:06 AM(java_re)-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: 2004.10.11 at 12:13:34 EDT
006 //
007
008 /*
009 * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
010 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
011 */
012
013 package astronomy.data.spectra.impl.runtime;
014
015 import javax.xml.bind.ValidationEvent;
016
017 import org.xml.sax.SAXException;
018
019 import com.sun.xml.bind.JAXBObject;
020 import com.sun.xml.bind.marshaller.IdentifiableObject;
021 import com.sun.xml.bind.serializer.AbortSerializationException;
022
023 /**
024 * Receives XML serialization event
025 *
026 * <p>
027 * This object coordinates the overall marshalling efforts across different
028 * content-tree objects and different target formats.
029 *
030 * <p>
031 * The following CFG gives the proper sequence of method invocation.
032 *
033 * <pre>
034 * MARSHALLING := ELEMENT
035 * ELEMENT := "startElement" NSDECL* "endNamespaceDecls"
036 * ATTRIBUTE* "endAttributes" BODY "endElement"
037 *
038 * NSDECL := "declareNamespace"
039 *
040 * ATTRIBUTE := "startAttribute" ATTVALUES "endAttribute"
041 * ATTVALUES := "text"*
042 *
043 *
044 * BODY := ( "text" | ELEMENT )*
045 * </pre>
046 *
047 * <p>
048 * A marshalling of one element consists of two stages. The first stage is
049 * for marshalling attributes and collecting namespace declarations.
050 * The second stage is for marshalling characters/child elements of that element.
051 *
052 * <p>
053 * Observe that multiple invocation of "text" is allowed.
054 *
055 * <p>
056 * Also observe that the namespace declarations are allowed only between
057 * "startElement" and "endAttributes".
058 *
059 *
060 * @author Kohsuke Kawaguchi
061 */
062 public interface XMLSerializer
063 {
064 /**
065 * Errors detected by the XMLSerializable should be either thrown
066 * as {@link SAXException} or reported through this method.
067 *
068 * The callee should report an error to the client application
069 * and
070 */
071 void reportError( ValidationEvent e ) throws AbortSerializationException;
072
073 /**
074 * Starts marshalling of an element.
075 * Calling this method will push the internal state into the
076 * internal stack.
077 */
078 void startElement( String uri, String local ) throws SAXException;
079
080 /**
081 * Switches to the mode to marshal attribute values.
082 * This method has to be called after the 1st pass is completed.
083 */
084 void endNamespaceDecls() throws SAXException;
085
086 /**
087 * Switches to the mode to marshal child texts/elements.
088 * This method has to be called after the 2nd pass is completed.
089 */
090 void endAttributes() throws SAXException;
091
092 /**
093 * Ends marshalling of an element.
094 * Pops the internal stack.
095 */
096 void endElement() throws SAXException;
097
098
099 /**
100 * Marshalls text.
101 *
102 * <p>
103 * This method can be called (i) after the startAttribute method
104 * and (ii) before the endAttribute method, to marshal attribute values.
105 * If the method is called more than once, those texts are considered
106 * as separated by whitespaces. For example,
107 *
108 * <pre>
109 * c.startAttribute();
110 * c.text("abc");
111 * c.text("def");
112 * c.endAttribute("","foo");
113 * </pre>
114 *
115 * will generate foo="abc def".
116 *
117 * <p>
118 * Similarly, this method can be called after the endAttributes
119 * method to marshal texts inside elements. The same rule about
120 * multiple invokations apply to this case, too. For example,
121 *
122 * <pre>
123 * c.startElement("","foo");
124 * c.endNamespaceDecls();
125 * c.endAttributes();
126 * c.text("abc");
127 * c.text("def");
128 * c.startElement("","bar");
129 * c.endAttributes();
130 * c.endElement();
131 * c.text("ghi");
132 * c.endElement();
133 * </pre>
134 *
135 * will generate <code><foo>abc def<bar/>ghi</foo></code>.
136 */
137 void text( String text ) throws SAXException;
138
139
140 /**
141 * Starts marshalling of an attribute.
142 *
143 * The marshalling of an attribute will be done by
144 * <ol>
145 * <li>call the startAttribute method
146 * <li>call the text method (several times if necessary)
147 * <li>call the endAttribute method
148 * </ol>
149 *
150 * No two attributes can be marshalled at the same time.
151 * Note that the whole attribute marshalling must be happened
152 * after the startElement method and before the endAttributes method.
153 */
154 void startAttribute( String uri, String local ) throws SAXException;
155
156 void endAttribute() throws SAXException;
157
158 /**
159 * Obtains a namespace context object, which is used to
160 * declare/obtain namespace bindings.
161 */
162 NamespaceContext2 getNamespaceContext();
163
164
165 /**
166 * Notifies the serializer that an ID value has just marshalled.
167 *
168 * The serializer may or may not check the consistency of ID/IDREFs
169 * and may throw a SAXException.
170 *
171 * @param owner
172 * JAXB content object that posesses the ID.
173 * @param value
174 * The value of the ID.
175 *
176 * @return
177 * Return the value parameter without any modification,
178 * so that the invocation of this method can be done transparently
179 * by a transducer.
180 */
181 String onID( IdentifiableObject owner, String value ) throws SAXException;
182
183 /**
184 * Notifies the serializer that an IDREF value has just marshalled.
185 *
186 * The serializer may or may not check the consistency of ID/IDREFs
187 * and may throw a SAXException.
188 *
189 * @return
190 * Return the value parameter without any modification.
191 * so that the invocation of this method can be done transparently
192 * by a transducer.
193 */
194 String onIDREF( IdentifiableObject obj ) throws SAXException;
195
196
197 // TODO: think about the exception handling.
198 // I suppose we don't want to use SAXException. -kk
199
200
201
202 // those method signatures are purposely made to JAXBContext, not
203 // XMLSerializable, to avoid N^2 proxy overhead.
204
205 /**
206 * This method is called when an JAXBObject object is found
207 * while the marshaller is in the "element" mode (i.e. marshalling
208 * a content model of an element)
209 */
210 void childAsElementBody( JAXBObject o ) throws SAXException;
211
212 /**
213 * This method is called when an JAXBObject object is found
214 * while the marshaller is in the "attribute" mode (i.e. marshalling
215 * attributes of an element)
216 */
217 void childAsAttributes( JAXBObject o ) throws SAXException;
218
219 void childAsAttributeBody( JAXBObject o ) throws SAXException;
220
221 /**
222 * This method is called when an JAXBObject object is found
223 * while the marshaller is in the "URI" mode.
224 */
225 void childAsURIs( JAXBObject o ) throws SAXException;
226 }