gomp-20050608-branch/libjava/classpath/javax/xml/stream/XMLStreamReader.java

   1 /* XMLStreamReader.java --
   2    Copyright (C) 2005  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 getAttributeQName(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 getAttributeName(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 }
 301