com.opmath.util.dmldoc
Class DMLDoc

java.lang.Object
  |
  +--com.opmath.util.dmldoc.DMLDocBlock
        |
        +--com.opmath.util.dmldoc.DMLDoc

public class DMLDoc

extends DMLDocBlock

The Document Object Model (DOM) for the template.

DMLDoc provides a simple, efficient and highly-functional method for generating dynamic Web pages, or other dynamic SGML documents. This enables a flexible approach to constructing Web sites using Java Servlets, Enterprise Java Beans, and any other appropriate Java technology. The approach is independent of the choice of Web server, Java applications server or server-side database.

DMLDoc provides the highest-level view of the com.opmath.util.dmldoc structures. This includes the DOM, together with a ComparableTable for holding tabluar data, known as the DMLDoc model.

Copyright: (c) 2002 The Open Math Company Limited

The Terms of Distribution of this software are stipulated in the javadoc Overview for this project.

Since:

J2SE 1.3

Version:

utilities-v011

Author:

Bruno Beloff bruno.beloff@opmath.com

See Also:

DMLDocBlock, DMLDocText

Field Summary

protected static String	CMD_ENDIF The String identifying the DMLDoc ENDIF command.
protected static String	CMD_ENDLOOP The String identifying the DMLDoc ENDLOOP command.
protected static String	CMD_IF The String identifying the DMLDoc IF command.
protected static String	CMD_IFDATA The String identifying the DMLDoc IFDATAFOR command.
protected static String	CMD_IFNODATA The String identifying the DMLDoc IFNODATAFOR command.
protected static String	CMD_IFNOT The String identifying the DMLDoc IFNOT command.
protected static String	CMD_LOOP The String identifying the DMLDoc LOOP command.
protected static String	CMD_SUB The String identifying the DMLDoc SUB command.
protected static String	DELIMITERS The delimiters used to identify the DMLDoc command tokens in the template source.
protected static String	EOL The end-of-line character or characters for the server operating system.
ComparableTable	model

Constructor Summary

DMLDoc(BufferedReader viewReader)
Constructs a DMLDoc for a given BufferedReader.

DMLDoc(InputStream viewStream)
Constructs a DMLDoc for a given InputStream.

DMLDoc(String viewPath, String viewFile)
Constructs a DMLDoc for the text found in the named file.

Method Summary

protected void	parse(BufferedReader viewReader) Constructs the DMLDocBlock according to the text supplied by the given BufferedReader.
String	toString() Returns a formatted string representaion of the DMLDocBlock instance.
String	view() Returns a String representaion of this DMLDoc instance, with the various SUBs, LOOPs and IF / IFNOT / IFDATAFOR / IFNODATAFOR elements processed, as determined by the contents of the model.
String	view(ComparableTable model) Returns a String representaion of the DMLDocBlock instance, with the various SUBs, LOOPs and IF / IFNOT / IFDATAFOR / IFNODATAFOR elements processed, as determined by the contents of the com.opmath.util.datastruct.ComparableTable.
protected String	view(ComparableTable model, int mode, int loopIndex) Returns a String representaion of the DMLDocBlock instance, with the various SUBs, LOOPs and IF / IFNOT / IFDATAFOR / IFNODATAFOR elements processed, as determined by the contents of the com.opmath.util.datastruct.ComparableTable.
ComparableList	viewNames() Returns a ComparableList containing one Object for each of the SUB and IF / IFNOT / IFDATAFOR / IFNODATAFOR source names found in the SGML template file.
protected ComparableList	viewNames(ComparableList sourceList) Updates the com.opmath.util.datastruct.ComparableList with one Object for each of the SUB and IF / IFNOT / IFDATAFOR / IFNODATAFOR sources found in the SGML template file (if any).
String	viewWithException(ComparableTable model) Returns a String representaion of the DMLDocBlock instance, with the various SUBs, LOOPs and IF / IFNOT / IFDATAFOR / IFNODATAFOR elements processed, as determined by the contents of the com.opmath.util.datastruct.ComparableTable.

Methods inherited from class java.lang.Object

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

Field Detail

model

public ComparableTable model

DELIMITERS

protected static final String DELIMITERS

The delimiters used to identify the DMLDoc command tokens in the template source. Used by the DMLDoc parser.

Set to "\t\n\r #/|%,.;:'?=&\"<>[]{}".

Since:

J2SE 1.3

See Also:

Constant Field Values

EOL

protected static final String EOL

The end-of-line character or characters for the server operating system. Used by the DMLDoc parser, instantiator, and exception reporting methods.

