001: //
002: // This file was generated by the JavaTM Architecture for XML Binding(JAXB) Reference Implementation, v1.0.5-b16-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: 2005.09.05 at 03:09:41 PM IST
006: //
007:
008: package com.sun.xml.wss.saml.internal.saml11.jaxb10.impl.runtime;
009:
010: import javax.xml.bind.ValidationEvent;
011:
012: import org.xml.sax.SAXException;
013:
014: import com.sun.xml.bind.JAXBObject;
015: import com.sun.xml.bind.marshaller.IdentifiableObject;
016: import 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: */
057: public interface XMLSerializer {
058: /**
059: * Errors detected by the XMLSerializable should be either thrown
060: * as {@link SAXException} or reported through this method.
061: *
062: * The callee should report an error to the client application
063: * and
064: */
065: void reportError(ValidationEvent e)
066: 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: * Marshalls text.
095: *
096: * <p>
097: * This method can be called (i) after the startAttribute method
098: * and (ii) before the endAttribute method, to marshal attribute values.
099: * If the method is called more than once, those texts are considered
100: * as separated by whitespaces. For example,
101: *
102: * <pre>
103: * c.startAttribute();
104: * c.text("abc");
105: * c.text("def");
106: * c.endAttribute("","foo");
107: * </pre>
108: *
109: * will generate foo="abc def".
110: *
111: * <p>
112: * Similarly, this method can be called after the endAttributes
113: * method to marshal texts inside elements. The same rule about
114: * multiple invokations apply to this case, too. For example,
115: *
116: * <pre>
117: * c.startElement("","foo");
118: * c.endNamespaceDecls();
119: * c.endAttributes();
120: * c.text("abc");
121: * c.text("def");
122: * c.startElement("","bar");
123: * c.endAttributes();
124: * c.endElement();
125: * c.text("ghi");
126: * c.endElement();
127: * </pre>
128: *
129: * will generate <code><foo>abc def<bar/>ghi</foo></code>.
130: */
131: void text(String text, String fieldName) throws SAXException;
132:
133: /**
134: * Starts marshalling of an attribute.
135: *
136: * The marshalling of an attribute will be done by
137: * <ol>
138: * <li>call the startAttribute method
139: * <li>call the text method (several times if necessary)
140: * <li>call the endAttribute method
141: * </ol>
142: *
143: * No two attributes can be marshalled at the same time.
144: * Note that the whole attribute marshalling must be happened
145: * after the startElement method and before the endAttributes method.
146: */
147: void startAttribute(String uri, String local) throws SAXException;
148:
149: void endAttribute() throws SAXException;
150:
151: /**
152: * Obtains a namespace context object, which is used to
153: * declare/obtain namespace bindings.
154: */
155: NamespaceContext2 getNamespaceContext();
156:
157: /**
158: * Notifies the serializer that an ID value has just marshalled.
159: *
160: * The serializer may or may not check the consistency of ID/IDREFs
161: * and may throw a SAXException.
162: *
163: * @param owner
164: * JAXB content object that posesses the ID.
165: * @param value
166: * The value of the ID.
167: *
168: * @return
169: * Return the value parameter without any modification,
170: * so that the invocation of this method can be done transparently
171: * by a transducer.
172: */
173: String onID(IdentifiableObject owner, String value)
174: throws SAXException;
175:
176: /**
177: * Notifies the serializer that an IDREF value has just marshalled.
178: *
179: * The serializer may or may not check the consistency of ID/IDREFs
180: * and may throw a SAXException.
181: *
182: * @return
183: * Return the value parameter without any modification.
184: * so that the invocation of this method can be done transparently
185: * by a transducer.
186: */
187: String onIDREF(IdentifiableObject obj) throws SAXException;
188:
189: // I suppose we don't want to use SAXException. -kk
190:
191: // those method signatures are purposely made to JAXBContext, not
192: // XMLSerializable, to avoid N^2 proxy overhead.
193:
194: /**
195: * This method is called when an JAXBObject object is found
196: * while the marshaller is in the "element" mode (i.e. marshalling
197: * a content model of an element)
198: *
199: * @param fieldName
200: * property name of the parent objeect from which 'o' comes.
201: * Used as a part of the error message in case anything goes wrong
202: * with 'o'.
203: */
204: void childAsBody(JAXBObject o, String fieldName)
205: throws SAXException;
206:
207: /**
208: * This method is called when an JAXBObject object is found
209: * while the marshaller is in the "attribute" mode (i.e. marshalling
210: * attributes of an element)
211: *
212: * @param fieldName
213: * property name of the parent objeect from which 'o' comes.
214: * Used as a part of the error message in case anything goes wrong
215: * with 'o'.
216: */
217: void childAsAttributes(JAXBObject o, String fieldName)
218: throws SAXException;
219:
220: /**
221: * This method is called when an JAXBObject object is found
222: * while the marshaller is in the "URI" mode.
223: *
224: * @param fieldName
225: * property name of the parent objeect from which 'o' comes.
226: * Used as a part of the error message in case anything goes wrong
227: * with 'o'.
228: */
229: void childAsURIs(JAXBObject o, String fieldName)
230: throws SAXException;
231: }
|