Source for javax.xml.stream.XMLStreamReader

   1: /* XMLStreamReader.java --
   2:    Copyright (C) 2005,2006  Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: package javax.xml.stream;
  39: 
  40: import javax.xml.namespace.NamespaceContext;
  41: import javax.xml.namespace.QName;
  42: 
  43: /**
  44:  * Interface implemented by an XML parser.
  45:  */
  46: public interface XMLStreamReader
  47:   extends XMLStreamConstants
  48: {
  49: 
  50:   /**
  51:    * Returns the implementation-specific feature or property of the given
  52:    * name.
  53:    */
  54:   Object getProperty(String name)
  55:     throws IllegalArgumentException;
  56: 
  57:   /**
  58:    * Returns the next parsing event.
  59:    */
  60:   int next()
  61:     throws XMLStreamException;
  62: 
  63:   /**
  64:    * Tests whether the current event is of the given type and namespace.
  65:    * @exception XMLStreamException if the test fails
  66:    */
  67:   void require(int type, String namespaceURI, String localName)
  68:     throws XMLStreamException;
  69: 
  70:   /**
  71:    * Returns the text content of a text-only element.
  72:    * When invoked, the current event must be START_ELEMENT.
  73:    * On completion, the current event will be END_ELEMENT.
  74:    */
  75:   String getElementText()
  76:     throws XMLStreamException;
  77: 
  78:   /**
  79:    * Skips any ignorable whitespace, comments, and processing instructions
  80:    * until a START_ELEMENT or END_ELEMENT event is encountered.
  81:    * @exception XMLStreamException if an event of any other type is
  82:    * encountered
  83:    */
  84:   int nextTag()
  85:     throws XMLStreamException;
  86: 
  87:   /**
  88:    * Indicates whether there are any remaining events to be read.
  89:    */
  90:   boolean hasNext()
  91:     throws XMLStreamException;
  92: 
  93:   /**
  94:    * Frees any resources used by this parser.
  95:    * This method will not close the underlying input source.
  96:    */
  97:   void close()
  98:     throws XMLStreamException;
  99: 
 100:   /**
 101:    * Returns the namespace URI for the given prefix.
 102:    */
 103:   String getNamespaceURI(String prefix);
 104: 
 105:   /**
 106:    * Indicates whether the current event is START_ELEMENT.
 107:    */
 108:   boolean isStartElement();
 109: 
 110:   /**
 111:    * Indicates whether the current event is END_ELEMENT.
 112:    */
 113:   boolean isEndElement();
 114: 
 115:   /**
 116:    * Indicates whether the current event is character data.
 117:    */
 118:   boolean isCharacters();
 119: 
 120:   /**
 121:    * Indicates whether the current event is ignorable whitespace.
 122:    */
 123:   boolean isWhiteSpace();
 124: 
 125:   /**
 126:    * Returns the normalized attribute value for the given attribute.
 127:    */
 128:   String getAttributeValue(String namespaceURI, String localName);
 129: 
 130:   /**
 131:    * Returns the number of attributes on this element.
 132:    * This method can only be invoked on a START_ELEMENT event.
 133:    */
 134:   int getAttributeCount();
 135: 
 136:   /**
 137:    * Returns the QName of the attribute at the given index.
 138:    */
 139:   QName getAttributeName(int index);
 140: 
 141:   /**
 142:    * Returns the namespace URI of the attribute at the given index.
 143:    */
 144:   String getAttributeNamespace(int index);
 145: 
 146:   /**
 147:    * Returns the local-name of the attribute at the given index.
 148:    */
 149:   String getAttributeLocalName(int index);
 150: 
 151:   /**
 152:    * Returns the namespace prefix of the attribute at the given index.
 153:    */
 154:   String getAttributePrefix(int index);
 155: 
 156:   /**
 157:    * Returns the type of the attribute at the specified index.
 158:    */
 159:   String getAttributeType(int index);
 160: 
 161:   /**
 162:    * Returns the normalized value of the attribute at the given index.
 163:    */
 164:   String getAttributeValue(int index);
 165: 
 166:   /**
 167:    * Indicates whether the attribute at the given index was specified in the
 168:    * underlying XML source or created by default.
 169:    */
 170:   boolean isAttributeSpecified(int index);
 171: 
 172:   /**
 173:    * Returns the number of namespaces declared on this event.
 174:    * This method is only valid on a START_ELEMENT, END_ELEMENT, or NAMESPACE
 175:    * event.
 176:    */
 177:   int getNamespaceCount();
 178: 
 179:   /**
 180:    * Returns the prefix of the namespace at the given index, or null if this
 181:    * is the default namespace declaration.
 182:    */
 183:   String getNamespacePrefix(int index);
 184: 
 185:   /**
 186:    * Returns the URI of the namespace at the given index.
 187:    */
 188:   String getNamespaceURI(int index);
 189: 
 190:   /**
 191:    * Returns the namespace context for the current position.
 192:    */
 193:   NamespaceContext getNamespaceContext();
 194: 
 195:   /**
 196:    * Returns the type of the current event.
 197:    */
 198:   int getEventType();
 199: 
 200:   /**
 201:    * Returns the string value of the current event.
 202:    */
 203:   String getText();
 204: 
 205:   /**
 206:    * Returns the string value of the current event as a character array.
 207:    */
 208:   char[] getTextCharacters();
 209: 
 210:   /**
 211:    * Copies the string value of the current event into the specified
 212:    * character array.
 213:    */
 214:   int getTextCharacters(int sourceStart, char[] target,
 215:                         int targetStart, int length)
 216:     throws XMLStreamException;
 217: 
 218:   /**
 219:    * Returns the offset of the first character in the text character array.
 220:    */
 221:   int getTextStart();
 222: 
 223:   /**
 224:    * Returns the length of the characters in the text character array.
 225:    */
 226:   int getTextLength();
 227: 
 228:   /**
 229:    * Returns the input encoding.
 230:    */
 231:   String getEncoding();
 232: 
 233:   /**
 234:    * Indicates whether the current event has text.
 235:    */
 236:   boolean hasText();
 237: 
 238:   /**
 239:    * Returns the current location of the parser cursor in the underlying
 240:    * input source.
 241:    */
 242:   Location getLocation();
 243: 
 244:   /**
 245:    * Returns the QName of the current element.
 246:    * This method is only valid on a START_ELEMENT or END_ELEMENT event.
 247:    */
 248:   QName getName();
 249: 
 250:   /**
 251:    * Returns the local-name of the current element.
 252:    */
 253:   String getLocalName();
 254: 
 255:   /**
 256:    * Indicates whether the current event has a name.
 257:    */
 258:   boolean hasName();
 259: 
 260:   /**
 261:    * Returns the namespace URI of the current element.
 262:    */
 263:   String getNamespaceURI();
 264: 
 265:   /**
 266:    * Returns the namespace prefix of the current element.
 267:    */
 268:   String getPrefix();
 269: 
 270:   /**
 271:    * Returns the XML version declared in the XML declaration.
 272:    */
 273:   String getVersion();
 274: 
 275:   /**
 276:    * Returns the standalone flag declared in the XML declaration.
 277:    */
 278:   boolean isStandalone();
 279: 
 280:   /**
 281:    * Indicates whether the standalone flag was set in the document.
 282:    */
 283:   boolean standaloneSet();
 284: 
 285:   /**
 286:    * Returns the encoding declared in the XML declaration.
 287:    */
 288:   String getCharacterEncodingScheme();
 289: 
 290:   /**
 291:    * Returns the target of the current processing instruction event.
 292:    */
 293:   String getPITarget();
 294: 
 295:   /**
 296:    * Returns the data of the current processing instruction event.
 297:    */
 298:   String getPIData();
 299: 
 300: }