public abstract class

SAXSupport

extends Object
java.lang.Object
   ↳ com.microstrategy.utils.xml.SAXSupport

Class Overview

This is a wrapper around the SAX parser that provides the following services:

  • Hides the actual parser implementation
  • Maintains the stack of active ContentHandlers
  • Provide set of static helper methods for dealing with XML content

This class is not thread-safe.

Summary

Public Constructors
SAXSupport()
Public Methods
static boolean getBoolAttribute(Attributes attrs, String name, boolean defaultVal)
If specified attribute is present in attrs collection this method will return true if the attribute hase value "1" and false if it has value "0".
static boolean getBoolAttribute(Attributes attrs, String name)
This method returns true if specified attribute is present in attrs collection and has value "1".
Object getContextObject(String key)
static SAXParserFactory getDefaultFactory()
Returns default SAXParserFactory that is used to create SAXParsers in the getInstance() method.
static SAXSupport getInstance(SAXParserFactory factory, Set<String> allowEntityPath)
A factory method that returns new SAXSupport instance.
static SAXSupport getInstance(SAXParserFactory factory)
A factory method that returns new SAXSupport instance.
static SAXSupport getInstance()
A factory method that returns new SAXSupport instance.
static SAXSupport getInstance(Set<String> allowEntityPath)
A factory method that returns new SAXSupport instance.
static int getIntAttribute(String tag, Attributes attrs, String name)
This method returns attribute value from the attrs collection converted to the integer.
static int getIntAttribute(String tag, Attributes attrs, String name, int defaultVal)
This method returns attribute value from the attrs collection converted to the integer or defaultVal if the attribute does not exist.
abstract SAXParser getParser()
Returns SAXParser associated with this object.
static String getStrAttribute(String tag, Attributes attrs, String name)
This method returns attribute value from the attrs collection.
static String getStrAttribute(Attributes attrs, String name, String defaultVal)
This method returns attribute value from the attrs collection or defaultVal if the attribute does not exist.
abstract XMLReader getXMLReader()
static void invalidAttrFormat(String tag, String name, String val)
Throws SAXSupportException exception with "Invalid attribute value format" message
static void missingAttribute(String tag, String name)
Throws SAXSupportException exception with "Missing attribute" message
abstract void parse(InputSource iSrc, ContentHandler contHandler)
Parses XML presented by iSrc using specified content handler
abstract void parse(String xml, ContentHandler contHandler)
Parses XML string using specified content handler
abstract void parse(File xmlFile, ContentHandler contHandler)
Parses XML file using specified content handler
abstract ContentHandler popContentHandler(String uri, String local, String qName)
This method shall be called from the content handler's endElelment method to reattach the parent content handler to the xmlReader.
abstract void pushContentHandler(ContentHandler contHandler)
This method shall be called from the content handler's startElelment method to attach another content handler to the xmlReader.
abstract void pushContentHandler(AbstractHandler contHandler)
This method shall be called from the content handler's startElelment method to attach another content handler to the xmlReader.
void putContextObject(String key, Object value)
static void unexpectedElement(String tag, String parent)
Throws SAXSupportException exception with "Unexpected element" message
static void unexpectedEndDocument(Object handler)
Call this method to report unexpected end of document event.
static void unexpectedEndElement(Object handler)
Call this method to report unexpected end of element event.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public SAXSupport ()

Public Methods

public static boolean getBoolAttribute (Attributes attrs, String name, boolean defaultVal)

If specified attribute is present in attrs collection this method will return true if the attribute hase value "1" and false if it has value "0". If the attribute is absent then the method will return defaultVal.

Parameters
attrs attribute collection
name attribute name
defaultVal a default value
Returns
  • true or false.
Throws
SAXSupportException if attribute value is not "0" or "1"

public static boolean getBoolAttribute (Attributes attrs, String name)

This method returns true if specified attribute is present in attrs collection and has value "1". It returns false if the attribute is absent or if it has value "0". It will throw SAXSupportException in any other case.

Use this method for boolean attributes that can be present with both "1" and "0" values

Parameters
attrs attribute collection
name attribute name
Returns
  • true or false.
Throws
SAXSupportException if attribute value is not "0" or "1"

public Object getContextObject (String key)

public static SAXParserFactory getDefaultFactory ()

Returns default SAXParserFactory that is used to create SAXParsers in the getInstance() method.

Returns
  • default SAXParserFactory

public static SAXSupport getInstance (SAXParserFactory factory, Set<String> allowEntityPath)

A factory method that returns new SAXSupport instance.

Parameters
factory a factory that shall be used to create SAXParser associated with the instance.
allowEntityPath a set that includes the paths which are allowed to be used in external entities.
Returns
  • new SAXSupport instance.
Throws
XMLSupportRuntimeException if a parser cannot be created which satisfies the requested configuration.
SAXException If error occurs during create the parser or the xml reader.

public static SAXSupport getInstance (SAXParserFactory factory)

A factory method that returns new SAXSupport instance.

Parameters
factory a factory that shall be used to create SAXParser associated with the instance.
Returns
  • new SAXSupport instance.
Throws
XMLSupportRuntimeException if a parser cannot be created which satisfies the requested configuration.
SAXException If error occurs during create the parser or the xml reader.

public static SAXSupport getInstance ()

A factory method that returns new SAXSupport instance. The default factory will be used to create the SAXParser associated with the instance.

Returns
  • new SAXSupport instance.
Throws
XMLSupportRuntimeException if a parser cannot be created which satisfies the requested configuration.
SAXException If error occurs during create the parser or the xml reader.

