001: /*
002: * Portions Copyright 2006 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package com.sun.xml.internal.ws.streaming;
027:
028: import java.util.Iterator;
029:
030: import javax.xml.namespace.QName;
031:
032: /**
033: * <p> XMLReader provides a high-level streaming parser interface
034: * for reading XML documents. </p>
035: *
036: * <p> The {@link #next} method is used to read events from the XML document. </p>
037: *
038: * <p> Each time it is called, {@link #next} returns the new state of the reader. </p>
039: *
040: * <p> Possible states are: BOF, the initial state, START, denoting the start
041: * tag of an element, END, denoting the end tag of an element, CHARS, denoting
042: * the character content of an element, PI, denoting a processing instruction,
043: * EOF, denoting the end of the document. </p>
044: *
045: * <p> Depending on the state the reader is in, one or more of the following
046: * query methods will be meaningful: {@link #getName}, {@link #getURI},
047: * {@link #getLocalName}, {@link #getAttributes}, {@link #getValue}. </p>
048: *
049: * <p> Elements visited by a XMLReader are tagged with unique IDs. The ID of the
050: * current element can be found by calling {@link #getElementId}. </p>
051: *
052: * <p> A XMLReader is always namespace-aware, and keeps track of the namespace
053: * declarations which are in scope at any time during streaming. The
054: * {@link #getURI(java.lang.String)} method can be used to find the URI
055: * associated to a given prefix in the current scope. </p>
056: *
057: * <p> XMLReaders can be created using a {@link XMLReaderFactory}. </p>
058: *
059: * <p> Some utility methods, {@link #nextContent} and {@link #nextElementContent}
060: * make it possible to ignore whitespace and processing instructions with
061: * minimum impact on the client code. </p>
062: *
063: * <p> Similarly, the {@link #skipElement} and {@link #skipElement(int elementId)}
064: * methods allow to skip to the end tag of an element ignoring all its content. </p>
065: *
066: * <p> Finally, the {@link #recordElement} method can be invoked when the XMLReader
067: * is positioned on the start tag of an element to record the element's contents
068: * so that they can be played back later. </p>
069: *
070: * @see XMLReaderFactory
071: *
072: * @author WS Development Team
073: */
074: public interface XMLReader {
075: /**
076: * The initial state of a XMLReader.
077: */
078: public static final int BOF = 0;
079:
080: /**
081: * The state denoting the start tag of an element.
082: */
083: public static final int START = 1;
084:
085: /**
086: * The state denoting the end tag of an element.
087: */
088: public static final int END = 2;
089:
090: /**
091: * The state denoting the character content of an element.
092: */
093: public static final int CHARS = 3;
094:
095: /**
096: * The state denoting a processing instruction.
097: */
098: public static final int PI = 4;
099:
100: /**
101: * The state denoting that the end of the document has been reached.
102: */
103: public static final int EOF = 5;
104:
105: /**
106: * Return the next state of the XMLReader.
107: *
108: * The return value is one of: START, END, CHARS, PI, EOF.
109: */
110: public int next();
111:
112: /*
113: * Return the next state of the XMLReader.
114: *
115: * <p> Whitespace character content and processing instructions are ignored. </p>
116: *
117: * <p> The return value is one of: START, END, CHARS, EOF. </p>
118: */
119: public int nextContent();
120:
121: /**
122: * Return the next state of the XMLReader.
123: *
124: * <p> Whitespace character content, processing instructions are ignored.
125: * Non-whitespace character content triggers an exception. </p>
126: *
127: * <p> The return value is one of: START, END, EOF. </p>
128: */
129: public int nextElementContent();
130:
131: /**
132: * Return the current state of the XMLReader.
133: *
134: */
135: public int getState();
136:
137: /**
138: * Return the current qualified name.
139: *
140: * <p> Meaningful only when the state is one of: START, END. </p>
141: */
142: public QName getName();
143:
144: /**
145: * Return the current URI.
146: *
147: * <p> Meaningful only when the state is one of: START, END. </p>
148: */
149: public String getURI();
150:
151: /**
152: * Return the current local name.
153: *
154: * <p> Meaningful only when the state is one of: START, END, PI. </p>
155: */
156: public String getLocalName();
157:
158: /**
159: * Return the current attribute list. In the jaxws implementation,
160: * this list also includes namespace declarations.
161: *
162: * <p> Meaningful only when the state is one of: START. </p>
163: *
164: * <p> The returned {@link Attributes} object belong to the XMLReader and is
165: * only guaranteed to be valid until the {@link #next} method is called,
166: * directly or indirectly.</p>
167: */
168: public Attributes getAttributes();
169:
170: /**
171: * Return the current value.
172: *
173: * <p> Meaningful only when the state is one of: CHARS, PI. </p>
174: */
175: public String getValue();
176:
177: /**
178: * Return the current element ID.
179: */
180: public int getElementId();
181:
182: /**
183: * Return the current line number.
184: *
185: * <p> Due to aggressive parsing, this value may be off by a few lines. </p>
186: */
187: public int getLineNumber();
188:
189: /**
190: * Return the URI for the given prefix.
191: *
192: * <p> If there is no namespace declaration in scope for the given
193: * prefix, return null. </p>
194: */
195: public String getURI(String prefix);
196:
197: /**
198: * Return an iterator on all prefixes in scope, except for the default prefix.
199: *
200: */
201: public Iterator getPrefixes();
202:
203: /**
204: * Records the current element and leaves the reader positioned on its end tag.
205: *
206: * <p> The XMLReader must be positioned on the start tag of the element.
207: * The returned reader will play back all events starting with the
208: * start tag of the element and ending with its end tag. </p>
209: */
210: public XMLReader recordElement();
211:
212: /**
213: * Skip all nodes up to the end tag of the element with the current element ID.
214: */
215: public void skipElement();
216:
217: /**
218: * Skip all nodes up to the end tag of the element with the given element ID.
219: */
220: public void skipElement(int elementId);
221:
222: /**
223: * Close the XMLReader.
224: *
225: * <p> All subsequent calls to {@link #next} will return EOF. </p>
226: */
227: public void close();
228: }
|