java.lang.Object
- com.sun.xml.rpc.sp.StreamingParser

Direct Known Subclasses:: StreamingParserImpl

public abstract class StreamingParser
extends Object

A simple demand-driven XML parser interface.

There are no public constructors for this class. New instances are created by first creating and configuring, if necessary, an instance of the StreamingParserFactory class.

After each invocation of the parse method an instance of this class will be in one of the following states. In each state the name, value, and uriString methods may be invoked to return the data specified in the following table. If no data is specified for a given method and state then invoking that method in that state will cause an IllegalStateException to be thrown.

state     description     name()     value()     uriString()

START     Start tag     Element name     Element namespace

END     End tag     Element name     Element namespace

ATTR     Attribute     Name     Value     Attribute namespace

CHARS     Character data     Data

IWS Ignorable whitespace     Whitespace

PI     Processing instruction     Target name     Content

If a start tag has any attributes then the START state for that tag will immediately be followed by a sequence of ATTR states, one per attribute. The attributes are parsed in the order in which they appear in the document.

An empty tag, that is, a tag of the form <foo/>, will yield a START state and then an END state, possibly with some ATTR states in between.

If the parser is namespace-aware then the uriString method may be invoked in the START, END, and ATTR states to return the namespace in which the element or attribute is defined. Otherwise, the uriString method just returns null at those states.

Note that because detecting ignorable whitespace requires a DTD, the IWS state will be entered only when validation is being performed.

There is otherwise no restriction on the allowable state transitions other than those induced by the structure of the XML document being parsed.

Author:: Mark Reinhold, JAX-RPC RI Development Team

Field Summary

Fields
Modifier and Type	Field	Description
`static int`	`ATTR`	State value indicating that an attribute has been parsed.
`static int`	`CHARS`	State value indicating that character data has been parsed.
`static int`	`END`	State value indicating that an end tag has been parsed.
`static int`	`IWS`	State value indicating that ignorable whitespace has been parsed.
`static int`	`PI`	State value indicating that a processing instruction has been parsed.
`static int`	`START`	State value indicating that a start tag has been parsed.

Constructor Summary

Constructors
Modifier Constructor Description

protected StreamingParser()
Construct a new StreamingParser.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method	Description
`abstract int`	`column()`	Returns the column number of the current component, or `-1` if the column number is not known.
`abstract String`	`describe(boolean articleNeeded)`	Constructs a string describing the current state of this parser, suitable for use in an error message or an exception detail string.
`static String`	`describe(int state, String name, String value, boolean articleNeeded)`	Constructs a string describing the given parser state, suitable for use in an error message or an exception detail string.
`abstract boolean`	`isCoalescing()`	Returns the coalescing property of this parser.
`abstract boolean`	`isNamespaceAware()`	Returns the namespaceAware property of this parser.
`abstract boolean`	`isValidating()`	Returns the validating property of this parser.
`abstract int`	`line()`	Returns the line number of the current component, or `-1` if the line number is not known.
`abstract String`	`name()`	Returns a name string whose meaning depends upon the current state.
`abstract int`	`parse()`	Parses the next component of the document being parsed.
`abstract String`	`publicId()`	Returns the public identifer of the document being parsed, or `null` if it has none.
`abstract int`	`state()`	Returns the current state of the parser.
`abstract String`	`systemId()`	Returns the system identifer of the document being parsed, or `null` if it has none.
`String`	`toString()`
`abstract String`	`uriString()`	Returns the URI string of the current component.
`abstract String`	`value()`	Returns a value string whose meaning depends upon the current state.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - START
```
public static final int START
```
    State value indicating that a start tag has been parsed. The name() method will return the name of the element just started.
    
    See Also:
    
    Constant Field Values
  - END
```
public static final int END
```
    State value indicating that an end tag has been parsed. The name() method will return the name of the element just ended.
    
    See Also:
    
    Constant Field Values
  - ATTR
```
public static final int ATTR
```
    State value indicating that an attribute has been parsed. The name() method will return the name of the attribute, while the value() method will return its value.
    
    See Also:
    
    Constant Field Values
  - CHARS
```
public static final int CHARS
```
    State value indicating that character data has been parsed. The value() method will return the parsed characters.
    
    See Also:
    
    Constant Field Values
  - IWS