public static SAXSupport getInstance (Set<String> allowEntityPath)

A factory method that returns new SAXSupport instance. The default factory will be used to create the SAXParser associated with the instance.

Parameters
allowEntityPath a set that includes the paths which are allowed to be used in external entities.
Returns
  • new SAXSupport instance.
Throws
XMLSupportRuntimeException if a parser cannot be created which satisfies the requested configuration.
SAXException If error occurs during create the parser or the xml reader.

public static int getIntAttribute (String tag, Attributes attrs, String name)

This method returns attribute value from the attrs collection converted to the integer. It will throw SAXSupportException if the attribute does not exist. Use this method for mandatory attributes.

Parameters
tag element's tag name. Used in the diagnostic message.
attrs attribute collection
name attribute name
Returns
  • attribute value
Throws
SAXSupportException if attribute does not exists in the collection or if its value is not an integer

public static int getIntAttribute (String tag, Attributes attrs, String name, int defaultVal)

This method returns attribute value from the attrs collection converted to the integer or defaultVal if the attribute does not exist. Use this method for optional attributes.

Parameters
tag element's tag name. Used in the diagnostic message.
attrs attribute collection
name attribute name
defaultVal default value to be used if the attribute does not exist
Returns
  • attribute value
Throws
SAXSupportException if attribute value is not an integer

public abstract SAXParser getParser ()

Returns SAXParser associated with this object. Please use getXMLReader() instead of this method as some application servers will create a XMLReader with each getXMLReader() invocation.

Returns
  • SAXParser associated with this object.

public static String getStrAttribute (String tag, Attributes attrs, String name)

This method returns attribute value from the attrs collection. It will throw WebSAXException if the attribute does not exist. Use this method for mandatory attributes.

Parameters
tag element's tag name. Used in the diagnostic message.
attrs attribute collection
name attribute name
Returns
  • attribute value
Throws
SAXSupportException if attribute does not exists in the collection

public static String getStrAttribute (Attributes attrs, String name, String defaultVal)

This method returns attribute value from the attrs collection or defaultVal if the attribute does not exist. Use this method for optional attributes.

Parameters
attrs attribute collection
name attribute name
defaultVal default value to be used if the attribute does not exist
Returns
  • attribute value

public abstract XMLReader getXMLReader ()

Returns
  • return the underlying XMLReader instance

public static void invalidAttrFormat (String tag, String name, String val)

Throws SAXSupportException exception with "Invalid attribute value format" message

Parameters
tag tag name
name attribute name
val value
Throws
SAXSupportException exception with "Invalid attribute value format" message

public static void missingAttribute (String tag, String name)

Throws SAXSupportException exception with "Missing attribute" message

Parameters
tag tag name
name attribute name
Throws
SAXSupportException exception with "Missing attribute" message.

public abstract void parse (InputSource iSrc, ContentHandler contHandler)

Parses XML presented by iSrc using specified content handler

Parameters
iSrc input source presenting XML document
contHandler a content handler
Throws
SAXException if something is wrong with the input xml
IOException if there are problems with input source

public abstract void parse (String xml, ContentHandler contHandler)

Parses XML string using specified content handler

Parameters
xml XML string
contHandler a content handler
Throws
SAXException if something is wrong with the input xml

public abstract void parse (File xmlFile, ContentHandler contHandler)

Parses XML file using specified content handler

Parameters
xmlFile XML file
contHandler a content handler
Throws
SAXException if something is wrong with the input xml
IOException if there are problems with input file

public abstract ContentHandler popContentHandler (String uri, String local, String qName)

This method shall be called from the content handler's endElelment method to reattach the parent content handler to the xmlReader. Detaches the current content handler from the xmlReader. Pop's from the stack a "parent" content handler, and attaches it to the xmlReader.

The endElement method is called on the new content handler before attaching it to the xmlReader. It is done to allow it to adjust it's level count properly and to do other actions, if any.

Parameters
uri The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.
local The local name (without prefix), or the empty string if Namespace processing is not being performed.
qName The qualified name (with prefix), or the empty string if qualified names are not available.
Returns
  • an old content handler
Throws
IllegalStateException if the handler stack is empty
SAXException can be thrown from the endElement method

public abstract void pushContentHandler (ContentHandler contHandler)

This method shall be called from the content handler's startElelment method to attach another content handler to the xmlReader. It detaches the current content handler from the xmlReader and pushes it into the stack, then attaches the to the xmlReader.

Parameters
contHandler a new content handler
Throws
IllegalStateException if this method is called before the parse method was called.

public abstract void pushContentHandler (AbstractHandler contHandler)

This method shall be called from the content handler's startElelment method to attach another content handler to the xmlReader. It detaches the current content handler from the xmlReader and pushes it into the stack, then attaches the to the xmlReader. It also sets contHandler.parser attribute to this.

Parameters
contHandler a new content handler

public void putContextObject (String key, Object value)

public static void unexpectedElement (String tag, String parent)

Throws SAXSupportException exception with "Unexpected element" message

Parameters
tag tag name
parent parent tag name
Throws
SAXSupportException exception with "Unexpected element" message

public static void unexpectedEndDocument (Object handler)

Call this method to report unexpected end of document event. Normally it shall be used in the endDocument methods of inner event handlers.

Parameters
handler the handler that detected the error
Throws
IllegalStateException If the handler does not support endDocument() method.

public static void unexpectedEndElement (Object handler)

Call this method to report unexpected end of element event. Normally it shall be called from the endElement methods if the level count goes below zero.

Parameters
handler the handler that detected the error
Throws
IllegalStateException If the handler does not support endElement() method.