Package com.sun.xml.rpc.sp

Class StreamingParser

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 final int
    ATTR
    State value indicating that an attribute has been parsed.
    static final int
    CHARS
    State value indicating that character data has been parsed.
    static final int
    END
    State value indicating that an end tag has been parsed.
    static final int
    IWS
    State value indicating that ignorable whitespace has been parsed.
    static final int
    PI
    State value indicating that a processing instruction has been parsed.
    static final 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

    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 Details

    • 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:

    • 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:

    • 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:

    • 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:

    • IWS

      public static final int IWS
      State value indicating that ignorable whitespace has been parsed. The value() method will return the whitespace.
      See Also:

    • 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:

  • Constructor Details

    • StreamingParser

      protected StreamingParser()
      Construct a new StreamingParser.

  • Method Details

    • 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