```
public static final int IWS
```
    State value indicating that ignorable whitespace has been parsed. The value() method will return the whitespace.
    
    See Also:
    
    Constant Field Values
  - PI
```
public static final int PI
```
    State value indicating that a processing instruction has been parsed. The name() method will return the target of the instruction, while the value() method will return its content.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - StreamingParser
```
protected StreamingParser()
```
    Construct a new StreamingParser.
- Method Detail
  - parse
```
public abstract int parse()
                   throws ParseException,
                          IOException
```
    Parses the next component of the document being parsed.
    
    Returns:
    
    The parser's current state, one of START, END, ATTR, CHARS, IWS, or PI, or -1 if the end of the document has been reached
    
    Throws:
    
    ParseException - If an XML parsing error occurs
    
    IOException - If an I/O error occurs
  - state
```
public abstract int state()
```
    Returns the current state of the parser.
    
    Returns:
    
    The parser's current state, one of START, END, ATTR, CHARS, IWS, or PI, or -1 if the end of the document has been reached.
    
    Throws:
    
    IllegalStateException - If the parser has yet not been started by invoking the parse() method
  - name
```
public abstract String name()
```
    Returns a name string whose meaning depends upon the current state.
    
    Throws:
    
    IllegalStateException - If there is no name data for the current parser state
  - value
```
public abstract String value()
```
    Returns a value string whose meaning depends upon the current state.
    
    Throws:
    
    IllegalStateException - If there is no value data for the current parser state
  - uriString
```
public abstract String uriString()
```
    Returns the URI string of the current component.
    
    Throws:
    
    IllegalStateException - If there is no URI for the current component
  - line
```
public abstract int line()
```
    Returns the line number of the current component, or -1 if the line number is not known.
  - column
```
public abstract int column()
```
    Returns the column number of the current component, or -1 if the column number is not known.
  - publicId
```
public abstract String publicId()
```
    Returns the public identifer of the document being parsed, or null if it has none.
  - systemId
```
public abstract String systemId()
```
    Returns the system identifer of the document being parsed, or null if it has none.
  - isValidating
```
public abstract boolean isValidating()
```
    Returns the validating property of this parser.
    
    Returns:
    
    true if, and only if, this parser will perform validation
  - isCoalescing
```
public abstract boolean isCoalescing()
```
    Returns the coalescing property of this parser.
    
    Returns:
    
    true if, and only if, this parser will coalesce adjacent runs of character data
  - isNamespaceAware
```
public abstract boolean isNamespaceAware()
```
    Returns the namespaceAware property of this parser.
    
    Returns:
    
    true if, and only if, this parser will support namespace
  - describe
```
public static String describe(int state,
                              String name,
                              String value,
                              boolean articleNeeded)
```
    Constructs a string describing the given parser state, suitable for use in an error message or an exception detail string.
    
    Parameters:
    
    state - A parser state, one of START, END, ATTR, CHARS, IWS, or PI, or -1 if the end of the document has been reached
    
    name - The name data for the parser state, or null if there is none
    
    value - The value data for the parser state, or null if there is none
    
    articleNeeded - Whether an appropriate article ("a", "an", "some", or "the") is to be prepended to the description string
    
    Returns:
    
    A string describing the given parser state.
  - describe
```
public abstract String describe(boolean articleNeeded)
```
    Constructs a string describing the current state of this parser, suitable for use in an error message or an exception detail string.
    
    Parameters:
    
    articleNeeded - Whether an appropriate article ("a", "an", "some", or "the") is to be prepended to the description string
    
    Returns:
    
    A string describing the given parser state.
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

state	description	`name()`	`value()`	`uriString()`
START	Start tag	Element name		Element namespace
END	End tag	Element name		Element namespace
ATTR	Attribute	Name	Value	Attribute namespace
CHARS	Character data		Data
IWS	Ignorable whitespace		Whitespace
PI	Processing instruction	Target name	Content

Class StreamingParser

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

START

END

ATTR

CHARS

IWS

PI

Constructor Detail

StreamingParser

Method Detail

parse

state

name

value

uriString

line

column

publicId

systemId

isValidating

isCoalescing

isNamespaceAware

describe

describe

toString