Set to System.getProperty("line.separator").

Since:

J2SE 1.3

CMD_SUB

protected static final String CMD_SUB

The String identifying the DMLDoc SUB command. Used by the parser. Note that this parser is not case-sensitive for these commands.

Set to "SUB".

Since:

J2SE 1.3

See Also:

Constant Field Values

CMD_IF

protected static final String CMD_IF

The String identifying the DMLDoc IF command. Used by the parser. Note that this parser is not case-sensitive for these commands.

Set to "IF".

Since:

J2SE 1.3

See Also:

Constant Field Values

CMD_IFNOT

protected static final String CMD_IFNOT

The String identifying the DMLDoc IFNOT command. Used by the parser. Note that this parser is not case-sensitive for these commands.

Set to "IFNOT".

Since:

J2SE 1.3

See Also:

Constant Field Values

CMD_IFDATA

protected static final String CMD_IFDATA

The String identifying the DMLDoc IFDATAFOR command. Used by the parser. Note that this parser is not case-sensitive for these commands.

Set to "IFDATAFOR".

Since:

J2SE 1.3

See Also:

Constant Field Values

CMD_IFNODATA

protected static final String CMD_IFNODATA

The String identifying the DMLDoc IFNODATAFOR command. Used by the parser. Note that this parser is not case-sensitive for these commands.

Set to "IFNODATAFOR".

Since:

J2SE 1.3

See Also:

Constant Field Values

CMD_ENDIF

protected static final String CMD_ENDIF

The String identifying the DMLDoc ENDIF command. Used by the parser. Note that this parser is not case-sensitive for these commands.

Set to "ENDIF".

Since:

J2SE 1.3

See Also:

Constant Field Values

CMD_LOOP

protected static final String CMD_LOOP

The String identifying the DMLDoc LOOP command. Used by the parser. Note that this parser is not case-sensitive for these commands.

Set to "LOOP".

Since:

J2SE 1.3

See Also:

Constant Field Values

CMD_ENDLOOP

protected static final String CMD_ENDLOOP

The String identifying the DMLDoc ENDLOOP command. Used by the parser. Note that this parser is not case-sensitive for these commands.

Set to "ENDLOOP".

Since:

J2SE 1.3

See Also:

Constant Field Values

Constructor Detail

DMLDoc

public DMLDoc(BufferedReader viewReader)
       throws DMLDocBuildException

Constructs a DMLDoc for a given BufferedReader.

It is anticipated that DMLDoc(String, String) will be the most common way in which DMLDoc instances are created.

Throws:

DMLDocBuildException - An exception thrown if the template text contained ill-formed commands.

Since:

J2SE 1.3

See Also:

DMLDoc(String, String)

DMLDoc

public DMLDoc(InputStream viewStream)
       throws DMLDocBuildException

Constructs a DMLDoc for a given InputStream.

It is anticipated that DMLDoc(String, String) will be the most common way in which DMLDoc instances are created.

Throws:

DMLDocBuildException - An exception thrown if the template text contained ill-formed commands.

Since:

J2SE 1.3

See Also:

DMLDoc(String, String)

DMLDoc

public DMLDoc(String viewPath,
              String viewFile)
       throws DMLDocBuildException

Constructs a DMLDoc for the text found in the named file. This node will be the root of a new DMLDoc.

It is anticipated that this will be the most common way in which DMLDoc instances are created.

Throws:

DMLDocBuildException - an exception thrown if the template file was missing or contained ill-formed commands.

Since:

J2SE 1.3

Method Detail

view

public String view()

Returns a String representaion of this DMLDoc instance, with the various SUBs, LOOPs and IF / IFNOT / IFDATAFOR / IFNODATAFOR elements processed, as determined by the contents of the model.

If the model is malformed, view() attempts to return a String containing an SGML-formatted report detailing the cause of the problem. The template resource for this report is held at com.opmath.util.dmldoc.tpl_DMLDocWriteException.html. This template may be edited, but all of its SUB .. commands should remain unaltered.

NOTE: If com.opmath.util.dmldoc.tpl_DMLDocWriteException.html is not found, or is malformed, then view() reports to System.err and returns an empty String.

Returns:

a new String containing the instantiated SGML template.

Since:

J2SE 1.3

viewNames

protected ComparableList viewNames(ComparableList sourceList)

Updates the com.opmath.util.datastruct.ComparableList with one Object for each of the SUB and IF / IFNOT / IFDATAFOR / IFNODATAFOR sources found in the SGML template file (if any).

It is anticipated that the alternative method - viewNames() - will be the normal way in which DMLDocBlock view sources are found.

