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><foo>abc def<bar/>ghi</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}