Package com.microstrategy.web.transform

Class MSTRLayoutParser

java.lang.Object

com.microstrategy.web.transform.MSTRLayoutParser

All Implemented Interfaces:

LayoutParser

Direct Known Subclasses:

AppLayoutParser

public class MSTRLayoutParser
extends java.lang.Object
implements LayoutParser

The MSTRLayoutParser class is default parser for all MicroStrategy-defined layout definitions. It provides many hooks for customization, for example:

• getContentHandler(java.lang.String) is used to retrieve a SAX ContentHandler for the layout XML. This needs to use MSTRLayoutParser.ParserContentHandler as the base class to enable the MSTRLayoutParser component to interact with the underlying SAX Parser.
• getEntityResolver(java.lang.String) is used to retrieve an EntityResolver object for the ContentHandler. It is used to locate any entities references in the layout XML document. The default implementation (MSTRLayoutParser.ParserEntityResolver) uses the entitySearchDir parameter of the parseLayout(java.lang.String, java.lang.String, com.microstrategy.web.transform.LayoutParser.MessageListener) method to reroute references to the XHTML 1.1 and MicroStrategy Layout DTDs to this directory.
• getErrorHandler(com.microstrategy.web.transform.LayoutParser.MessageListener, com.microstrategy.web.transform.MSTRLayoutParser.ParserContentHandler) is used to retrieve an ErrorHandler object for the ContentHandler. All warning and error messages are routed through this object. The default implementation (MSTRLayoutParser.ParserErrorHandler) routes these messages to a supplied LayoutParser.MessageListener object.

All of the object methods can be overriden to provide a different implementation. Furthermore, the steps of the parseLayout(java.lang.String, java.lang.String, com.microstrategy.web.transform.LayoutParser.MessageListener) method are themselves protected methods can be overriden.

Since:

MicroStrategy Web 8.0.0

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected static class	MSTRLayoutParser.ParserContentHandler	This is the default implementation of the ContentHandler to use parse the layout XML.
protected class	MSTRLayoutParser.ParserEntityResolver	This is the default implementation of the EntityResolver object.
protected static class	MSTRLayoutParser.ParserErrorHandler	This is the defualt implementation for the ErrorHandler object used with the SAX Parser.

Nested classes/interfaces inherited from interface com.microstrategy.web.transform.LayoutParser

LayoutParser.MessageListener

Constructor Summary

Constructors

Constructor	Description
MSTRLayoutParser()	Standard no-args constructor for the layout parser.
MSTRLayoutParser(boolean debug)	Special version of the Parser that can enable more diagnostic messages.

Method Summary

Modifier and Type	Method	Description
protected MSTRLayoutParser.ParserContentHandler	getContentHandler(java.lang.String layoutLocation)	Returns a MSTRLayoutParser.ParserContentHandler object which performs the actual parsing of the layout text.
java.lang.String	getDescription()	Gets the description of this layout parser object (to be read by someone wishing to use it).
protected java.io.InputStream	getEntityAsStream(java.lang.String entityId)	Returns an InputStream for the specified entity file name.
protected org.xml.sax.EntityResolver	getEntityResolver(java.lang.String entitySearchDir)	Returns an EntityResolver object used by the parser to resolve references to external DTDs.
protected org.xml.sax.ErrorHandler	getErrorHandler(LayoutParser.MessageListener listener, MSTRLayoutParser.ParserContentHandler pch)	Returns an ErrorHandler object used by the parser to route error and warning messages back to the caller.
protected org.xml.sax.InputSource	getInputSource(java.lang.String xmlText)	Returns an InputSource object for the supplied layout XML.
protected LayoutTag	loadDocument(org.xml.sax.InputSource inputSource, java.lang.String layoutLocation, java.lang.String entitySearchDir, LayoutParser.MessageListener listener)	This method performs the actual SAX parsing of the layout definition.
LayoutTag	parseLayout(java.lang.String layout, java.lang.String location, LayoutParser.MessageListener listener)	Deprecated. - use parseLayout(String layout, String location,LayoutSource layoutSource, MessageListener listener)
LayoutTag	parseLayout(java.lang.String layout, java.lang.String location, LayoutSource layoutSource, LayoutParser.MessageListener listener)	This method performs a parsing operation on a layout definition (supplied as a string).
protected void	performStaticSemanticChecks(LayoutTag layoutTag, LayoutParser.MessageListener listener)	Perform any additional static semantic analyses on the generated LayoutTag object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MSTRLayoutParser