Parameters:

sourceList - the ComparableList for the SUB and IF / IFNOT / IFDATAFOR / IFNODATAFOR source names.

Returns:

a ComparableList of source names.

Since:

J2SE 1.3

See Also:

DMLDocBlock.viewNames(com.opmath.util.datastruct.ComparableList), DMLDocText.viewNames(com.opmath.util.datastruct.ComparableList)

viewNames

public ComparableList viewNames()

Returns a ComparableList containing one Object for each of the SUB and IF / IFNOT / IFDATAFOR / IFNODATAFOR source names found in the SGML template file.

If no substitution sources were found, viewNames() returns a ComparableList with zero elements.

Returns:

a ComparableList of source names.

Since:

J2SE 1.3

parse

protected void parse(BufferedReader viewReader)
              throws DMLDocBuildException

Constructs the DMLDocBlock according to the text supplied by the given BufferedReader. If the source text contains malformed commands, parse(BufferedReader) throws a DMLDocBuildException.

Parameters:

viewReader - a BufferedReader carrying the source text.

Returns:

a ComparableList of source names.

Throws:

DMLDocBuildException - An exception thrown if the source text contained malformed commands.

Since:

J2SE 1.3

view

protected String view(ComparableTable model,
                      int mode,
                      int loopIndex)
               throws DMLDocWriteException

Returns a String representaion of the DMLDocBlock instance, with the various SUBs, LOOPs and IF / IFNOT / IFDATAFOR / IFNODATAFOR elements processed, as determined by the contents of the com.opmath.util.datastruct.ComparableTable.

NOTE: This is a highly specialzed method, only called during recursive decents into the DOM.

Parameters:

model - the com.opmath.util.datastruct.ComparableTable representing the data set.

mode - the int representing the function of this DMLDocBlock.

loopIndex - the int representing the current row in the model.

Returns:

a new String containing the instantiated DMLDocBlock.

Throws:

DMLDocWriteException - An exception thrown if the com.opmath.util.datastruct.ComparableTable was malformed.

Since:

J2SE 1.3

See Also:

DMLDocBlock.view(com.opmath.util.datastruct.ComparableTable)

viewWithException

public String viewWithException(ComparableTable model)
                         throws DMLDocWriteException

Returns a String representaion of the DMLDocBlock instance, with the various SUBs, LOOPs and IF / IFNOT / IFDATAFOR / IFNODATAFOR elements processed, as determined by the contents of the com.opmath.util.datastruct.ComparableTable.

If the com.opmath.util.datastruct.ComparableTable is malformed, viewWithException(com.opmath.util.datastruct.ComparableTable) raises a DMLDocWriteException exception.

Parameters:

model - the com.opmath.util.datastruct.ComparableTable representing the data set.

Returns:

a new String containing the instantiated DMLDocBlock.

Throws:

DMLDocWriteException - An exception thrown if the com.opmath.util.datastruct.ComparableTable was malformed.

Since:

J2SE 1.3

See Also:

DMLDocBlock.view(com.opmath.util.datastruct.ComparableTable)

view

public String view(ComparableTable model)

Returns a String representaion of the DMLDocBlock instance, with the various SUBs, LOOPs and IF / IFNOT / IFDATAFOR / IFNODATAFOR elements processed, as determined by the contents of the com.opmath.util.datastruct.ComparableTable.

If the com.opmath.util.datastruct.ComparableTable is malformed, view(com.opmath.util.datastruct.ComparableTable) attempts to return a String containing an SGML-formatted report detailing the cause of the problem. The template resource for this report is held at com.opmath.util.dmldoc.tpl_DMLDocWriteException.html This template may be edited, but all of its <!-- SUB .. --> commands should remain unaltered.

NOTE: If com.opmath.util.dmldoc.tpl_DMLDocWriteException.html is not found, or is malformed, then view(com.opmath.util.datastruct.ComparableTable) reports to System.err and returns an empty String.

Parameters:

model - the com.opmath.util.datastruct.ComparableTable representing the data set.

Returns:

a new String containing the instantiated SGML template.

Since:

J2SE 1.3

toString

public String toString()

Returns a formatted string representaion of the DMLDocBlock instance. No instantiation is performed, but the structure of the DMLDocBlockinstance is revealed.

NOTE: Intended to be used for debugging tasks only. The format of the output may change from one release of dmldoc to the next.

Overrides:

toString in class Object

Returns:

a new String

Since:

J2SE 1.3

See Also:

DMLDocBlock.view(com.opmath.util.datastruct.ComparableTable)