KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > xmlpull > v1 > XmlSerializer


1 package org.xmlpull.v1;
2
3 import java.io.IOException JavaDoc;
4 import java.io.OutputStream JavaDoc;
5 import java.io.Writer JavaDoc;
6
7 /**
8  * Define an interface to serialziation of XML Infoset.
9  * This interface abstracts away if serialized XML is XML 1.0 comaptible text or
10  * other formats of XML 1.0 serializations (such as binary XML for example with WBXML).
11  *
12  * <p><b>PLEASE NOTE:</b> This interface will be part of XmlPull 1.2 API.
13  * It is included as basis for discussion. It may change in any way.
14  *
15  * <p>Exceptions that may be thrown are: IOException or runtime exception
16  * (more runtime exceptions can be thrown but are not declared and as such
17  * have no semantics defined for this interface):
18  * <ul>
19  * <li><em>IllegalArgumentException</em> - for almost all methods to signal that
20  * argument is illegal
21  * <li><em>IllegalStateException</em> - to signal that call has good arguments but
22  * is not expected here (violation of contract) and for features/properties
23  * when requesting setting unimplemented feature/property
24  * (UnsupportedOperationException would be better but it is not in MIDP)
25  * </ul>
26  *
27  * <p><b>NOTE:</b> writing CDSECT, ENTITY_REF, IGNORABLE_WHITESPACE,
28  * PROCESSING_INSTRUCTION, COMMENT, and DOCDECL in some implementations
29  * may not be supported (for example when serializing to WBXML).
30  * In such case IllegalStateException will be thrown and it is recommened
31  * to use an optional feature to signal that implementation is not
32  * supporting this kind of output.
33  */
34
35 public interface XmlSerializer {
36
37     /**
38      * Set feature identified by name (recommended to be URI for uniqueness).
39      * Some well known optional features are defined in
40      * <a HREF="http://www.xmlpull.org/v1/doc/features.html">
41      * http://www.xmlpull.org/v1/doc/features.html</a>.
42      *
43      * If feature is not recocgnized or can not be set
44      * then IllegalStateException MUST be thrown.
45      *
46      * @exception IllegalStateException If the feature is not supported or can not be set
47      */
48     public void setFeature(String JavaDoc name,
49                            boolean state)
50         throws IllegalArgumentException JavaDoc, IllegalStateException JavaDoc;
51
52
53     /**
54      * Return the current value of the feature with given name.
55      * <p><strong>NOTE:</strong> unknown features are <string>always</strong> returned as false.
56      *
57      * @param name The name of feature to be retrieved.
58      * @return The value of named feature.
59      * @exception IllegalArgumentException if feature string is null
60      */
61     public boolean getFeature(String JavaDoc name);
62
63
64     /**
65      * Set the value of a property.
66      * (the property name is recommened to be URI for uniqueness).
67      * Some well known optional properties are defined in
68      * <a HREF="http://www.xmlpull.org/v1/doc/properties.html">
69      * http://www.xmlpull.org/v1/doc/properties.html</a>.
70      *
71      * If property is not recocgnized or can not be set
72      * then IllegalStateException MUST be thrown.
73      *
74      * @exception IllegalStateException if the property is not supported or can not be set
75      */
76     public void setProperty(String JavaDoc name,
77                             Object JavaDoc value)
78         throws IllegalArgumentException JavaDoc, IllegalStateException JavaDoc;
79
80     /**
81      * Look up the value of a property.
82      *
83      * The property name is any fully-qualified URI. I
84      * <p><strong>NOTE:</strong> unknown properties are <string>always</strong> returned as null
85      *
86      * @param name The name of property to be retrieved.
87      * @return The value of named property.
88      */
89     public Object JavaDoc getProperty(String JavaDoc name);
90
91
92     /**
93      * Set to use binary output stream with given encoding.
94      */
95     public void setOutput (OutputStream JavaDoc os, String JavaDoc encoding)
96         throws IOException JavaDoc, IllegalArgumentException JavaDoc, IllegalStateException JavaDoc;
97
98     /**
99      * Set the output to the given writer;
100      * <p><b>WARNING</b> no information about encoding is available!
101      */
102     public void setOutput (Writer JavaDoc writer)
103         throws IOException JavaDoc, IllegalArgumentException JavaDoc, IllegalStateException JavaDoc;
104
105     /**
106      * Write &lt;?xml declaration with encoding (if encoding not null)
107      * and standalone flag (if standalone not null)
108      * This method can only be called just after setOutput.
109      */
110     public void startDocument (String JavaDoc encoding, Boolean JavaDoc standalone)
111         throws IOException JavaDoc, IllegalArgumentException JavaDoc, IllegalStateException JavaDoc;
112
113     /**
114      * Finish writing. All unclosed start tags will be closed and output
115      * will be flushed. After calling this method no more output can be
116      * serialized until next call to setOutput()
117      */
118     public void endDocument ()
119         throws IOException JavaDoc, IllegalArgumentException JavaDoc, IllegalStateException JavaDoc;
120
121     /**
122      * Binds the given prefix to the given namespace.
123      * This call is valid for the next element including child elements.
124      * The prefix and namespace MUST be always declared even if prefix
125      * is not used in element (startTag() or attribute()) - for XML 1.0
126      * it must result in declaring <code>xmlns:prefix='namespace'</code>
127      * (or <code>xmlns:prefix="namespace"</code> depending what character is used
128      * to quote attribute value).
129      *
130      * <p><b>NOTE:</b> this method MUST be called directly before startTag()
131      * and if anything but startTag() or setPrefix() is called next there will be exception.
132      * <p><b>NOTE:</b> prefixes "xml" and "xmlns" are already bound
133      * and can not be redefined see:
134      * <a HREF="http://www.w3.org/XML/xml-names-19990114-errata#NE05">Namespaces in XML Errata</a>.
135      * <p><b>NOTE:</b> to set default namespace use as prefix empty string.
136      *
137      * @argument prefix must be not null (or IllegalArgumentException is thrown)
138      * @argument namespace must be not null
139      */
140     public void setPrefix (String JavaDoc prefix, String JavaDoc namespace)
141         throws IOException JavaDoc, IllegalArgumentException JavaDoc, IllegalStateException JavaDoc;
142
143     /**
144      * Return namespace that corresponds to given prefix
145      * If there is no prefix bound to this namespace return null
146      * but if generatePrefix is false then return generated prefix.
147      *
148      * <p><b>NOTE:</b> if the prefix is empty string "" and defualt namespace is bound
149      * to this prefix then empty string ("") is returned.
150      *
151      * <p><b>NOTE:</b> prefixes "xml" and "xmlns" are already bound
152      * will have values as defined
153      * <a HREF="http://www.w3.org/TR/REC-xml-names/">Namespaces in XML specification</a>
154      */
155     public String JavaDoc getPrefix (String JavaDoc namespace, boolean generatePrefix)
156         throws IllegalArgumentException JavaDoc;
157
158     /**
159      * Returns the current depth of the element.
160      * Outside the root element, the depth is 0. The
161      * depth is incremented by 1 when startTag() is called.
162      * The depth is decremented after the call to endTag()
163      * event was observed.
164      *
165      * <pre>
166      * &lt;!-- outside --&gt; 0
167      * &lt;root> 1
168      * sometext 1
169      * &lt;foobar&gt; 2
170      * &lt;/foobar&gt; 2
171      * &lt;/root&gt; 1
172      * &lt;!-- outside --&gt; 0
173      * </pre>
174      */
175     public int getDepth();
176
177     /**
178      * Returns the namespace URI of the current element as set by startTag().
179      *
180      * <p><b>NOTE:</b> that measn in particaulr that: <ul>
181      * <li>if there was startTag("", ...) then getNamespace() returns ""
182      * <li>if there was startTag(null, ...) then getNamespace() returns null
183      * </ul>
184      *
185      * @return namespace set by startTag() that is currently in scope
186      */
187     public String JavaDoc getNamespace ();
188
189     /**
190      * Returns the name of the current element as set by startTag().
191      * It can only be null before first call to startTag()
192      * or when last endTag() is called to close first startTag().
193      *
194      * @return namespace set by startTag() that is currently in scope
195      */
196     public String JavaDoc getName();
197
198     /**
199      * Writes a start tag with the given namespace and name.
200      * If there is no prefix defined for the given namespace,
201      * a prefix will be defined automatically.
202      * The explicit prefixes for namespaces can be established by calling setPrefix()
203      * immediately before this method.
204      * If namespace is null no namespace prefix is printed but just name.
205      * If namespace is empty string then serialzier will make sure that
206      * default empty namespace is declared (in XML 1.0 xmlns='')
207      * or throw IllegalStateException if default namespace is already bound
208      * to non-empty string.
209      */
210     public XmlSerializer startTag (String JavaDoc namespace, String JavaDoc name)
211         throws IOException JavaDoc, IllegalArgumentException JavaDoc, IllegalStateException JavaDoc;
212
213     /**
214      * Write an attribute. Calls to attribute() MUST follow a call to
215      * startTag() immediately. If there is no prefix defined for the
216      * given namespace, a prefix will be defined automatically.
217      * If namespace is null or empty string
218      * no namespace prefix is printed but just name.
219      */
220     public XmlSerializer attribute (String JavaDoc namespace, String JavaDoc name, String JavaDoc value)
221         throws IOException JavaDoc, IllegalArgumentException JavaDoc, IllegalStateException JavaDoc;
222
223     /**
224      * Write end tag. Repetition of namespace and name is just for avoiding errors.
225      * <p><b>Background:</b> in kXML endTag had no arguments, and non matching tags were
226      * very difficult to find...
227      * If namespace is null no namespace prefix is printed but just name.
228      * If namespace is empty string then serialzier will make sure that
229      * default empty namespace is declared (in XML 1.0 xmlns='').
230      */
231     public XmlSerializer endTag (String JavaDoc namespace, String JavaDoc name)
232         throws IOException JavaDoc, IllegalArgumentException JavaDoc, IllegalStateException JavaDoc;
233
234     /**
235      * Writes text, where special XML chars are escaped automatically
236      */
237     public XmlSerializer text (String JavaDoc text)
238         throws IOException JavaDoc, IllegalArgumentException JavaDoc, IllegalStateException JavaDoc;
239
240     /**
241      * Writes text, where special XML chars are escaped automatically
242      */
243     public XmlSerializer text (char [] buf, int start, int len)
244         throws IOException JavaDoc, IllegalArgumentException JavaDoc, IllegalStateException JavaDoc;
245
246     public void cdsect (String JavaDoc text)
247         throws IOException JavaDoc, IllegalArgumentException JavaDoc, IllegalStateException JavaDoc;
248     public void entityRef (String JavaDoc text) throws IOException JavaDoc,
249         IllegalArgumentException JavaDoc, IllegalStateException JavaDoc;
250     public void processingInstruction (String JavaDoc text)
251         throws IOException JavaDoc, IllegalArgumentException JavaDoc, IllegalStateException JavaDoc;
252     public void comment (String JavaDoc text)
253         throws IOException JavaDoc, IllegalArgumentException JavaDoc, IllegalStateException JavaDoc;
254     public void docdecl (String JavaDoc text)
255         throws IOException JavaDoc, IllegalArgumentException JavaDoc, IllegalStateException JavaDoc;
256     public void ignorableWhitespace (String JavaDoc text)
257         throws IOException JavaDoc, IllegalArgumentException JavaDoc, IllegalStateException JavaDoc;
258
259     /**
260      * Write all pending output to the stream.
261      * If method startTag() or attribute() was called then start tag is closed (final &gt;)
262      * before flush() is called on underlying output stream.
263      *
264      * <p><b>NOTE:</b> if there is need to close start tag
265      * (so no more attribute() calls are allowed) but without flushinging output
266      * call method text() with empty string (text("")).
267      *
268      */
269     public void flush ()
270         throws IOException JavaDoc;
271
272 }
273
274
Popular Tags