public MSTRLayoutParser()

Standard no-args constructor for the layout parser.

MSTRLayoutParser

public MSTRLayoutParser(boolean debug)

Special version of the Parser that can enable more diagnostic messages.

Parameters:

debug - Whether to enable more diagnostic messages. If enabled, the messages are sent to System.err.

Method Detail

getDescription

public java.lang.String getDescription()

Gets the description of this layout parser object (to be read by someone wishing to use it). This description should include some reference to the type of special tags that understands.

Specified by:

getDescription in interface LayoutParser

Returns:

A textual description of this layout parser object.

parseLayout

@Deprecated
public LayoutTag parseLayout(java.lang.String layout,
                             java.lang.String location,
                             LayoutParser.MessageListener listener)
                      throws LayoutParsingException

Deprecated.

- use parseLayout(String layout, String location,LayoutSource layoutSource, MessageListener listener)

This method performs a parsing operation on a layout definition (supplied as a string). If the caller wants to be informed of warning and error conditions, he should create an instance of an object that implements the LayoutParser.MessageListener interface.

This particular implentation is broken up into three steps:

1. Create an InputSource object (see getInputSource(java.lang.String) using the supplied layout text.
2. Load the document into memory using the InputSource computed in the previous step. (See loadDocument(org.xml.sax.InputSource, java.lang.String, java.lang.String, com.microstrategy.web.transform.LayoutParser.MessageListener))
3. Perform any additional static semantic by calling performStaticSemanticChecks(com.microstrategy.web.tags.LayoutTag, com.microstrategy.web.transform.LayoutParser.MessageListener).

Any of these methods can be overridden in a subclass to modify the behavior of the parser.

Specified by:

parseLayout in interface LayoutParser

Parameters:

layout - The Layout Definition as a string.

location - The source location for this layout. It is only used for diagnostic purposes. If omitted, then no source location is mentioned any error or warning messages.

listener - An instance of a MessageListener object that the parser uses to indicate warning and error conditions.

Returns:

If successful, a LayoutTag that represents the Layout Definition in-memory.

Throws:

LayoutParsingException - If parsing fails (due to an error condition), this exception is raised.

parseLayout

public LayoutTag parseLayout(java.lang.String layout,
                             java.lang.String location,
                             LayoutSource layoutSource,
                             LayoutParser.MessageListener listener)
                      throws LayoutParsingException

This method performs a parsing operation on a layout definition (supplied as a string). If the caller wants to be informed of warning and error conditions, he should create an instance of an object that implements the LayoutParser.MessageListener interface.

This particular implentation is broken up into three steps:

1. Create an InputSource object (see getInputSource(java.lang.String) using the supplied layout text.
2. Load the document into memory using the InputSource computed in the previous step. (See loadDocument(org.xml.sax.InputSource, java.lang.String, java.lang.String, com.microstrategy.web.transform.LayoutParser.MessageListener))
3. Perform any additional static semantic by calling performStaticSemanticChecks(com.microstrategy.web.tags.LayoutTag, com.microstrategy.web.transform.LayoutParser.MessageListener).

Any of these methods can be overridden in a subclass to modify the behavior of the parser.

Specified by:

parseLayout in interface LayoutParser

Parameters:

layout - The Layout Definition as a string.

location - The source location for this layout. It is only used for diagnostic purposes. If omitted, then no source location is mentioned any error or warning messages.

layoutSource - The layout source is for loading the external file when IncludeTag is used

listener - An instance of a MessageListener object that the parser uses to indicate warning and error conditions.

Returns:

If successful, a LayoutTag that represents the Layout Definition in-memory.

Throws:

LayoutParsingException - If parsing fails (due to an error condition), this exception is raised.

Since:

MicroStrategy Web 8.0.2

getInputSource

protected org.xml.sax.InputSource getInputSource(java.lang.String xmlText)
                                          throws LayoutParsingException

Returns an InputSource object for the supplied layout XML.

Parameters:

xmlText - The layout definition to parse.

Returns:

An InputSource object which is used by the loadDocument(org.xml.sax.InputSource, java.lang.String, java.lang.String, com.microstrategy.web.transform.LayoutParser.MessageListener) method.

Throws:

LayoutParsingException

getEntityResolver

protected org.xml.sax.EntityResolver getEntityResolver(java.lang.String entitySearchDir)

Returns an EntityResolver object used by the parser to resolve references to external DTDs.

Parameters:

entitySearchDir - The location to use to search for all DTDs.

Returns:

An EntityResolver implementation that resolves the location of specific DTDs.

getErrorHandler

protected org.xml.sax.ErrorHandler getErrorHandler(LayoutParser.MessageListener listener,
                                                   MSTRLayoutParser.ParserContentHandler pch)

Returns an ErrorHandler object used by the parser to route error and warning messages back to the caller.

Parameters:

listener - An LayoutParser.MessageListener object to use.

pch - A reference to the MSTRLayoutParser.ParserContentHandler object instance.

Returns:

An ErrorHandler object which is used by the loadDocument(org.xml.sax.InputSource, java.lang.String, java.lang.String, com.microstrategy.web.transform.LayoutParser.MessageListener) method.

getContentHandler

protected MSTRLayoutParser.ParserContentHandler getContentHandler(java.lang.String layoutLocation)

Returns a MSTRLayoutParser.ParserContentHandler object which performs the actual parsing of the layout text.

Parameters:

layoutLocation - The location of the original layout definition. It is only used in diagnostic messages.

Returns:

A MSTRLayoutParser.ParserContentHandler object used by the loadDocument(org.xml.sax.InputSource, java.lang.String, java.lang.String, com.microstrategy.web.transform.LayoutParser.MessageListener) method.

loadDocument

protected LayoutTag loadDocument(org.xml.sax.InputSource inputSource,
                                 java.lang.String layoutLocation,
                                 java.lang.String entitySearchDir,
                                 LayoutParser.MessageListener listener)
                          throws LayoutParsingException

This method performs the actual SAX parsing of the layout definition.

Parameters:

inputSource - The InputSource object which contains a reference to the the layout defintion being parsed.

layoutLocation - The source location of the layout definition. It is used for generate meaningful error messages.

entitySearchDir - This is the directory where the Parser may find the referenced DTDs.

listener - This is an instance of LayoutParser.MessageListener object used to communicate warning and error messages back to the caller.

Returns:

The generated LayoutTag, if parsing was successful.

Throws:

LayoutParsingException - If parsing fails, this is thrown.

performStaticSemanticChecks

protected void performStaticSemanticChecks(LayoutTag layoutTag,
                                           LayoutParser.MessageListener listener)
                                    throws LayoutParsingException

Perform any additional static semantic analyses on the generated LayoutTag object. The current implementation does not perform any additional checks at this time.

Parameters:

layoutTag - The generated layout, in the form of a LayoutTag.

listener - The LayoutParser.MessageListener object to pass messages through.

Throws:

LayoutParsingException - An exception is through if any sematic checks fail.

getEntityAsStream

protected java.io.InputStream getEntityAsStream(java.lang.String entityId)
                                         throws java.io.IOException

Returns an InputStream for the specified entity file name.

Parameters:

entityId - The file name containing XML entities

Returns:

InputStream the input stream for reading the entity file, or null if the entity file can not be found.

Throws:

java.io.IOException - thrown if there is any error reading the entity file.