001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common Development
008: * and Distribution License("CDDL") (collectively, the "License"). You
009: * may not use this file except in compliance with the License. You can obtain
010: * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
011: * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
012: * language governing permissions and limitations under the License.
013: *
014: * When distributing the software, include this License Header Notice in each
015: * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
016: * Sun designates this particular file as subject to the "Classpath" exception
017: * as provided by Sun in the GPL Version 2 section of the License file that
018: * accompanied this code. If applicable, add the following below the License
019: * Header, with the fields enclosed by brackets [] replaced by your own
020: * identifying information: "Portions Copyrighted [year]
021: * [name of copyright owner]"
022: *
023: * Contributor(s):
024: *
025: * If you wish your version of this file to be governed by only the CDDL or
026: * only the GPL Version 2, indicate your decision by adding "[Contributor]
027: * elects to include this software in this distribution under the [CDDL or GPL
028: * Version 2] license." If you don't indicate a single choice of license, a
029: * recipient has the option to distribute your version of this file under
030: * either the CDDL, the GPL Version 2 or to extend the choice of license to
031: * its licensees as provided above. However, if you add GPL Version 2 code
032: * and therefore, elected the GPL Version 2 license, then the option applies
033: * only if the new code is made subject to such option by the copyright
034: * holder.
035: */
036:
037: package com.sun.xml.ws.streaming;
038:
039: import org.xml.sax.helpers.XMLReaderFactory;
040:
041: import java.util.Iterator;
042:
043: import javax.xml.namespace.QName;
044:
045: /**
046: * <p> XMLReader provides a high-level streaming parser interface
047: * for reading XML documents. </p>
048: *
049: * <p> The {@link #next} method is used to read events from the XML document. </p>
050: *
051: * <p> Each time it is called, {@link #next} returns the new state of the reader. </p>
052: *
053: * <p> Possible states are: BOF, the initial state, START, denoting the start
054: * tag of an element, END, denoting the end tag of an element, CHARS, denoting
055: * the character content of an element, PI, denoting a processing instruction,
056: * EOF, denoting the end of the document. </p>
057: *
058: * <p> Depending on the state the reader is in, one or more of the following
059: * query methods will be meaningful: {@link #getName}, {@link #getURI},
060: * {@link #getLocalName}, {@link #getAttributes}, {@link #getValue}. </p>
061: *
062: * <p> Elements visited by a XMLReader are tagged with unique IDs. The ID of the
063: * current element can be found by calling {@link #getElementId}. </p>
064: *
065: * <p> A XMLReader is always namespace-aware, and keeps track of the namespace
066: * declarations which are in scope at any time during streaming. The
067: * {@link #getURI(java.lang.String)} method can be used to find the URI
068: * associated to a given prefix in the current scope. </p>
069: *
070: * <p> XMLReaders can be created using a {@link XMLReaderFactory}. </p>
071: *
072: * <p> Some utility methods, {@link #nextContent} and {@link #nextElementContent}
073: * make it possible to ignore whitespace and processing instructions with
074: * minimum impact on the client code. </p>
075: *
076: * <p> Similarly, the {@link #skipElement} and {@link #skipElement(int elementId)}
077: * methods allow to skip to the end tag of an element ignoring all its content. </p>
078: *
079: * <p> Finally, the {@link #recordElement} method can be invoked when the XMLReader
080: * is positioned on the start tag of an element to record the element's contents
081: * so that they can be played back later. </p>
082: *
083: * @see XMLReaderFactory
084: *
085: * @author WS Development Team
086: */
087: public interface XMLReader {
088: /**
089: * The initial state of a XMLReader.
090: */
091: public static final int BOF = 0;
092:
093: /**
094: * The state denoting the start tag of an element.
095: */
096: public static final int START = 1;
097:
098: /**
099: * The state denoting the end tag of an element.
100: */
101: public static final int END = 2;
102:
103: /**
104: * The state denoting the character content of an element.
105: */
106: public static final int CHARS = 3;
107:
108: /**
109: * The state denoting a processing instruction.
110: */
111: public static final int PI = 4;
112:
113: /**
114: * The state denoting that the end of the document has been reached.
115: */
116: public static final int EOF = 5;
117:
118: /**
119: * Return the next state of the XMLReader.
120: *
121: * The return value is one of: START, END, CHARS, PI, EOF.
122: */
123: public int next();
124:
125: /*
126: * Return the next state of the XMLReader.
127: *
128: * <p> Whitespace character content and processing instructions are ignored. </p>
129: *
130: * <p> The return value is one of: START, END, CHARS, EOF. </p>
131: */
132: public int nextContent();
133:
134: /**
135: * Return the next state of the XMLReader.
136: *
137: * <p> Whitespace character content, processing instructions are ignored.
138: * Non-whitespace character content triggers an exception. </p>
139: *
140: * <p> The return value is one of: START, END, EOF. </p>
141: */
142: public int nextElementContent();
143:
144: /**
145: * Return the current state of the XMLReader.
146: *
147: */
148: public int getState();
149:
150: /**
151: * Return the current qualified name.
152: *
153: * <p> Meaningful only when the state is one of: START, END. </p>
154: */
155: public QName getName();
156:
157: /**
158: * Return the current URI.
159: *
160: * <p> Meaningful only when the state is one of: START, END. </p>
161: */
162: public String getURI();
163:
164: /**
165: * Return the current local name.
166: *
167: * <p> Meaningful only when the state is one of: START, END, PI. </p>
168: */
169: public String getLocalName();
170:
171: /**
172: * Return the current attribute list. In the jaxws implementation,
173: * this list also includes namespace declarations.
174: *
175: * <p> Meaningful only when the state is one of: START. </p>
176: *
177: * <p> The returned {@link Attributes} object belong to the XMLReader and is
178: * only guaranteed to be valid until the {@link #next} method is called,
179: * directly or indirectly.</p>
180: */
181: public Attributes getAttributes();
182:
183: /**
184: * Return the current value.
185: *
186: * <p> Meaningful only when the state is one of: CHARS, PI. </p>
187: */
188: public String getValue();
189:
190: /**
191: * Return the current element ID.
192: */
193: public int getElementId();
194:
195: /**
196: * Return the current line number.
197: *
198: * <p> Due to aggressive parsing, this value may be off by a few lines. </p>
199: */
200: public int getLineNumber();
201:
202: /**
203: * Return the URI for the given prefix.
204: *
205: * <p> If there is no namespace declaration in scope for the given
206: * prefix, return null. </p>
207: */
208: public String getURI(String prefix);
209:
210: /**
211: * Return an iterator on all prefixes in scope, except for the default prefix.
212: *
213: */
214: public Iterator getPrefixes();
215:
216: /**
217: * Records the current element and leaves the reader positioned on its end tag.
218: *
219: * <p> The XMLReader must be positioned on the start tag of the element.
220: * The returned reader will play back all events starting with the
221: * start tag of the element and ending with its end tag. </p>
222: */
223: public XMLReader recordElement();
224:
225: /**
226: * Skip all nodes up to the end tag of the element with the current element ID.
227: */
228: public void skipElement();
229:
230: /**
231: * Skip all nodes up to the end tag of the element with the given element ID.
232: */
233: public void skipElement(int elementId);
234:
235: /**
236: * Close the XMLReader.
237: *
238: * <p> All subsequent calls to {@link #next} will return EOF. </p>
239: */
240: public void close();
241: }
|