XMLStreamReader


1   /*
2    * Javolution - Java(TM) Solution for Real-Time and Embedded Systems
3    * Copyright (C) 2006 - Javolution (http://javolution.org/)
4    * All rights reserved.
5    * 
6    * Permission to use, copy, modify, and distribute this software is
7    * freely granted, provided that this notice is preserved.
8    */
9   package javolution.xml.stream;
10  
11  import javolution.text.CharArray;
12  import j2me.lang.CharSequence;
13  
14  /**
15   * <p> This interface is similar to 
16   *     <code>javax.xml.stream.XMLStreamReader</code>; but it does not forces
17   *     dynamic allocation when parsing  (its methods returns 
18   *     {@link CharArray CharArray} instances instead  of {@link String}).</p>
19   *     
20   * <p> Except for the speed (faster) and its real-time characteristics  
21   *     the usage/behavior is about the same as its StAX counterpart.</p>
22   *     
23   * <p> The {@link CharArray CharArray} instances returned by this reader 
24   *     supports fast primitive conversions as illustrated below:[code]
25   *     
26   *     // Creates a new reader (potentially recycled).
27   *     XMLInputFactory factory = XMLInputFactory.newInstance();
28   *     XMLStreamReader reader = factory.createXMLStreamReader(inputStream);
29   *     
30   *     while (reader.getEventType() != XMLStreamConstants.END_DOCUMENT) {
31   *         switch (reader.next()) {
32   *             case XMLStreamConstants.START_ELEMENT:
33   *             if (reader.getLocalName().equals("Time")) {
34   *                  // Reads primitive types (int) attributes directly (no memory allocation).
35   *                  time.hour = reader.getAttributeValue("hour").toInt();
36   *                  time.minute = reader.getAttributeValue("minute").toInt();
37   *                  time.second = reader.getAttributeValue("second").toInt();
38   *             }
39   *             ...
40   *             break;
41   *         }         
42   *     }
43   *     
44   *     reader.close(); // Recycles the reader.
45   *     inputStream.close(); // Underlying stream has to be closed explicitly.
46   *     [/code] 
47   *     
48   * @author  <a HREF="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
49   * @version 4.0, September 4, 2006
50   */
51  public interface XMLStreamReader extends XMLStreamConstants {
52  
53      /**
54       * Gets the value of a feature/property from the underlying implementation
55       * 
56       * @param name the name of the property.
57       * @return the value of the property.
58       */
59      public Object   getProperty(String   name) throws IllegalArgumentException  ;
60  
61      /**
62       * Gets next parsing event - contiguous character data is returned into a
63       * single chunk.
64       * 
65       * By default entity references must be expanded and reported transparently
66       * to the application. An exception will be thrown if an entity reference
67       * cannot be expanded. If element content is empty (i.e. content is "") then
68       * no CHARACTERS event will be reported.
69       * 
70       * <p>
71       * Given the following XML:<br>
72       * &lt;foo>&lt;!--description-->content
73       * text&lt;![CDATA[&lt;greeting>Hello&lt;/greeting>]]>other content&lt;/foo><br>
74       * The behavior of calling next() when being on foo will be:<br>
75       * 1- the comment (COMMENT)<br>
76       * 2- then the characters section (CHARACTERS)<br>
77       * 3- then the CDATA section (another CHARACTERS)<br>
78       * 4- then the next characters section (another CHARACTERS)<br>
79       * 5- then the END_ELEMENT<br>
80       * 
81       * <p>
82       * <b>NOTE:</b> empty element (such as &lt;tag/>) will be reported with two
83       * separate events: START_ELEMENT, END_ELEMENT - This preserves parsing
84       * equivalency of empty element to &lt;tag>&lt;/tag>.
85       * 
86       * This method will throw an IllegalStateException if it is called after
87       * hasNext() returns false.
88       * 
89       * @return the integer code corresponding to the current parse event
90       * @throws NoSuchElementException if this is called when hasNext() 
91       *         returns false
92       * @throws XMLStreamException if there is an error processing the 
93       *         underlying XML source
94       */
95      public int next() throws XMLStreamException;
96  
97      /**
98       * Tests if the current event is of the given type and if the namespace and
99       * name match the current namespace and name of the current event. If the
100      * namespaceURI is null it is not checked for equality, if the localName is
101      * null it is not checked for equality.
102      * 
103      * @param type the event type.
104      * @param namespaceURI the uri of the event, may be null.
105      * @param localName the localName of the event, may be null.
106      * @throws XMLStreamException if the required values are not matched.
107      */
108     public void require(int type, CharSequence   namespaceURI,
109             CharSequence   localName) throws XMLStreamException;
110 
111     /**
112      * Reads the content of a text-only element, an exception is thrown if this
113      * is not a text-only element. Regardless of the value of
114      * javax.xml.stream.isCoalescing this method always returns coalesced
115      * content. <br />
116      * Precondition: the current event is START_ELEMENT. <br />
117      * Postcondition: the current event is the corresponding END_ELEMENT.
118      * 
119      * <br />
120      * The method does the following (implementations are free to optimized but
121      * must do equivalent processing):
122      * 
123      * <pre>
124      * if (getEventType() != XMLStreamConstants.START_ELEMENT) {
125      *  throw new XMLStreamException(
126      *          &quot;parser must be on START_ELEMENT to read next text&quot;, getLocation());
127      * }
128      * int eventType = next();
129      * StringBuffer content = new StringBuffer();
130      * while (eventType != XMLStreamConstants.END_ELEMENT) {
131      *  if (eventType == XMLStreamConstants.CHARACTERS
132      *          || eventType == XMLStreamConstants.CDATA
133      *          || eventType == XMLStreamConstants.SPACE
134      *          || eventType == XMLStreamConstants.ENTITY_REFERENCE) {
135      *      buf.append(getText());
136      *  } else if (eventType == XMLStreamConstants.PROCESSING_INSTRUCTION
137      *          || eventType == XMLStreamConstants.COMMENT) {
138      *      // skipping
139      *  } else if (eventType == XMLStreamConstants.END_DOCUMENT) {
140      *      throw new XMLStreamException(
141      *              &quot;unexpected end of document when reading element text content&quot;,
142      *              this);
143      *  } else if (eventType == XMLStreamConstants.START_ELEMENT) {
144      *      throw new XMLStreamException(
145      *              &quot;element text content may not contain START_ELEMENT&quot;,
146      *              getLocation());
147      *  } else {
148      *      throw new XMLStreamException(&quot;Unexpected event type &quot; + eventType,
149      *              getLocation());
150      *  }
151      *  eventType = next();
152      * }
153      * return buf.toString();
154      * </pre>
155      * 
156      * @throws XMLStreamException if the current event is not a START_ELEMENT 
157      *         or if a non text element is encountered.
158      */
159     public CharArray getElementText() throws XMLStreamException;
160 
161     /**
162      * Skips any white space (isWhiteSpace() returns true), COMMENT, or
163      * PROCESSING_INSTRUCTION, until a START_ELEMENT or END_ELEMENT is reached.
164      * If other than white space characters, COMMENT, PROCESSING_INSTRUCTION,
165      * START_ELEMENT, END_ELEMENT are encountered, an exception is thrown. This
166      * method should be used when processing element-only content seperated by
167      * white space.
168      * 
169      * <br />
170      * Precondition: none <br />
171      * Postcondition: the current event is START_ELEMENT or END_ELEMENT and
172      * cursor may have moved over any whitespace event.
173      * 
174      * <br />
175      * Essentially it does the following (implementations are free to optimized
176      * but must do equivalent processing):
177      * 
178      * <pre>
179      *   int eventType = next();
180      *   while((eventType == XMLStreamConstants.CHARACTERS &amp;&amp; isWhiteSpace()) // skip whitespace
181      *   || (eventType == XMLStreamConstants.CDATA &amp;&amp; isWhiteSpace()) 
182      *   // skip whitespace
183      *   || eventType == XMLStreamConstants.SPACE
184      *   || eventType == XMLStreamConstants.PROCESSING_INSTRUCTION
185      *   || eventType == XMLStreamConstants.COMMENT
186      *   ) {
187      *   eventType = next();
188      *   }
189      *   if (eventType != XMLStreamConstants.START_ELEMENT &amp;&amp; eventType != XMLStreamConstants.END_ELEMENT) {
190      *   throw new String XMLStreamException(&quot;expected start or end tag&quot;, getLocation());
191      *   }
192      *   return eventType;
193      * </pre>
194      * 
195      * @return the event type of the element read (START_ELEMENT or END_ELEMENT)
196      * @throws XMLStreamException if the current event is not white space,
197      *             PROCESSING_INSTRUCTION, START_ELEMENT or END_ELEMENT
198      * @throws NoSuchElementException if this is called when hasNext() 
199      *         returns false
200      */
201     public int nextTag() throws XMLStreamException;
202 
203     /**
204      * Returns true if there are more parsing events and false if there are no
205      * more events. This method will return false if the current state of the
206      * XMLStreamReader is END_DOCUMENT.
207      * 
208      * @return true if there are more events, false otherwise.
209      * @throws XMLStreamException if there is a fatal error detecting the next
210      *         state.
211      */
212     public boolean hasNext() throws XMLStreamException;
213 
214     /**
215      * Frees any resources associated with this Reader. This method does not
216      * close the underlying input source.
217      * 
218      * @throws XMLStreamException if there are errors freeing associated
219      *         resources
220      */
221     public void close() throws XMLStreamException;
222 
223     /**
224      * Returns the uri for the given prefix. The uri returned depends on the
225      * current state of the processor.
226      * 
227      * <p>
228      * <strong>NOTE:</strong>The 'xml' prefix is bound as defined in <a
229      * HREF="http://www.w3.org/TR/REC-xml-names/#ns-using">Namespaces in XML</a>
230      * specification to "http://www.w3.org/XML/1998/namespace".
231      * 
232      * <p>
233      * <strong>NOTE:</strong> The 'xmlns' prefix must be resolved to following
234      * namespace <a
235      * HREF="http://www.w3.org/2000/xmlns/">http://www.w3.org/2000/xmlns/</a>
236      * 
237      * @param prefix the prefix to lookup.
238      * @return the uri bound to the given prefix or <code>null</code> if it is
239      *         not bound
240      */
241     public CharArray getNamespaceURI(CharSequence   prefix);
242 
243     /**
244      * Indicates if the cursor points to a start tag.
245      * 
246      * @return <code>true</code> if the cursor points to a start tag;
247      *         <code>false</code> otherwise.
248      */
249     public boolean isStartElement();
250 
251     /**
252      * Indicates if the cursor points to an end tag.
253      * 
254      * @return <code>true</code> if the cursor points to a end tag;
255      *         <code>false</code> otherwise.
256      */
257     public boolean isEndElement();
258 
259     /**
260      * Indicates if the cursor points to character data.
261      * 
262      * @return <code>true</code> if the cursor points to character data;
263      *         <code>false</code> otherwise.
264      */
265     public boolean isCharacters();
266 
267     /**
268      * Indicates if the cursor points to character data that consists
269      * of all whitespace.
270      * 
271      * @return <code>true</code> if the cursor points to whitespaces;
272      *         <code>false</code> otherwise.
273      */
274     public boolean isWhiteSpace();
275 
276     /**
277      * Returns the normalized attribute value of the attribute with the
278      * namespace and localName. 
279      * 
280      * @param namespaceURI the namespace of the attribute or <code>null</code>.
281      * @param localName the local name of the attribute.
282      * @return returns the value of the attribute or <code>null</code>.
283      * @throws IllegalStateException if not a START_ELEMENT or ATTRIBUTE.
284      */
285     public CharArray getAttributeValue(CharSequence   namespaceURI,
286             CharSequence   localName);
287 
288     /**
289      * Returns the count of attributes on this START_ELEMENT, this method is
290      * only valid on a START_ELEMENT or ATTRIBUTE. This count excludes namespace
291      * definitions. Attribute indices are zero-based.
292      * 
293      * @return returns the number of attributes.
294      * @throws IllegalStateException if not a START_ELEMENT or ATTRIBUTE.
295      */
296     public int getAttributeCount();
297 
298     /**
299      * Returns the namespace of the attribute at the provided index
300      * 
301      * @param index the position of the attribute.
302      * @return the namespace URI or <code>null</code> if no prefix. 
303      * @throws IllegalStateException if not a START_ELEMENT or ATTRIBUTE.
304      */
305     public CharArray getAttributeNamespace(int index);
306 
307     /**
308      * Returns the localName of the attribute at the provided index.
309      * 
310      * @param index the position of the attribute.
311      * @return the localName of the attribute.
312      * @throws IllegalStateException if not a START_ELEMENT or ATTRIBUTE.
313      */
314     public CharArray getAttributeLocalName(int index);
315 
316     /**
317      * Returns the prefix of this attribute at the provided index
318      * 
319      * @param index the position of the attribute.
320      * @return the prefix of the attribute or <code>null</code> if no prefix.
321      * @throws IllegalStateException if not a START_ELEMENT or ATTRIBUTE.
322      */
323     public CharArray getAttributePrefix(int index);
324 
325     /**
326      * Returns the XML type of the attribute at the provided index.
327      * 
328      * @param index the position of the attribute
329      * @return the XML type of the attribute.
330      * @throws IllegalStateException if not a START_ELEMENT or ATTRIBUTE.
331      */
332     public CharArray getAttributeType(int index);
333 
334     /**
335      * Returns the value of the attribute at the index.
336      * 
337      * @param index the position of the attribute.
338      * @return the attribute value.
339      * @throws IllegalStateException if not a START_ELEMENT or ATTRIBUTE.
340      */
341     public CharArray getAttributeValue(int index);
342 
343     /**
344      * Indicates if this attribute was created by default.
345      * 
346      * @param index the position of the attribute.
347      * @return <code>true</code> if this is a default attribute;
348      *         <code>false</code> otherwise.
349      * @throws IllegalStateException if not a START_ELEMENT or ATTRIBUTE.
350      */
351     public boolean isAttributeSpecified(int index);
352 
353     /**
354      * Returns the count of namespaces declared on this START_ELEMENT or
355      * END_ELEMENT. This method is only valid on a START_ELEMENT, END_ELEMENT or
356      * NAMESPACE. On an END_ELEMENT the count is of the namespaces that are
357      * about to go out of scope. This is the equivalent of the information
358      * reported by SAX callback for an end element event.
359      * 
360      * @return returns the number of namespace declarations on this specific
361      *         element.
362      * @throws IllegalStateException if not a START_ELEMENT or END_ELEMENT.
363      */
364     public int getNamespaceCount();
365 
366     /**
367      * Returns the prefix for the namespace declared at the index. 
368      * 
369      * @param index the position of the namespace declaration.
370      * @return returns the namespace prefix or <code>null</code> if no prefix.
371      * @throws IllegalStateException if this is not a START_ELEMENT, 
372      *         END_ELEMENT or NAMESPACE.
373      */
374     public CharArray getNamespacePrefix(int index);
375 
376     /**
377      * Returns the URI for the namespace declared at the index.
378      * 
379      * @param index the position of the namespace declaration.
380      * @return returns the namespace uri or <code>null</code> if no prefix.
381      * @throws IllegalStateException if this is not a START_ELEMENT, 
382      *         END_ELEMENT or NAMESPACE.
383      */
384     public CharArray getNamespaceURI(int index);
385 
386     /**
387      * Returns a read only namespace context for the current position.
388      * 
389      * @return return a namespace context
390      */
391     public NamespaceContext getNamespaceContext();
392 
393     /**
394      * Returns an integer code that indicates the type of the event the cursor
395      * is pointing to.
396      * 
397      * @return the event type.
398      */
399     public int getEventType();
400 
401     /**
402      * Returns the current value of the parse event as a string, this returns
403      * the string value of a CHARACTERS event, returns the value of a COMMENT,
404      * the replacement value for an ENTITY_REFERENCE, the string value of a
405      * CDATA section, the string value for a SPACE event, or the String value of
406      * the internal subset of the DTD. If an ENTITY_REFERENCE has been resolved,
407      * any character data will be reported as CHARACTERS events.
408      * 
409      * @return the current text or <code>null</code>
410      * @throws IllegalStateException if this state is not a valid text state.
411      */
412     public CharArray getText();
413 
414     /**
415      * Returns an array which contains the characters from this event. This
416      * array should be treated as read-only and transient. I.e. the array will
417      * contain the text characters until the XMLStreamReader moves on to the
418      * next event. Attempts to hold onto the character array beyond that time or
419      * modify the contents of the array are breaches of the contract for this
420      * interface.
421      * 
422      * @return the current text or an empty array.
423      * @throws IllegalStateException if this state is not a valid text state.
424      */
425     public char[] getTextCharacters();
426 
427     /**
428      * Gets the the text associated with a CHARACTERS, SPACE or CDATA event.
429      * Text starting a "sourceStart" is copied into "target" starting at
430      * "targetStart". Up to "length" characters are copied. The number of
431      * characters actually copied is returned.
432      * 
433      * The "sourceStart" argument must be greater or equal to 0 and less than or
434      * equal to the number of characters associated with the event. Usually, one
435      * requests text starting at a "sourceStart" of 0. If the number of
436      * characters actually copied is less than the "length", then there is no
437      * more text. Otherwise, subsequent calls need to be made until all text has
438      * been retrieved. For example:
439      * 
440      * <code>
441      * int length = 1024;
442      * char[] myBuffer = new char[ length ];
443      * 
444      * for ( int sourceStart = 0 ; ; sourceStart += length )
445      * {
446      *    int nCopied = stream.getTextCharacters( sourceStart, myBuffer, 0, length );
447      *
448      *   if (nCopied < length)
449      *       break;
450      * }
451      * </code> XMLStreamException may be thrown
452      * if there are any XML errors in the underlying source. The "targetStart"
453      * argument must be greater than or equal to 0 and less than the length of
454      * "target", Length must be greater than 0 and "targetStart + length" must
455      * be less than or equal to length of "target".
456      * 
457      * @param sourceStart the index of te first character in the source array 
458      *        to copy
459      * @param target the destination array
460      * @param targetStart the start offset in the target array
461      * @param length the number of characters to copy
462      * @return the number of characters actually copied
463      * @throws XMLStreamException if the XML source is not well-formed.
464      * @throws IndexOutOfBoundsException
465      *             if targetStart < 0 or > than the length of target
466      * @throws IndexOutOfBoundsException
467      *             if length < 0 or targetStart + length > length of target
468      * @throws UnsupportedOperationException if this method is not supported.
469      */
470     public int getTextCharacters(int sourceStart, char[] target,
471             int targetStart, int length) throws XMLStreamException;
472 
473     /**
474      * Returns the offset into the text character array where the first
475      * character (of this text event) is stored.
476      * 
477      * @throws IllegalStateException if this state is not a valid text state.
478      */
479     public int getTextStart();
480 
481     /**
482      * Returns the length of the sequence of characters for this Text event
483      * within the text character array.
484      * 
485      * @throws IllegalStateException if this state is not a valid text state.
486      */
487     public int getTextLength();
488 
489     /**
490      * Returns the input encoding if known or <code>null</code> if unknown.
491      * 
492      * @return the encoding of this instance or null.
493      */
494     public String   getEncoding();
495 
496     /**
497      * Indicates if the current event has text. The following
498      * events have text: CHARACTERS, DTD ,ENTITY_REFERENCE, COMMENT, SPACE.
499      * 
500      * @return <code>true</code> if the current event as text;
501      *         <code>false</code> otherwise.
502      */
503     public boolean hasText();
504 
505     /**
506      * Return the current location of the processor. If the Location is unknown
507      * the processor should return an implementation of Location that returns -1
508      * for the location and null for the publicId and systemId. The location
509      * information is only valid until next() is called.
510      * 
511      * @return the current location.
512      */
513     public Location getLocation();
514 
515     /**
516      * Returns the (local) name of the current event. For START_ELEMENT or
517      * END_ELEMENT returns the (local) name of the current element. For
518      * ENTITY_REFERENCE it returns entity name. The current event must be
519      * START_ELEMENT or END_ELEMENT, or ENTITY_REFERENCE.
520      * 
521      * @return the localName.
522      * @throws IllegalStateException if this not a START_ELEMENT, END_ELEMENT 
523      *         or ENTITY_REFERENCE
524      */
525     public CharArray getLocalName();
526 
527     /**
528      * Indicates if the current event has a name (is a START_ELEMENT or
529      * END_ELEMENT).
530      * 
531      * @return <code>true</code> if the current event has a name;
532      *         <code>false</code> otherwise.
533      */
534     public boolean hasName();
535 
536     /**
537      * If the current event is a START_ELEMENT or END_ELEMENT this method
538      * returns the URI of the current element (URI mapping to the prefix
539      * element/attribute has; or if no prefix <code>null</code>).
540      * 
541      * @return the URI bound to this elements prefix or <code>null</code>.
542      * @throws IllegalStateException if not a START_ELEMENT, END_ELEMENT 
543      *         or ATTRIBUTE.
544      */
545     public CharArray getNamespaceURI();
546 
547     /**
548      * Returns the prefix of the current event or null if the event does not
549      * have a prefix.
550      * 
551      * @return the prefix or <code>null</code>
552      * @throws IllegalStateException if not a START_ELEMENT or END_ELEMENT.
553      */
554     public CharArray getPrefix();
555 
556     /**
557      * Gets the xml version declared on the xml declaration. 
558      * 
559      * @return the XML version or <code>null</code>
560      */
561     public CharArray getVersion();
562 
563     /**
564      * Gets the standalone declaration from the xml declaration.
565      * 
566      * @return <code>true</code> if this is standalone; 
567      *         <code>false</code> otherwise.
568      */
569     public boolean isStandalone();
570 
571     /**
572      * Checks if standalone was set in the document.
573      * 
574      * @return <code>true</code> if standalone was set; 
575      *         <code>false</code> otherwise.
576      */
577     public boolean standaloneSet();
578 
579     /**
580      * Returns the character encoding declared on the xml declaration.
581      * 
582      * @return the encoding declared in the document or <code>null</code>
583      */
584     public CharArray getCharacterEncodingScheme();
585 
586     /**
587      * Returns the target of a processing instruction.
588      * 
589      * @return the target.
590      * @throws IllegalStateException  if the current event is not a
591      *             {@link XMLStreamConstants#PROCESSING_INSTRUCTION}
592      */
593     public CharArray getPITarget();
594 
595     /**
596      * Get the data section of a processing instruction.
597      * 
598      * @return the data (if processing instruction has any) or
599      *         <code>null</code> if the processing instruction only has target.
600      * @throws IllegalStateException if the current event is not a
601      *             {@link XMLStreamConstants#PROCESSING_INSTRUCTION}
602      */
603     public CharArray getPIData();
604 }
605
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags