cb.jdynamite

Class JDynamiTe

java.lang.Object

cb.jdynamite.analyser.DefaultDynamicElement

cb.jdynamite.JDynamiTe

All Implemented Interfaces:

cb.jdynamite.analyser.IDynamicElement, cb.jdynamite.analyser.ITemplateElement, ITemplateDocument, java.io.Serializable

public class JDynamiTe
extends cb.jdynamite.analyser.DefaultDynamicElement
implements ITemplateDocument, java.io.Serializable

JDynamiTe is the unique class that you need in order to parse a template document, populate it and finally produce an output document.
It is very simple to use:
- First define the input file or input stream (for example an HTML template document) with the "setInput" method.
- Secondly fill and develop this document with a few methods such as "setVariable", and "parseDynElem".
- Finally, after calling the "parse" method to finalize building your dynamic document, you simply obtain the result with the "toString" method.

There are several examples available from JDynamiTe Project Home page.

JDynamiTe elements

There are (only) five types of JDynamiTe elements. Inserted into a document, they make it a "template" document.

1) "Variable Element"
A "Variable Element" is defined by an identifier in the template document. It is a simple variable, whose value can be changed with the setVariable(String, String) method.
In the generated output document, a Variable element is replaced by its value.
Example of use: titles, values of cells in tables, etc.

2) "Dynamic Element"
A "Dynamic Element" is a "block" which can be dynamically developed. It has an identifier, a template definition, and a current value. Its value can be set or developed with the parseDynElem(String) and setDynElemValue(String, String) methods.
Example of use: list, table, enumeration, etc.

3) "XML Dynamic Element"
Since JDynamiTe 2.0, there is a new kind of Dynamic Element: "XML Dynamic Element" allows to automatically populate the template taking input from XML files (see setXMLInput(String, String)). It uses standard XPath syntax, which refers to data (XML nodes) contained in an external XML file. By this way, no need to programmatically populate this block of data: JDynamiTe parser automatically does it for you (see parseXMLDynElem(String, boolean) or parseXMLDynElem()).
Several examples available in JDynamiTe Project Examples Home page.

4) "XML Variable Element"
An "XML Variable Element" is a simple variable in the current "XML Dynamic Element" context (i.e. relative to current XML node).
It can be an attribute node or a text node
In the generated output document, an XML Variable element is replaced by its value in its context.

5) "Ignored Element"
Since JDynamiTe 1.1, this optional element can be used in template documents. An "Ignored Element" is a "block" which will be completely ignored (skipped during document analysis).
Example of use: it allows the HTML designer to build more realistic pages, with concrete data, giving a better idea of the possible dynamic page look and feel. An "Ignored Element" can be inserted anywhere in the template document, even inside "Dynamic Element".

Template document syntax

Special tags allow to declare JDynamiTe elements (described above) in a template.
Technically, tag syntax is defined by regular expressions (which can be customized if needed, using DefaultAnalyser class methods). The default syntax is suitable for most usages.
Below is a simplified (more readable than full regular expressions) definition of these tags.
Note that the best way to learn how to insert JDynamiTe tags in a template document is probably to look at the "JDynamiTe QuickStart example", which is the first (and simple) example provided in JDynamiTe Project Home page (follow "JDynamiTe Examples Overview", the input template file is "testTemplateV2_0.html").

1) "Variable" tag

{VARNAME}

Defines VARNAME as a Variable Element.
Note that you can use several times {VARNAME} in your template.


2) "Begin Dynamic Element" tag

<!-- BEGIN DYNAMIC : blockName -->

Defines blockName as a Dynamic Element.
Its definition begins at the next line of the template.
Note that Dynamic Elements can be nested.


3) "Begin XML Dynamic Element" tag

<!-- BEGIN XML DYNAMIC : blockName [URI|filename] XPathExpression -->

Defines blockName as an XML Dynamic Element.
Its definition begins at the next line of the template.
If URI or filename is specified, this "URI" or "filename" is read and XML data are extracted from it.
Otherwise, XML data are extracted from parent XML Dynamic Element context (XML Dynamic Elements can be nested).

"XPathExpression" is an "XPath compliant" expression which selects the current context (current XML node).
It can be an "absolute" XML path (beginning with '/') or a relative XML path (it is relative to the current context).
See the Javadoc documentation of Package "javax.xml.xpath" or visit "http://www.w3.org/TR/xpath" for details and examples about XPath expressions.

As said above, there are several examples of "XML Dynamic Element" usage in "JDynamiTe Examples Overview" pages.


4) "XML Variable" tag

There are two kinds of "XML Variables". Both are enclosed by double braces:

1. Attribute



{{[RelativeXPath/]@NODE_ATTRIBUTE_NAME}}

If RelativeXPath/ is not specified, selects the attribute NODE_ATTRIBUTE_NAME of the current XML Dynamic Element (current XML node).
If RelativeXPath/ is specified, selects the attribute NODE_ATTRIBUTE_NAME of the current XML Dynamic Element child node, defined by the path RelativeXPath/.


2. Text

{{[RelativeXPath/]text()}}

If RelativeXPath/ is not specified, selects the "text" part of the current XML Dynamic Element (current XML node).
If RelativeXPath/ is specified, selects the "text" part of the current XML Dynamic Element child node, defined by the path RelativeXPath/.

5) "End Dynamic Element" tag

<-- END DYNAMIC : blockName -->

means that the Dynamic Element or XML Dynamic Element definition of "blockName" ends on the previous line.


6) "Ignored Element" tags

<!-- BEGIN IGNORED : blockName -->

means that an ignored block (skipped during analysis and document output) begins on the next line.

<!-- END IGNORED : blockName -->

means that this ignored block ends on the previous line.


7) Identifiers syntax (for Variable name and Dynamic Element name)
By default, it is a word made up of alphanumeric characters and these four characters: '.', ':', '_' and '-'

JDynamiTe home page

JDynamiTe latest versions, news, examples ... at http://jdynamite.sourceforge.net

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	INPUT_TEMPLATE_ERROR_TAG Special variable tag, {__LAST_JDYN_ERROR__}, that you can use in your template, and which is automatically populated by JDynamiTe, after parsing Dynamic Elements, with the last error message (it is empty if no error occurred).

Constructor Summary

Constructors

Constructor and Description
JDynamiTe() Constructs an empty "JDynamiTe" (Java Dynamic Template) document.
JDynamiTe(java.lang.String name) Constructs an empty "JDynamiTe" (Java Dynamic Template) document.

Method Summary

Methods

Modifier and Type	Method and Description
cb.jdynamite.analyser.ITemplateAnalyser	getAnalyser() Returns the analyser that parses template documents (Note: You do not need to directly call this method to use JDynamiTe).
cb.jdynamite.analyser.IDynamicElement	getDynElem(java.lang.String key) Returns the "Dynamic Element" identified by a string (note: you do not need to directly call this method to use JDynamiTe).
java.util.Enumeration<java.lang.String>	getDynElemenKeys() Returns an enumeration of the Dynamic Element keys (identifiers) in this JDynamiTe document.
java.lang.String	getLastError() Returns error message, possibly set after parsing Dynamic Elements.
java.lang.String	getTemplateDefinition() For debugging purposes: get the result (structure of the template document) of the analyser parsing.
java.lang.String	getVariable(java.lang.String key) Returns the value of a variable that was set by setVariable.
java.util.Enumeration<java.lang.String>	getVariableKeys() Returns an enumeration of the Variable keys (identifiers) in this JDynamiTe document.
java.lang.String	getXMLVariable(java.lang.String xmlDynElemName, java.lang.String xmlVarName) Returns the value of an XML Variable in its in current "XML Dynamic Element" context.
boolean	hasXMLElement(java.lang.String dynElemName) Determines if an XML Dynamic Element has still XML nodes to parse.
boolean	isXMLDynElement(java.lang.String dynElemName) Determines if a Dynamic Element is an XML Dynamic Element.
void	parse() Calls the parse method inherited from DefaultDynamicElement.
void	parseDynElem(java.lang.String elementName) This is a "key" method you call to append elements to the current value of a Dynamic Element.
void	parseXMLDynElem() Parses recursively all "first level" XML Dynamic Elements.
void	parseXMLDynElem(java.lang.String elementName, boolean recurse) Parses an XML Dynamic Element.
void	recordDynElem(java.lang.String key, cb.jdynamite.analyser.IDynamicElement value) Records a "Dynamic Element" in this "JDynamiTe" Document (Note: You do not need to directly call this method to use JDynamiTe).
void	resetAll() Resets all Variables to empty string and all Dynamic Element values to null.
void	resetAllDynElemValues() Resets all Dynamic Element values to null.
void	resetAllVariables() Resets all Variables values to empty String.
void	resetExternalXMLDocuments() Clears XML external Documents shared list.
void	setAnalyser(cb.jdynamite.analyser.ITemplateAnalyser templateAnalyser) Sets the analyser that parses template documents (Note: You do not need to directly call this method to use JDynamiTe).
void	setDynElemValue(java.lang.String elementName, java.lang.String value) Sets an arbitrary value to a Dynamic Element.
void	setExternalXMLDocumentsCacheMaxSize(int cacheMaxSize) Sets XML external Documents shared list maximum size.
void	setInput(java.io.BufferedReader reader) Starts the analysis of the input template document.
void	setInput(java.io.InputStream istream) Starts the analysis of the input template document.
void	setInput(java.lang.String fileName) Starts the analysis of the input template document.
void	setLastError(java.lang.String lastError) Internal JDynamiTe method used to set error message, after parsing Dynamic Elements.
void	setVariable(java.lang.String key, java.lang.String value) Sets the value of a variable.
static void	setVerbose(boolean isVerbose)
void	setXMLInput(java.lang.String xmlDynElemName, java.lang.String value_URI) Sets or replaces XML input path (URI or filename) of an XML Dynamic Element.
void	setXMLXPathExpression(java.lang.String xmlDynElemName, java.lang.String xPathExpr) Replaces XML XPath expression of an XML Dynamic Element.
java.lang.String	toString() Returns the value (after parsing) of this JDynamiTe document.

Methods inherited from class cb.jdynamite.analyser.DefaultDynamicElement

addElement, getDefinition, getFatherDynElem, getName, getValue, getXMLCurrentNode, getXMLInput, getXMLValue, getXMLXPathExpression, hasXMLElement, isXMLDynElement, parse, parseXML, resetDefinition, setValue, setXMLInput, setXMLXPathExpression

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

INPUT_TEMPLATE_ERROR_TAG

public static final java.lang.String INPUT_TEMPLATE_ERROR_TAG

Special variable tag, {__LAST_JDYN_ERROR__}, that you can use in your template, and which is automatically populated by JDynamiTe, after parsing Dynamic Elements, with the last error message (it is empty if no error occurred). Errors can typically happen when an external XML input document can not be open.

See Also:

getLastError(), Constant Field Values

Constructor Detail

JDynamiTe

public JDynamiTe()

Constructs an empty "JDynamiTe" (Java Dynamic Template) document.

JDynamiTe

public JDynamiTe(java.lang.String name)

Constructs an empty "JDynamiTe" (Java Dynamic Template) document.

Parameters:

name - The name of this "JDynamiTe" document, used for debugging purposes by the "getTemplateDefinition" method.

Method Detail

setInput

public void setInput(java.io.BufferedReader reader)
              throws java.io.IOException

Starts the analysis of the input template document. If no custom "ITemplateAnalyser" was defined, JDynamiTe uses the "DefaultAnalyser". After this step, all the Variables and Dynamic Elements are identified, so this JDynamiTe is ready to be developed. By default all Variables are set to an empty string value. In addition, Variable identifiers (keys) can be retrieved by getVariablesKeys.

Parameters:

reader - A BufferedReader to read the input template document.

Throws:

java.io.IOException - If an I/O error occurs.

Since:

JDynamyTe 1.2

See Also:

setInput(java.io.InputStream), setInput(java.lang.String), DefaultAnalyser, setAnalyser(ITemplateAnalyser templateAnalyser)

setInput

public void setInput(java.io.InputStream istream)
              throws java.io.IOException

Starts the analysis of the input template document. If no custom "ITemplateAnalyser" was defined, JDynamiTe uses the "DefaultAnalyser". After this step, all the Variables and Dynamic Elements are identified, so this JDynamiTe is ready to be developed. By default all Variables are set to an empty string value. In addition, Variable identifiers (keys) can be retrieved by getVariablesKeys.

Parameters:

istream - A stream to read the input template document.

Throws:

java.io.IOException - If an I/O error occurs.

See Also:

setInput(java.io.BufferedReader), setInput(java.lang.String), DefaultAnalyser, setAnalyser(ITemplateAnalyser templateAnalyser)

setInput

public void setInput(java.lang.String fileName)
              throws java.io.IOException,
                     java.io.FileNotFoundException

Starts the analysis of the input template document. If no custom "ITemplateAnalyser" was defined, JDynamiTe uses the "DefaultAnalyser". After this step, all the Variables and Dynamic Elements are identified, so this JDynamiTe is ready to be developed. By default all Variables are set to an empty string value. In addition, Variable identifiers (keys) can be retrieved by getVariablesKeys.

Parameters:

fileName - The name of the file which contains the input template document.

Throws:

java.io.IOException - If an I/O error occurs.

java.io.FileNotFoundException - Bad filename.

See Also:

setInput(java.io.BufferedReader), setInput(java.io.InputStream), DefaultAnalyser, setAnalyser(ITemplateAnalyser templateAnalyser)

getVariable

public java.lang.String getVariable(java.lang.String key)

Returns the value of a variable that was set by setVariable. A "JDynamiTe" document maintains a list of key/value pairs, which is used when Dynamic Elements are parsed.

Specified by:

getVariable in interface ITemplateDocument

Parameters:

key - The key (identifier) of the variable to retrieve.

Returns:

The value of the variable, or null if this variable does not exist.

See Also:

setVariable(java.lang.String, java.lang.String)

setVariable

public void setVariable(java.lang.String key,
               java.lang.String value)

Sets the value of a variable. Overrides its previous value if any. A "JDynamiTe" document maintains a list of key/value pairs, which is used when Dynamic Elements are parsed.

Specified by:

setVariable in interface ITemplateDocument

Parameters:

key - The key (identifier) of the variable to set.

value - The new value of this variable.

See Also:

getVariable(java.lang.String)

getVariableKeys

public java.util.Enumeration<java.lang.String> getVariableKeys()

Returns an enumeration of the Variable keys (identifiers) in this JDynamiTe document. A "JDynamiTe" document maintains a list of key/value pairs, which is used when Dynamic Elements are parsed. The setInput method builds this list (with an empty string as default value) during the template document analysis. After this step, the setVariable method is used to set a value to a Variable. Example of use:

 Enumeration keys = getVariableKeys();
 while (keys.hasMoreElements()) {
    String key = keys.nextElement();
    System.err.println(keys);
    String value = myDatabase.selectValue(key); // get the current value somewhere...
    myJDynamiTeDoc.setVariable(key, value); // set the template Variable.
 }
 

Returns:

Enumeration of the Variable keys.

Since:

JDynamiTe 1.2

See Also:

setVariable(java.lang.String, java.lang.String), setInput(InputStream istream), setInput(String fileName)

getDynElem

public cb.jdynamite.analyser.IDynamicElement getDynElem(java.lang.String key)

Returns the "Dynamic Element" identified by a string (note: you do not need to directly call this method to use JDynamiTe). A "JDynamiTe" document maintains a list of "Dynamic Elements".

Parameters:

key - The "Dynamic Element" identifier. This is the string defined in the template document in the "BEGIN DYNAMIC" tag. For example:

<-- BEGIN DYNAMIC : myList -->

Here "myList" identifies the Dynamic Element which begins.

Returns:

The interface of the Dynamic Element.

getDynElemenKeys

public java.util.Enumeration<java.lang.String> getDynElemenKeys()

Returns an enumeration of the Dynamic Element keys (identifiers) in this JDynamiTe document.

Returns:

Enumeration of the Dynamic Element keys.

Since:

JDynamiTe 1.2

See Also:

setDynElemValue(String, String), parseDynElem(String), parseXMLDynElem(String, boolean), parseXMLDynElem()

hasXMLElement

public boolean hasXMLElement(java.lang.String dynElemName)

Determines if an XML Dynamic Element has still XML nodes to parse.
See JDynamiTe elements and Template document syntax sections.

Parameters:

dynElemName - "XML Dynamic Element" identifier.

Returns:

false when all XML nodes of "dynElemName" have been parsed. Returns true otherwise.

See Also:

isXMLDynElement(String)

isXMLDynElement

public boolean isXMLDynElement(java.lang.String dynElemName)

Determines if a Dynamic Element is an XML Dynamic Element. Some "XML" methods can be called on XML Dynamic Elements.
See JDynamiTe elements and Template document syntax sections.

Parameters:

dynElemName - Dynamic Element identifier

Returns:

true if dynElemName is the identifier of an XML Dynamic Element. Returns false otherwise.

See Also:

hasXMLElement(String), setXMLInput(String, String), getXMLVariable(String, String), setXMLXPathExpression(String, String)

setXMLInput

public void setXMLInput(java.lang.String xmlDynElemName,
               java.lang.String value_URI)

Sets or replaces XML input path (URI or filename) of an XML Dynamic Element. Useful for example when an XML input path (in "Begin XML Dynamic Element" tag) is not defined in the parsed template file. Does nothing on non XML Dynamic Elements.
See JDynamiTe elements and Template document syntax sections.

Parameters:

xmlDynElemName - "XML Dynamic Element" identifier.

value_URI - new path

See Also:

isXMLDynElement(String)

setXMLXPathExpression

public void setXMLXPathExpression(java.lang.String xmlDynElemName,
                         java.lang.String xPathExpr)

Replaces XML XPath expression of an XML Dynamic Element. Useful to programmatically set the XML XPath expression (whose initial value is defined in "Begin XML Dynamic Element" tag of the template file).
Does nothing on non XML Dynamic Elements.
See JDynamiTe elements and Template document syntax sections.

Parameters:

xmlDynElemName - "XML Dynamic Element" identifier.

xPathExpr - new XML XPath expression

See Also:

isXMLDynElement(String)

getXMLVariable

public java.lang.String getXMLVariable(java.lang.String xmlDynElemName,
                              java.lang.String xmlVarName)

Returns the value of an XML Variable in its in current "XML Dynamic Element" context. It can be an attribute node or a text node (XML Variables are enclosed by double braces in "XML Variable" tag).
See JDynamiTe elements and Template document syntax sections.
Does nothing on non XML Dynamic Elements.

Parameters:

xmlDynElemName -

xmlVarName -

Returns:

Value of xmlVarName in its in current "XML Dynamic Element" context

See Also:

isXMLDynElement(String)

recordDynElem

public void recordDynElem(java.lang.String key,
                 cb.jdynamite.analyser.IDynamicElement value)

Records a "Dynamic Element" in this "JDynamiTe" Document (Note: You do not need to directly call this method to use JDynamiTe). A "JDynamiTe" document maintains a list of "Dynamic Elements". It is called by the analyser. (all Dynamic Elements are put in the same list, so they must have a unique identifier).

Specified by:

recordDynElem in interface ITemplateDocument

Parameters:

key - The "Dynamic Element" identifier.

value - An object that implements the IDynamicElement interface.

getAnalyser

public cb.jdynamite.analyser.ITemplateAnalyser getAnalyser()

Returns the analyser that parses template documents (Note: You do not need to directly call this method to use JDynamiTe).

Specified by:

getAnalyser in interface ITemplateDocument

Returns:

The current analyser.

See Also:

setAnalyser(cb.jdynamite.analyser.ITemplateAnalyser)

setAnalyser

public void setAnalyser(cb.jdynamite.analyser.ITemplateAnalyser templateAnalyser)

Sets the analyser that parses template documents (Note: You do not need to directly call this method to use JDynamiTe).

Specified by:

setAnalyser in interface ITemplateDocument

Parameters:

templateAnalyser - The new analyser.

See Also:

getAnalyser()

parseDynElem

public void parseDynElem(java.lang.String elementName)

This is a "key" method you call to append elements to the current value of a Dynamic Element. These elements are built from the template definition of this Dynamic Element and the current value of variables (and possibly nested Dynamic Elements). See examples.
See also JDynamiTe elements and Template document syntax sections.

Parameters:

elementName - The "Dynamic Element" identifier. This is the string defined in the template document in the "BEGIN DYNAMIC" tag. For example:

 <-- BEGIN DYNAMIC : myList -->
 

Here "myList" identifies the Dynamic Element that begins.

parseXMLDynElem

public void parseXMLDynElem(java.lang.String elementName,
                   boolean recurse)

Parses an XML Dynamic Element.
It means that this XML Dynamic Element will be parsed using its XML input (URI or filename) and its XPath expression.
See JDynamiTe elements and Template document syntax sections.

Parameters:

elementName - "XML Dynamic Element" identifier.

recurse - If true, this XML Dynamic Element will be recursively parsed (if it contains nested XML Elements).

parseXMLDynElem

public void parseXMLDynElem()

Parses recursively all "first level" XML Dynamic Elements.
It means that all XML Dynamic Elements defined in the template document will be parsed, using their XML input (URI or filename) and their XPath expression.
See JDynamiTe elements and Template document syntax sections.

setVerbose

public static void setVerbose(boolean isVerbose)

setDynElemValue

public void setDynElemValue(java.lang.String elementName,
                   java.lang.String value)

Sets an arbitrary value to a Dynamic Element. For example, enables emptying a Dynamic Element if you give an empty string as argument.

Parameters:

elementName - The Dynamic Element identifier.

value - New value for The Dynamic Element

parse

public void parse()

Calls the parse method inherited from DefaultDynamicElement. As this object is the "top level" dynamic element, this method enables obtaining the "final" value of this document. You can use the "toString" method to get this value.

See Also:

toString()

setLastError

public void setLastError(java.lang.String lastError)

Internal JDynamiTe method used to set error message, after parsing Dynamic Elements. You do not have to use this method, which is internally called by Dynamic Elements. Note that this method also sets the "INPUT_TEMPLATE_ERROR_TAG" special TAG.

Specified by:

setLastError in interface ITemplateDocument

See Also:

getLastError(), INPUT_TEMPLATE_ERROR_TAG

getLastError

public java.lang.String getLastError()

Returns error message, possibly set after parsing Dynamic Elements. Note that the "INPUT_TEMPLATE_ERROR_TAG" special TAG also contains this error message.

Specified by:

getLastError in interface ITemplateDocument

Returns:

lastError Last error message, null if no error occurred.

See Also:

INPUT_TEMPLATE_ERROR_TAG

toString

public java.lang.String toString()

Returns the value (after parsing) of this JDynamiTe document.

Overrides:

toString in class java.lang.Object

Returns:

Value (after parsing) of this JDynamiTe document

getTemplateDefinition

public java.lang.String getTemplateDefinition()

For debugging purposes: get the result (structure of the template document) of the analyser parsing.

Returns:

Result (structure of the template document) of the analyser parsing.

resetAll

public void resetAll()

Resets all Variables to empty string and all Dynamic Element values to null.

See Also:

resetAllVariables(), resetAllDynElemValues()

resetAllVariables

public void resetAllVariables()

Resets all Variables values to empty String.

resetAllDynElemValues

public void resetAllDynElemValues()

Resets all Dynamic Element values to null.

resetExternalXMLDocuments

public void resetExternalXMLDocuments()

Clears XML external Documents shared list. These input documents are attached to XML Dynamic Elements. JDynamiTe manages this global "cache" list of already loaded Documents, in order to optimize performances.

See Also:

setExternalXMLDocumentsCacheMaxSize(int)

setExternalXMLDocumentsCacheMaxSize

public void setExternalXMLDocumentsCacheMaxSize(int cacheMaxSize)

Sets XML external Documents shared list maximum size. JDynamiTe manages this global "cache" list of already loaded Documents, in order to optimize performances. The default value of list maximum size is 10.

Parameters:

cacheMaxSize - New value of list maximum size (must be > 0).

See Also:

resetExternalXMLDocuments()