001: /*
002: Copyright (c) 2005, 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: /**
032: * XML reader interface used for input of unmarshalled document. This interface
033: * allows easy substitution of different parsers or other input sources.
034: *
035: * @author Dennis M. Sosnoski
036: * @version 1.0
037: */
038: public interface IXMLReader {
039: //
040: // Event types reported by nextEvent() method
041: public static final int START_DOCUMENT = 0;
042: public static final int END_DOCUMENT = 1;
043: public static final int START_TAG = 2;
044: public static final int END_TAG = 3;
045: public static final int TEXT = 4;
046: public static final int CDSECT = 5;
047: public static final int ENTITY_REF = 6;
048: public static final int IGNORABLE_WHITESPACE = 7;
049: public static final int PROCESSING_INSTRUCTION = 8;
050: public static final int COMMENT = 9;
051: public static final int DOCDECL = 10;
052:
053: /**
054: * Build current parse input position description.
055: *
056: * @return text description of current parse position
057: */
058: public String buildPositionString();
059:
060: /**
061: * Advance to next parse event of input document.
062: *
063: * @return parse event type code
064: * @throws JiBXException if error reading or parsing document
065: */
066: public int nextToken() throws JiBXException;
067:
068: /**
069: * Advance to next binding component of input document. This is a
070: * higher-level operation than {@link #nextToken()}, which consolidates text
071: * content and ignores parse events for components such as comments and PIs.
072: *
073: * @return parse event type code
074: * @throws JiBXException if error reading or parsing document
075: */
076: public int next() throws JiBXException;
077:
078: /**
079: * Gets the current parse event type, without changing the current parse
080: * state.
081: *
082: * @return parse event type code
083: * @throws JiBXException if error parsing document
084: */
085: public int getEventType() throws JiBXException;
086:
087: /**
088: * Get element name from the current start or end tag.
089: *
090: * @return local name if namespace handling enabled, full name if namespace
091: * handling disabled
092: * @throws IllegalStateException if not at a start or end tag (optional)
093: */
094: public String getName();
095:
096: /**
097: * Get element namespace from the current start or end tag.
098: *
099: * @return namespace URI if namespace handling enabled and element is in a
100: * namespace, empty string otherwise
101: * @throws IllegalStateException if not at a start or end tag (optional)
102: */
103: public String getNamespace();
104:
105: /**
106: * Get element prefix from the current start or end tag.
107: *
108: * @return prefix text (<code>null</code> if no prefix)
109: * @throws IllegalStateException if not at a start or end tag
110: */
111: public String getPrefix();
112:
113: /**
114: * Get the number of attributes of the current start tag.
115: *
116: * @return number of attributes
117: * @throws IllegalStateException if not at a start tag (optional)
118: */
119: public int getAttributeCount();
120:
121: /**
122: * Get an attribute name from the current start tag.
123: *
124: * @param index attribute index
125: * @return local name if namespace handling enabled, full name if namespace
126: * handling disabled
127: * @throws IllegalStateException if not at a start tag or invalid index
128: */
129: public String getAttributeName(int index);
130:
131: /**
132: * Get an attribute namespace from the current start tag.
133: *
134: * @param index attribute index
135: * @return namespace URI if namespace handling enabled and attribute is in a
136: * namespace, empty string otherwise
137: * @throws IllegalStateException if not at a start tag or invalid index
138: */
139: public String getAttributeNamespace(int index);
140:
141: /**
142: * Get an attribute prefix from the current start tag.
143: *
144: * @param index attribute index
145: * @return prefix for attribute (<code>null</code> if no prefix present)
146: * @throws IllegalStateException if not at a start tag or invalid index
147: */
148: public String getAttributePrefix(int index);
149:
150: /**
151: * Get an attribute value from the current start tag.
152: *
153: * @param index attribute index
154: * @return value text
155: * @throws IllegalStateException if not at a start tag or invalid index
156: */
157: public String getAttributeValue(int index);
158:
159: /**
160: * Get an attribute value from the current start tag.
161: *
162: * @param ns namespace URI for expected attribute (may be <code>null</code>
163: * or the empty string for the empty namespace)
164: * @param name attribute name expected
165: * @return attribute value text, or <code>null</code> if missing
166: * @throws IllegalStateException if not at a start tag
167: */
168: public String getAttributeValue(String ns, String name);
169:
170: /**
171: * Get current text. When positioned on a TEXT event this returns the actual
172: * text; for CDSECT it returns the text inside the CDATA section; for
173: * COMMENT, DOCDECL, or PROCESSING_INSTRUCTION it returns the text inside
174: * the structure.
175: *
176: * @return text for current event
177: */
178: public String getText();
179:
180: /**
181: * Get current element nesting depth. The returned depth always includes the
182: * current start or end tag (if positioned on a start or end tag).
183: *
184: * @return element nesting depth
185: */
186: public int getNestingDepth();
187:
188: /**
189: * Get number of namespace declarations active at depth.
190: *
191: * @param depth element nesting depth
192: * @return number of namespaces active at depth
193: * @throws IllegalArgumentException if invalid depth
194: */
195: public int getNamespaceCount(int depth);
196:
197: /**
198: * Get namespace URI.
199: *
200: * @param index declaration index
201: * @return namespace URI
202: * @throws IllegalArgumentException if invalid index
203: */
204: public String getNamespaceUri(int index);
205:
206: /**
207: * Get namespace prefix.
208: *
209: * @param index declaration index
210: * @return namespace prefix, <code>null</code> if a default namespace
211: * @throws IllegalArgumentException if invalid index
212: */
213: public String getNamespacePrefix(int index);
214:
215: /**
216: * Get document name.
217: *
218: * @return document name, <code>null</code> if not known
219: */
220: public String getDocumentName();
221:
222: /**
223: * Get current source line number.
224: *
225: * @return line number from source document, <code>-1</code> if line number
226: * information not available
227: */
228: public int getLineNumber();
229:
230: /**
231: * Get current source column number.
232: *
233: * @return column number from source document, <code>-1</code> if column
234: * number information not available
235: */
236: public int getColumnNumber();
237:
238: /**
239: * Get namespace URI associated with prefix.
240: *
241: * @param prefix to be found
242: * @return associated URI (<code>null</code> if prefix not defined)
243: */
244: public String getNamespace(String prefix);
245:
246: /**
247: * Return the input encoding, if known. This is only valid after parsing of
248: * a document has been started.
249: *
250: * @return input encoding (<code>null</code> if unknown)
251: */
252: public String getInputEncoding();
253:
254: /**
255: * Return namespace processing flag.
256: *
257: * @return namespace processing flag (<code>true</code> if namespaces are
258: * processed by reader, <code>false</code> if not)
259: */
260: public boolean isNamespaceAware();
261: }
|