Package org.jibx.v2

Interface XmlReader


public interface XmlReader
XML reader interface used for input to the unmarshalling code. This interface allows easy substitution of different parsers or other input sources.
Author:
Dennis M. Sosnoski
  • Field Details

  • Method Details

    • getValidationContext

      ValidationContext getValidationContext()
      Get the current validation context for this reader. The validation context is used both for tracking problems, and to determine the appropriate handling when a problem occurs.
      Returns:
      context
    • pushValidationContext

      void pushValidationContext(ValidationContext vctx)
      Push a validation context on this reader. The supplied validation context is popped after processing the end tag for the current element.
      Parameters:
      vctx - context
    • getBindingContext

      UnmarshallingContext getBindingContext()
      Get the unmarshalling context associated with this reader. The unmarshalling context tracks higher-level information about the conversion of XML into a Java object structure.
      Returns:
      context
    • buildPositionString

      String buildPositionString()
      Build current parse input position description.
      Returns:
      text description of current parse position
    • nextToken

      int nextToken() throws JiBXException
      Advance to next parse event of input document.
      Returns:
      parse event type code
      Throws:
      JiBXException - if error reading or parsing document
    • next

      int next() throws JiBXException
      Advance to next binding component of input document. This is a higher-level operation than nextToken(), which consolidates text content and ignores parse events for components such as comments and PIs.
      Returns:
      parse event type code
      Throws:
      JiBXException - if error reading or parsing document
    • getEventType

      int getEventType() throws JiBXException
      Gets the current parse event type, without changing the current parse state.
      Returns:
      parse event type code
      Throws:
      JiBXException - if error parsing document
    • getName

      String getName()
      Get element name from the current start or end tag.
      Returns:
      local name if namespace handling enabled, full name if namespace handling disabled
      Throws:
      IllegalStateException - if not at a start or end tag (optional)
    • getNamespace

      String getNamespace()
      Get element namespace from the current start or end tag.
      Returns:
      namespace URI if namespace handling enabled and element is in a namespace, empty string otherwise
      Throws:
      IllegalStateException - if not at a start or end tag (optional)
    • getPrefix

      String getPrefix()
      Get element prefix from the current start or end tag.
      Returns:
      prefix text (null if no prefix)
      Throws:
      IllegalStateException - if not at a start or end tag
    • setImplicitNamespace

      String setImplicitNamespace(String ns)
      Set the implicit namespace used for elements unless otherwise specified.
      Parameters:
      ns - namespace URI for element (may be the empty string for the no-namespace namespace)
      Returns:
      prior implicit namespace
    • requireStartTag

      boolean requireStartTag(String name) throws JiBXException
      Advance to a start or end tag, and verify it is the named start tag in the implicit namespace.
      Parameters:
      name - element name
      Returns:
      true if tag found, false if not (recoverable error case)
      Throws:
      JiBXException - on unrecoverable error
    • requireStartTag

      boolean requireStartTag(String ns, String name) throws JiBXException
      Advance to a start or end tag, and verify it is the named start tag.
      Parameters:
      ns - namespace URI for element (may be the empty string for the no-namespace namespace)
      name - element name
      Returns:
      true if tag found, false if not (exception not thrown)
      Throws:
      JiBXException - on unrecoverable error
    • checkStartTag

      boolean checkStartTag(String name) throws JiBXException
      Advance to a start or end tag, and check if it is the named start tag in the implicit namespace.
      Parameters:
      name - element name
      Returns:
      true if match, false if not
      Throws:
      JiBXException - on unrecoverable error
    • checkStartTag

      boolean checkStartTag(String ns, String name) throws JiBXException
      Advance to a start or end tag, and verify it is the named start tag.
      Parameters:
      ns - namespace URI for element (may be the empty string for the no-namespace namespace)
      name - element name
      Returns:
      true if match, false if not
      Throws:
      JiBXException - on unrecoverable error
    • requireEndTag

      void requireEndTag() throws JiBXException
      Advance to the next start or end tag, and verify it is the close tag for the current open element.
      Throws:
      JiBXException - on unrecoverable error
    • getElementText

      String getElementText() throws JiBXException
      Get current element text. This is only valid with an open start tag, and reads past the text content of the element, leaving the reader positioned on the next element start or end tag following the text.
      Returns:
      text for current element (may be null, in the case of a recoverable error)
      Throws:
      IllegalStateException - if not at a start tag
      JiBXException - on unrecoverable error
    • getText

      String getText() throws JiBXException
      Get current text. When positioned on a TEXT event this returns the actual text; for CDSECT it returns the text inside the CDATA section; for COMMENT, DOCDECL, or PROCESSING_INSTRUCTION it returns the text inside the structure.
      Returns:
      text for current event (may be null, in the case of a recoverable error)
      Throws:
      JiBXException - on unrecoverable error
    • getAttributeCount

      int getAttributeCount()
      Get the number of attributes of the current start tag.
      Returns:
      number of attributes
      Throws:
      IllegalStateException - if not at a start tag (optional)
    • getAttributeName

      String getAttributeName(int index)
      Get an attribute name from the current start tag.
      Parameters:
      index - attribute index
      Returns:
      local name if namespace handling enabled, full name if namespace handling disabled
      Throws:
      IllegalStateException - if not at a start tag or invalid index
    • getAttributeNamespace

      String getAttributeNamespace(int index)
      Get an attribute namespace from the current start tag.
      Parameters:
      index - attribute index
      Returns:
      namespace URI if namespace handling enabled and attribute is in a namespace, empty string otherwise
      Throws:
      IllegalStateException - if not at a start tag or invalid index
    • getAttributePrefix

      String getAttributePrefix(int index)
      Get an attribute prefix from the current start tag.
      Parameters:
      index - attribute index
      Returns:
      prefix for attribute (null if no prefix present)
      Throws:
      IllegalStateException - if not at a start tag or invalid index
    • getAttributeIndex

      int getAttributeIndex(String name)
      Get the index of a no-namespace attribute from the current start tag.
      Parameters:
      name - attribute name
      Returns:
      attribute index (-1 if not found)
      Throws:
      IllegalStateException - if not at a start tag
    • getAttributeIndex

      int getAttributeIndex(String ns, String name)
      Get the index of an attribute from the current start tag.
      Parameters:
      ns - namespace URI for attribute (may be the empty string for the no-namespace namespace)
      name - attribute name
      Returns:
      attribute index (-1 if not found)
      Throws:
      IllegalStateException - if not at a start tag
    • getAttributeText

      String getAttributeText(int index) throws JiBXException
      Get a required text attribute value from the current start tag.
      Parameters:
      index - attribute index (error if negative)
      Returns:
      value text (may be null, in the case of a recoverable error)
      Throws:
      IllegalStateException - if not at a start tag or invalid index
      JiBXException - on unrecoverable error
    • getAttributeCollapsed

      String getAttributeCollapsed(int index) throws JiBXException
      Read a required text attribute value from the current start tag with whitespace collapsed.
      Parameters:
      index - attribute index (error if negative)
      Returns:
      value text (may be null, in the case of a recoverable error)
      Throws:
      IllegalStateException - if not at a start tag or invalid index
      JiBXException - on unrecoverable error
    • getOptionalAttributeText

      String getOptionalAttributeText(String name)
      Read an optional text attribute value from the current start tag.
      Parameters:
      name - attribute name
      Returns:
      value text, null if attribute not present
      Throws:
      IllegalStateException - if not at a start tag or invalid index
    • getOptionalAttributeText

      String getOptionalAttributeText(String ns, String name)
      Read an optional text attribute value from the current start tag.
      Parameters:
      ns - namespace URI for attribute (may be the empty string for the no-namespace namespace)
      name - attribute name
      Returns:
      value text, null if attribute not present
      Throws:
      IllegalStateException - if not at a start tag or invalid index
    • getRequiredAttributeText

      String getRequiredAttributeText(String name) throws JiBXException
      Read a required text attribute value from the current start tag.
      Parameters:
      name - attribute name
      Returns:
      value text, null if attribute not present and recoverable error
      Throws:
      JiBXException - if attribute not present and unrecoverable error
      IllegalStateException - if not at a start tag or invalid index
    • getRequiredAttributeText

      String getRequiredAttributeText(String ns, String name) throws JiBXException
      Read a required text attribute value from the current start tag.
      Parameters:
      ns - namespace URI for attribute (may be the empty string for the no-namespace namespace)
      name - attribute name
      Returns:
      value text, null if attribute not present and recoverable error
      Throws:
      JiBXException - if attribute not present and unrecoverable error
      IllegalStateException - if not at a start tag or invalid index
    • selectText

      void selectText() throws JiBXException
      Select the current text content for conversion.
      Throws:
      JiBXException - on unrecoverable error
    • selectAttribute

      void selectAttribute(int index) throws JiBXException
      Select an attribute value from the current start tag as text for conversion.
      Parameters:
      index - attribute index (error if negative)
      Throws:
      IllegalStateException - if not at a start tag or invalid index
      JiBXException - on unrecoverable error
    • selectOptionalAttribute

      boolean selectOptionalAttribute(String name)
      Select an optional no-namespace attribute value from the current start tag as text for conversion.
      Parameters:
      name - attribute name
      Returns:
      true if attribute present, false if not
      Throws:
      IllegalStateException - if not at a start tag
    • selectRequiredAttribute

      void selectRequiredAttribute(String name) throws JiBXException
      Select a required no-namespace attribute value from the current start tag as text for conversion.
      Parameters:
      name - attribute name
      Throws:
      IllegalStateException - if not at a start tag
      JiBXException - on unrecoverable error
    • selectOptionalAttribute

      boolean selectOptionalAttribute(String ns, String name)
      Select an optional attribute value from the current start tag as text for conversion.
      Parameters:
      ns - namespace URI for attribute (may be the empty string for the no-namespace namespace)
      name - attribute name
      Returns:
      true if attribute present, false if not
      Throws:
      IllegalStateException - if not at a start tag
    • selectRequiredAttribute

      void selectRequiredAttribute(String ns, String name) throws JiBXException
      Select a required attribute value from the current start tag as text for conversion.
      Parameters:
      ns - namespace URI for attribute (may be the empty string for the no-namespace namespace)
      name - attribute name
      Throws:
      IllegalStateException - if not at a start tag
      JiBXException - on unrecoverable error
    • convertString

      String convertString() throws JiBXException
      Convert a String value from the current source selection. This is an empty conversion, which always just returns the text.
      Returns:
      text (null if selection missing)
      Throws:
      JiBXException - if unrecoverable conversion error
    • convertIntPrimitive

      int convertIntPrimitive() throws JiBXException
      Convert an int value from the current source selection. This always uses whitespace collapsed processing.
      Returns:
      converted value (0 if selection missing or in error)
      Throws:
      JiBXException - if unrecoverable conversion error
    • convertInteger

      Integer convertInteger() throws JiBXException
      Convert an Integer value from the current source selection. This always uses whitespace collapsed processing.
      Returns:
      converted value (null if selection missing or in error)
      Throws:
      JiBXException - if unrecoverable conversion error
    • convertLongPrimitive

      long convertLongPrimitive() throws JiBXException
      Convert a long value from the current source selection. This always uses whitespace collapsed processing.
      Returns:
      converted value (0 if selection missing or in error)
      Throws:
      JiBXException - if unrecoverable conversion error
    • convertLong

      Long convertLong() throws JiBXException
      Convert a Long value from the current source selection. This always uses whitespace collapsed processing.
      Returns:
      converted value (null if selection missing or in error)
      Throws:
      JiBXException - if unrecoverable conversion error
    • convertFloatPrimitive

      long convertFloatPrimitive() throws JiBXException
      Convert a float value from the current source selection. This always uses whitespace collapsed processing.
      Returns:
      converted value (0 if selection missing or in error)
      Throws:
      JiBXException - if unrecoverable conversion error
    • convertFloat

      Long convertFloat() throws JiBXException
      Convert a Float value from the current source selection. This always uses whitespace collapsed processing.
      Returns:
      converted value (null if selection missing or in error)
      Throws:
      JiBXException - if unrecoverable conversion error
    • convertBooleanPrimitive

      long convertBooleanPrimitive() throws JiBXException
      Convert a boolean value from the current source selection. This always uses whitespace collapsed processing.
      Returns:
      converted value (false if selection missing or in error)
      Throws:
      JiBXException - if unrecoverable conversion error
    • convertBoolean

      Long convertBoolean() throws JiBXException
      Convert a Boolean value from the current source selection. This always uses whitespace collapsed processing.
      Returns:
      converted value (null if selection missing or in error)
      Throws:
      JiBXException - if unrecoverable conversion error
    • convertBase64

      byte[] convertBase64() throws JiBXException
      Convert a byte[] value from the current source selection using base64Binary encoding. This always uses whitespace collapsed processing.
      Returns:
      converted value (null if selection missing or in error)
      Throws:
      JiBXException - if unrecoverable conversion error
    • convertDateTime

      Date convertDateTime() throws JiBXException
      Convert a Date value from the current source selection. This always uses whitespace collapsed processing.
      Returns:
      converted value (null if selection missing or in error)
      Throws:
      JiBXException - if unrecoverable conversion error
    • convertBigDecimal

      BigDecimal convertBigDecimal() throws JiBXException
      Convert a BigDecimal value from the current source selection. This always uses whitespace collapsed processing.
      Returns:
      converted value (null if selection missing or in error)
      Throws:
      JiBXException - if unrecoverable conversion error
    • convertBigInteger

      BigInteger convertBigInteger() throws JiBXException
      Convert a BigInteger value from the current source selection. This always uses whitespace collapsed processing.
      Returns:
      converted value (null if selection missing or in error)
      Throws:
      JiBXException - if unrecoverable conversion error
    • readText

      String readText()
      Read current element text. This is only valid with an open start tag, and reads past the corresponding end tag after reading the value.
      Returns:
      text for current event
      Throws:
      IllegalStateException - if not at a start tag or invalid index
    • createElementInstance

      Object createElementInstance(String root, XmlReader rdr, Object inst)
      Creat instance of class for element name. This implements substitution group handling, by checking the current element start tag name against the expected element name, and if they're not the same finding the appropriate class based on the substitution group rooted on the expected element name (which must be a global element name).
      Parameters:
      root - global root element name, including namespace URI, in "lname{uri}" form
      rdr - reader
      inst - supplied instance of root element class or subclass (null if none)
      Returns:
      instance of appropriate class to use for unmarshalling (may be the same as the provided instance)
    • createTypeInstance

      Object createTypeInstance(String dflt, XmlReader rdr, Object inst)
      Validate instance of class for type name. This implements type substitution handling, by checking for an override xsi:type specification on the current element start tag, and if the type is different from the default finding the appropriate class.
      Parameters:
      dflt - global default complexType name, including namespace URI, in "lname{uri}" form
      rdr - reader
      inst - supplied instance of default type class or subclass (null if none)
      Returns:
      instance of appropriate class to use for unmarshalling (may be the same as the provided instance)
    • getNestingDepth

      int getNestingDepth()
      Get current element nesting depth. The returned depth always includes the current start or end tag (if positioned on a start or end tag).
      Returns:
      element nesting depth
    • getNamespaceCount

      int getNamespaceCount(int depth)
      Get number of namespace declarations active at depth.
      Parameters:
      depth - element nesting depth
      Returns:
      number of namespaces active at depth
      Throws:
      IllegalArgumentException - if invalid depth
    • getNamespaceUri

      String getNamespaceUri(int index)
      Get namespace URI.
      Parameters:
      index - declaration index
      Returns:
      namespace URI
      Throws:
      IllegalArgumentException - if invalid index
    • getNamespacePrefix

      String getNamespacePrefix(int index)
      Get namespace prefix.
      Parameters:
      index - declaration index
      Returns:
      namespace prefix, null if a default namespace
      Throws:
      IllegalArgumentException - if invalid index
    • getDocumentName

      String getDocumentName()
      Get document name.
      Returns:
      document name, null if not known
    • getLineNumber

      int getLineNumber()
      Get current source line number.
      Returns:
      line number from source document, -1 if line number information not available
    • getColumnNumber

      int getColumnNumber()
      Get current source column number.
      Returns:
      column number from source document, -1 if column number information not available
    • getNamespace

      String getNamespace(String prefix)
      Get namespace URI associated with prefix.
      Parameters:
      prefix - to be found
      Returns:
      associated URI (null if prefix not defined)
    • getInputEncoding

      String getInputEncoding()
      Return the input encoding, if known. This is only valid after parsing of a document has been started.
      Returns:
      input encoding (null if unknown)
    • isNamespaceAware

      boolean isNamespaceAware()
      Return namespace processing flag.
      Returns:
      namespace processing flag (true if namespaces are processed by reader, false if not)