//
   // This file was generated by the JavaTM Architecture for XML Binding(JAXB) Reference Implementation, v@@BUILD_VERSION@@ 
   // 	See <a href="http://java.sun.com/xml/jaxb">http://java.sun.com/xml/jaxb</a> 
   // 	Any modifications to this file will be lost upon recompilation of the source schema. 
   // 	Generated on: 2005.06.30 um 05:21:08 CEST 
   //
   
   package de.nierbeck.timeTrack.model.impl.runtime;
   
  import javax.xml.bind.ValidationEvent;
  
  import org.xml.sax.SAXException;
  
  import com.sun.xml.bind.JAXBObject;
  import com.sun.xml.bind.marshaller.IdentifiableObject;
  import com.sun.xml.bind.serializer.AbortSerializationException;
  
  /***
   * Receives XML serialization event
   * 
   * <p>
   * This object coordinates the overall marshalling efforts across different
   * content-tree objects and different target formats.
   * 
   * <p>
   * The following CFG gives the proper sequence of method invocation.
   * 
   * <pre>
   *     MARSHALLING  :=  ELEMENT
   *     ELEMENT      :=  &quot;startElement&quot; NSDECL* &quot;endNamespaceDecls&quot;
   *                            ATTRIBUTE* &quot;endAttributes&quot; BODY &quot;endElement&quot;
   *     
   *     NSDECL       :=  &quot;declareNamespace&quot;
   *     
   *     ATTRIBUTE    :=  &quot;startAttribute&quot; ATTVALUES &quot;endAttribute&quot;
   *     ATTVALUES    :=  &quot;text&quot;*
   *     
   *     
   *     BODY         :=  ( &quot;text&quot; | ELEMENT )*
   * </pre>
   * 
   * <p>
   * A marshalling of one element consists of two stages. The first stage is for
   * marshalling attributes and collecting namespace declarations. The second
   * stage is for marshalling characters/child elements of that element.
   * 
   * <p>
   * Observe that multiple invocation of "text" is allowed.
   * 
   * <p>
   * Also observe that the namespace declarations are allowed only between
   * "startElement" and "endAttributes".
   * 
   * 
   * @author Kohsuke Kawaguchi
   */
  public interface XMLSerializer {
  	/***
  	 * Errors detected by the XMLSerializable should be either thrown as
  	 * {@link SAXException} or reported through this method.
  	 * 
  	 * The callee should report an error to the client application and
  	 */
  	void reportError(ValidationEvent e) throws AbortSerializationException;
  
  	/***
  	 * Starts marshalling of an element. Calling this method will push the
  	 * internal state into the internal stack.
  	 */
  	void startElement(String uri, String local) throws SAXException;
  
  	/***
  	 * Switches to the mode to marshal attribute values. This method has to be
  	 * called after the 1st pass is completed.
  	 */
  	void endNamespaceDecls() throws SAXException;
  
  	/***
  	 * Switches to the mode to marshal child texts/elements. This method has to
  	 * be called after the 2nd pass is completed.
  	 */
  	void endAttributes() throws SAXException;
  
  	/***
  	 * Ends marshalling of an element. Pops the internal stack.
  	 */
  	void endElement() throws SAXException;
  
  	/***
  	 * Marshalls text.
  	 * 
  	 * <p>
  	 * This method can be called (i) after the startAttribute method and (ii)
  	 * before the endAttribute method, to marshal attribute values. If the
  	 * method is called more than once, those texts are considered as separated
  	 * by whitespaces. For example,
  	 * 
  	 * <pre>
  	 * c.startAttribute();
 	 * c.text(&quot;abc&quot;);
 	 * c.text(&quot;def&quot;);
 	 * c.endAttribute(&quot;&quot;, &quot;foo&quot;);
 	 * </pre>
 	 * 
 	 * will generate foo="abc def".
 	 * 
 	 * <p>
 	 * Similarly, this method can be called after the endAttributes method to
 	 * marshal texts inside elements. The same rule about multiple invokations
 	 * apply to this case, too. For example,
 	 * 
 	 * <pre>
 	 * c.startElement(&quot;&quot;, &quot;foo&quot;);
 	 * c.endNamespaceDecls();
 	 * c.endAttributes();
 	 * c.text(&quot;abc&quot;);
 	 * c.text(&quot;def&quot;);
 	 * c.startElement(&quot;&quot;, &quot;bar&quot;);
 	 * c.endAttributes();
 	 * c.endElement();
 	 * c.text(&quot;ghi&quot;);
 	 * c.endElement();
 	 * </pre>
 	 * 
 	 * will generate <code>&lt;foo>abc def&lt;bar/>ghi&lt;/foo></code>.
 	 */
 	void text(String text, String fieldName) throws SAXException;
 
 	/***
 	 * Starts marshalling of an attribute.
 	 * 
 	 * The marshalling of an attribute will be done by
 	 * <ol>
 	 * <li>call the startAttribute method
 	 * <li>call the text method (several times if necessary)
 	 * <li>call the endAttribute method
 	 * </ol>
 	 * 
 	 * No two attributes can be marshalled at the same time. Note that the whole
 	 * attribute marshalling must be happened after the startElement method and
 	 * before the endAttributes method.
 	 */
 	void startAttribute(String uri, String local) throws SAXException;
 
 	void endAttribute() throws SAXException;
 
 	/***
 	 * Obtains a namespace context object, which is used to declare/obtain
 	 * namespace bindings.
 	 */
 	NamespaceContext2 getNamespaceContext();
 
 	/***
 	 * Notifies the serializer that an ID value has just marshalled.
 	 * 
 	 * The serializer may or may not check the consistency of ID/IDREFs and may
 	 * throw a SAXException.
 	 * 
 	 * @param owner
 	 *            JAXB content object that posesses the ID.
 	 * @param value
 	 *            The value of the ID.
 	 * 
 	 * @return Return the value parameter without any modification, so that the
 	 *         invocation of this method can be done transparently by a
 	 *         transducer.
 	 */
 	String onID(IdentifiableObject owner, String value) throws SAXException;
 
 	/***
 	 * Notifies the serializer that an IDREF value has just marshalled.
 	 * 
 	 * The serializer may or may not check the consistency of ID/IDREFs and may
 	 * throw a SAXException.
 	 * 
 	 * @return Return the value parameter without any modification. so that the
 	 *         invocation of this method can be done transparently by a
 	 *         transducer.
 	 */
 	String onIDREF(IdentifiableObject obj) throws SAXException;
 
 	// I suppose we don't want to use SAXException. -kk
 
 	// those method signatures are purposely made to JAXBContext, not
 	// XMLSerializable, to avoid N^2 proxy overhead.
 
 	/***
 	 * This method is called when an JAXBObject object is found while the
 	 * marshaller is in the "element" mode (i.e. marshalling a content model of
 	 * an element)
 	 * 
 	 * @param fieldName
 	 *            property name of the parent objeect from which 'o' comes. Used
 	 *            as a part of the error message in case anything goes wrong
 	 *            with 'o'.
 	 */
 	void childAsBody(JAXBObject o, String fieldName) throws SAXException;
 
 	/***
 	 * This method is called when an JAXBObject object is found while the
 	 * marshaller is in the "attribute" mode (i.e. marshalling attributes of an
 	 * element)
 	 * 
 	 * @param fieldName
 	 *            property name of the parent objeect from which 'o' comes. Used
 	 *            as a part of the error message in case anything goes wrong
 	 *            with 'o'.
 	 */
 	void childAsAttributes(JAXBObject o, String fieldName) throws SAXException;
 
 	/***
 	 * This method is called when an JAXBObject object is found while the
 	 * marshaller is in the "URI" mode.
 	 * 
 	 * @param fieldName
 	 *            property name of the parent objeect from which 'o' comes. Used
 	 *            as a part of the error message in case anything goes wrong
 	 *            with 'o'.
 	 */
 	void childAsURIs(JAXBObject o, String fieldName) throws SAXException;
 }