IXMLWriter


1   /*
2   Copyright (c) 2004-2005, Dennis M. Sosnoski.
3   All rights reserved.
4   
5   Redistribution and use in source and binary forms, with or without modification,
6   are permitted provided that the following conditions are met:
7   
8    * Redistributions of source code must retain the above copyright notice, this
9      list of conditions and the following disclaimer.
10   * Redistributions in binary form must reproduce the above copyright notice,
11     this list of conditions and the following disclaimer in the documentation
12     and/or other materials provided with the distribution.
13   * Neither the name of JiBX nor the names of its contributors may be used
14     to endorse or promote products derived from this software without specific
15     prior written permission.
16  
17  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
18  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
19  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
20  DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
21  ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
22  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
23  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
24  ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
26  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27  */
28  
29  package org.jibx.runtime;
30  
31  import java.io.IOException  ;
32  
33  /**
34   * XML writer interface used for output of marshalled document. This interface
35   * allows easy substitution of different output formats, including parse event
36   * stream equivalents. This makes heavy use of state information, so each
37   * method call defined is only valid in certain states.
38   *
39   * @author Dennis M. Sosnoski
40   * @version 1.0
41   */
42  
43  public interface IXMLWriter
44  {
45      /**
46       * Set nesting indentation. This is advisory only, and implementations of
47       * this interface are free to ignore it. The intent is to indicate that the
48       * generated output should use indenting to illustrate element nesting.
49       *
50       * @param count number of character to indent per level, or disable
51       * indentation if negative (zero means new line only)
52       * @param newline sequence of characters used for a line ending
53       * (<code>null</code> means use the single character '\n')
54       * @param indent whitespace character used for indentation
55       */
56      
57      public void setIndentSpaces(int count, String   newline, char indent);
58          
59      /**
60       * Write XML declaration to document. This can only be called before any
61       * other methods in the interface are called.
62       *
63       * @param version XML version text
64       * @param encoding text for encoding attribute (unspecified if
65       * <code>null</code>)
66       * @param standalone text for standalone attribute (unspecified if
67       * <code>null</code>)
68       * @throws IOException on error writing to document
69       */
70  
71      public void writeXMLDecl(String   version, String   encoding, String   standalone)
72          throws IOException  ;
73      
74      /**
75       * Generate open start tag. This allows attributes and/or namespace
76       * declarations to be added to the start tag, but must be followed by a
77       * {@link #closeStartTag} call.
78       *
79       * @param index namespace URI index number
80       * @param name unqualified element name
81       * @throws IOException on error writing to document
82       */
83  
84      public void startTagOpen(int index, String   name) throws IOException  ;
85      
86      /**
87       * Generate start tag for element with namespaces. This creates the actual
88       * start tag, along with any necessary namespace declarations. Previously
89       * active namespace declarations are not duplicated. The tag is
90       * left incomplete, allowing other attributes to be added.
91       *
92       * @param index namespace URI index number
93       * @param name element name
94       * @param nums array of namespace indexes defined by this element (must
95       * be constant, reference is kept until end of element)
96       * @param prefs array of namespace prefixes mapped by this element (no
97       * <code>null</code> values, use "" for default namespace declaration)
98       * @return this context (to allow chained calls)
99       * @throws JiBXException on any error (possibly wrapping other exception)
100      */
101 
102     public void startTagNamespaces(int index, String   name,
103         int[] nums, String  [] prefs) throws IOException  ;
104      
105     /**
106      * Add attribute to current open start tag. This is only valid after a call
107      * to {@link #startTagOpen} and before the corresponding call to {@link
108      * #closeStartTag}.
109      *
110      * @param index namespace URI index number
111      * @param name unqualified attribute name
112      * @param value text value for attribute
113      * @throws IOException on error writing to document
114      */
115 
116     public void addAttribute(int index, String   name, String   value)
117         throws IOException  ;
118     
119     /**
120      * Close the current open start tag. This is only valid after a call to
121      * {@link #startTagOpen}.
122      *
123      * @throws IOException on error writing to document
124      */
125 
126     public void closeStartTag() throws IOException  ;
127     
128     /**
129      * Close the current open start tag as an empty element. This is only valid
130      * after a call to {@link #startTagOpen}.
131      *
132      * @throws IOException on error writing to document
133      */
134 
135     public void closeEmptyTag() throws IOException  ;
136     
137     /**
138      * Generate closed start tag. No attributes or namespaces can be added to a
139      * start tag written using this call.
140      *
141      * @param index namespace URI index number
142      * @param name unqualified element name
143      * @throws IOException on error writing to document
144      */
145 
146     public void startTagClosed(int index, String   name) throws IOException  ;
147     
148     /**
149      * Generate end tag.
150      *
151      * @param index namespace URI index number
152      * @param name unqualified element name
153      * @throws IOException on error writing to document
154      */
155 
156     public void endTag(int index, String   name) throws IOException  ;
157     
158     /**
159      * Write ordinary character data text content to document.
160      *
161      * @param text content value text
162      * @throws IOException on error writing to document
163      */
164 
165     public void writeTextContent(String   text) throws IOException  ;
166     
167     /**
168      * Write CDATA text to document.
169      *
170      * @param text content value text
171      * @throws IOException on error writing to document
172      */
173 
174     public void writeCData(String   text) throws IOException  ;
175     
176     /**
177      * Write comment to document.
178      *
179      * @param text comment text
180      * @throws IOException on error writing to document
181      */
182 
183     public void writeComment(String   text) throws IOException  ;
184     
185     /**
186      * Write entity reference to document.
187      *
188      * @param name entity name
189      * @throws IOException on error writing to document
190      */
191 
192     public void writeEntityRef(String   name) throws IOException  ;
193     
194     /**
195      * Write DOCTYPE declaration to document.
196      *
197      * @param name root element name
198      * @param sys system ID (<code>null</code> if none, must be
199      * non-<code>null</code> for public ID to be used)
200      * @param pub public ID (<code>null</code> if none)
201      * @param subset internal subset (<code>null</code> if none)
202      * @throws IOException on error writing to document
203      */
204 
205     public void writeDocType(String   name, String   sys, String   pub, String   subset)
206         throws IOException  ;
207     
208     /**
209      * Write processing instruction to document.
210      *
211      * @param target processing instruction target name
212      * @param data processing instruction data
213      * @throws IOException on error writing to document
214      */
215 
216     public void writePI(String   target, String   data) throws IOException  ;
217     
218     /**
219      * Ends the current innermost set of nested namespace definitions. Reverts
220      * the namespaces involved to their previously-declared prefixes, and sets
221      * up for ending the new innermost set.
222      */
223     
224     public void closeNamespaces();
225     
226     /**
227      * Request output indent. The writer implementation should normally indent
228      * output as appropriate. This method can be used to request indenting of
229      * output that might otherwise not be indented. The normal effect when used
230      * with a text-oriented writer should be to output the appropriate line end
231      * sequence followed by the appropriate number of indent characters for the
232      * current nesting level.
233      *
234      * @throws IOException on error writing to document
235      */
236 
237     public void indent() throws IOException  ;
238     
239     /**
240      * Close document output. Completes writing of document output, including
241      * closing the output medium.
242      *
243      * @throws IOException on error writing to document
244      */
245 
246     public void close() throws IOException  ;
247     
248     /**
249      * Reset to initial state for reuse. The context is serially reusable,
250      * as long as this method is called to clear any retained state information
251      * between uses. It is automatically called when output is set.
252      */
253     
254     public void reset();
255     
256     /**
257      * Get namespace URIs for mapping. This gets the full ordered array of
258      * namespaces known in the binding used for this marshalling, where the
259      * index number of each namespace URI is the namespace index used to lookup
260      * the prefix when marshalling a name in that namespace. The returned array
261      * must not be modified.
262      *
263      * @return array of namespaces
264      */
265     
266     public String  [] getNamespaces();
267     
268     /**
269      * Get URI for namespace.
270      *
271      * @param index namespace URI index number
272      * @return namespace URI text, or <code>null</code> if the namespace index
273      * is invalid
274      */
275     
276     public String   getNamespaceUri(int index);
277     
278     /**
279      * Get current prefix defined for namespace.
280      *
281      * @param index namespace URI index number
282      * @return current prefix text, or <code>null</code> if the namespace is not
283      * currently mapped
284      */
285     
286     public String   getNamespacePrefix(int index);
287     
288     /**
289      * Get index of namespace mapped to prefix. This can be an expensive
290      * operation with time proportional to the number of namespaces defined, so
291      * it should be used with care.
292      * 
293      * @param prefix text to match
294      * @return index namespace URI index number mapped to prefix
295      */
296     
297     public int getPrefixIndex(String   prefix);
298     
299     /**
300      * Append extension namespace URIs to those in mapping.
301      *
302      * @param uris namespace URIs to extend those in mapping
303      */
304     
305     public void pushExtensionNamespaces(String  [] uris);
306     
307     /**
308      * Remove extension namespace URIs. This removes the last set of
309      * extension namespaces pushed using {@link #pushExtensionNamespaces}.
310      */
311     
312     public void popExtensionNamespaces();
313     
314     /**
315      * Get extension namespace URIs added to those in mapping. This gets the
316      * current set of extension definitions. The returned arrays must not be
317      * modified.
318      *
319      * @return array of arrays of extension namespaces (<code>null</code> if
320      * none)
321      */
322     
323     public String  [][] getExtensionNamespaces();
324 }
325
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags