001: /*
002: Copyright (c) 2004-2007, Dennis M. Sosnoski.
003: All rights reserved.
004:
005: Redistribution and use in source and binary forms, with or without modification,
006: are permitted provided that the following conditions are met:
007:
008: * Redistributions of source code must retain the above copyright notice, this
009: list of conditions and the following disclaimer.
010: * Redistributions in binary form must reproduce the above copyright notice,
011: this list of conditions and the following disclaimer in the documentation
012: and/or other materials provided with the distribution.
013: * Neither the name of JiBX nor the names of its contributors may be used
014: to endorse or promote products derived from this software without specific
015: prior written permission.
016:
017: THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
018: ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
019: WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
020: DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
021: ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
022: (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
023: LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
024: ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
025: (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
026: SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
027: */
028:
029: package org.jibx.runtime;
030:
031: import java.io.IOException;
032:
033: /**
034: * XML writer interface used for output of marshalled document. This interface
035: * allows easy substitution of different output formats, including parse event
036: * stream equivalents. This makes heavy use of state information, so each
037: * method call defined is only valid in certain states.
038: *
039: * @author Dennis M. Sosnoski
040: */
041: public interface IXMLWriter {
042: /**
043: * Get the current element nesting depth. Elements are only counted in the
044: * depth returned when they're officially open - after the start tag has
045: * been output and before the end tag has been output.
046: *
047: * @return number of nested elements at current point in output
048: */
049: public int getNestingDepth();
050:
051: /**
052: * Get the number of namespaces currently defined. This is equivalent to the
053: * index of the next extension namespace added.
054: *
055: * @return namespace count
056: */
057: public int getNamespaceCount();
058:
059: /**
060: * Set nesting indentation. This is advisory only, and implementations of
061: * this interface are free to ignore it. The intent is to indicate that the
062: * generated output should use indenting to illustrate element nesting.
063: *
064: * @param count number of character to indent per level, or disable
065: * indentation if negative (zero means new line only)
066: * @param newline sequence of characters used for a line ending
067: * (<code>null</code> means use the single character '\n')
068: * @param indent whitespace character used for indentation
069: */
070: public void setIndentSpaces(int count, String newline, char indent);
071:
072: /**
073: * Write XML declaration to document. This can only be called before any
074: * other methods in the interface are called.
075: *
076: * @param version XML version text
077: * @param encoding text for encoding attribute (unspecified if
078: * <code>null</code>)
079: * @param standalone text for standalone attribute (unspecified if
080: * <code>null</code>)
081: * @throws IOException on error writing to document
082: */
083: public void writeXMLDecl(String version, String encoding,
084: String standalone) throws IOException;
085:
086: /**
087: * Generate open start tag. This allows attributes and/or namespace
088: * declarations to be added to the start tag, but must be followed by a
089: * {@link #closeStartTag} call.
090: *
091: * @param index namespace URI index number
092: * @param name unqualified element name
093: * @throws IOException on error writing to document
094: */
095: public void startTagOpen(int index, String name) throws IOException;
096:
097: /**
098: * Generate start tag for element with namespaces. This creates the actual
099: * start tag, along with any necessary namespace declarations. Previously
100: * active namespace declarations are not duplicated. The tag is
101: * left incomplete, allowing other attributes to be added.
102: *
103: * @param index namespace URI index number
104: * @param name element name
105: * @param nums array of namespace indexes defined by this element (must
106: * be constant, reference is kept until end of element)
107: * @param prefs array of namespace prefixes mapped by this element (no
108: * <code>null</code> values, use "" for default namespace declaration)
109: * @throws IOException on error writing to document
110: */
111: public void startTagNamespaces(int index, String name, int[] nums,
112: String[] prefs) throws IOException;
113:
114: /**
115: * Add attribute to current open start tag. This is only valid after a call
116: * to {@link #startTagOpen} and before the corresponding call to {@link
117: * #closeStartTag}.
118: *
119: * @param index namespace URI index number
120: * @param name unqualified attribute name
121: * @param value text value for attribute
122: * @throws IOException on error writing to document
123: */
124: public void addAttribute(int index, String name, String value)
125: throws IOException;
126:
127: /**
128: * Close the current open start tag. This is only valid after a call to
129: * {@link #startTagOpen}.
130: *
131: * @throws IOException on error writing to document
132: */
133: public void closeStartTag() throws IOException;
134:
135: /**
136: * Close the current open start tag as an empty element. This is only valid
137: * after a call to {@link #startTagOpen}.
138: *
139: * @throws IOException on error writing to document
140: */
141: public void closeEmptyTag() throws IOException;
142:
143: /**
144: * Generate closed start tag. No attributes or namespaces can be added to a
145: * start tag written using this call.
146: *
147: * @param index namespace URI index number
148: * @param name unqualified element name
149: * @throws IOException on error writing to document
150: */
151: public void startTagClosed(int index, String name)
152: throws IOException;
153:
154: /**
155: * Generate end tag.
156: *
157: * @param index namespace URI index number
158: * @param name unqualified element name
159: * @throws IOException on error writing to document
160: */
161: public void endTag(int index, String name) throws IOException;
162:
163: /**
164: * Write ordinary character data text content to document.
165: *
166: * @param text content value text (must not be <code>null</code>)
167: * @throws IOException on error writing to document
168: */
169: public void writeTextContent(String text) throws IOException;
170:
171: /**
172: * Write CDATA text to document.
173: *
174: * @param text content value text (must not be <code>null</code>)
175: * @throws IOException on error writing to document
176: */
177: public void writeCData(String text) throws IOException;
178:
179: /**
180: * Write comment to document.
181: *
182: * @param text comment text (must not be <code>null</code>)
183: * @throws IOException on error writing to document
184: */
185: public void writeComment(String text) throws IOException;
186:
187: /**
188: * Write entity reference to document.
189: *
190: * @param name entity name (must not be <code>null</code>)
191: * @throws IOException on error writing to document
192: */
193: public void writeEntityRef(String name) throws IOException;
194:
195: /**
196: * Write DOCTYPE declaration to document.
197: *
198: * @param name root element name
199: * @param sys system ID (<code>null</code> if none, must be
200: * non-<code>null</code> for public ID to be used)
201: * @param pub public ID (<code>null</code> if none)
202: * @param subset internal subset (<code>null</code> if none)
203: * @throws IOException on error writing to document
204: */
205: public void writeDocType(String name, String sys, String pub,
206: String subset) throws IOException;
207:
208: /**
209: * Write processing instruction to document.
210: *
211: * @param target processing instruction target name (must not be
212: * <code>null</code>)
213: * @param data processing instruction data (must not be <code>null</code>)
214: * @throws IOException on error writing to document
215: */
216: public void writePI(String target, String data) throws IOException;
217:
218: /**
219: * Request output indent. The writer implementation should normally indent
220: * output as appropriate. This method can be used to request indenting of
221: * output that might otherwise not be indented. The normal effect when used
222: * with a text-oriented writer should be to output the appropriate line end
223: * sequence followed by the appropriate number of indent characters for the
224: * current nesting level.
225: *
226: * @throws IOException on error writing to document
227: */
228: public void indent() throws IOException;
229:
230: /**
231: * Flush document output. Writes any buffered data to the output medium.
232: * This does <b>not</b> flush the output medium itself, only any internal
233: * buffering within the writer.
234: *
235: * @throws IOException on error writing to document
236: */
237: public void flush() throws IOException;
238:
239: /**
240: * Close document output. Completes writing of document output, including
241: * flushing and closing the output medium.
242: *
243: * @throws IOException on error writing to document
244: */
245: public void close() throws IOException;
246:
247: /**
248: * Reset to initial state for reuse. The context is serially reusable,
249: * as long as this method is called to clear any retained state information
250: * between uses. It is automatically called when output is set.
251: */
252: public void reset();
253:
254: /**
255: * Get namespace URIs for mapping. This gets the full ordered array of
256: * namespaces known in the binding used for this marshalling, where the
257: * index number of each namespace URI is the namespace index used to lookup
258: * the prefix when marshalling a name in that namespace. The returned array
259: * must not be modified.
260: *
261: * @return array of namespaces
262: */
263: public String[] getNamespaces();
264:
265: /**
266: * Get URI for namespace.
267: *
268: * @param index namespace URI index number
269: * @return namespace URI text, or <code>null</code> if the namespace index
270: * is invalid
271: */
272: public String getNamespaceUri(int index);
273:
274: /**
275: * Get current prefix defined for namespace.
276: *
277: * @param index namespace URI index number
278: * @return current prefix text, or <code>null</code> if the namespace is not
279: * currently mapped
280: */
281: public String getNamespacePrefix(int index);
282:
283: /**
284: * Get index of namespace mapped to prefix. This can be an expensive
285: * operation with time proportional to the number of namespaces defined, so
286: * it should be used with care.
287: *
288: * @param prefix text to match (non-<code>null</code>, use "" for default
289: * prefix)
290: * @return index namespace URI index number mapped to prefix
291: */
292: public int getPrefixIndex(String prefix);
293:
294: /**
295: * Append extension namespace URIs to those in mapping.
296: *
297: * @param uris namespace URIs to extend those in mapping
298: */
299: public void pushExtensionNamespaces(String[] uris);
300:
301: /**
302: * Remove extension namespace URIs. This removes the last set of
303: * extension namespaces pushed using {@link #pushExtensionNamespaces}.
304: */
305: public void popExtensionNamespaces();
306:
307: /**
308: * Get extension namespace URIs added to those in mapping. This gets the
309: * current set of extension definitions. The returned arrays must not be
310: * modified.
311: *
312: * @return array of arrays of extension namespaces (<code>null</code> if
313: * none)
314: */
315: public String[][] getExtensionNamespaces();
316:
317: /**
318: * Open the specified namespaces for use. This method is normally only
319: * called internally, when namespace declarations are actually written to
320: * output. It is exposed as part of this interface to allow for special
321: * circumstances where namespaces are being written outside the usual
322: * processing. The namespaces will remain open for use until the current
323: * element is closed.
324: *
325: * @param nums array of namespace indexes defined by this element (must
326: * be constant, reference is kept until namespaces are closed)
327: * @param prefs array of namespace prefixes mapped by this element (no
328: * <code>null</code> values, use "" for default namespace declaration)
329: * @return array of indexes for namespaces not previously active (the ones
330: * actually needing to be declared, in the case of text output)
331: * @throws IOException on error writing to document
332: */
333: public int[] openNamespaces(int[] nums, String[] prefs)
334: throws IOException;
335: }
|