com.oopreserch.web
Class Form

java.lang.Object
  |
  +--com.oopreserch.web.Form

public final class Form

extends java.lang.Object

Insert the arbitrary Strings into the code fragments and merge them all.

Each code fragment can be written within the child elements of tag element in the XML. Then, you can insert the arbitrary String between the code fragments. By d.value element in the XML, you can specify where to insert the String.

For example, to insert Hello between the 2 code fragments in the above XML, your Servlet can call:

• setDefaultValue("item","Hello")

on the instance of this class. Then, the concatenated HTML tags can be retrieved by:

• getMerged( )

on the instance of this class. As you easily guess, the returned value will be:

• <ul><li>Hello</li></ul>

in this example.

The XML must comply with:

• form_gen_2_0.dtd

. This DTD is abstract enough to store the code fragments for any type of mark up language, such as HTML, XHTML, HDML, WML and SVG. For details about this class and the DTD, please read the article on the web site of OOP-Reserch at the URL of:

• http://www.oop-reserch.com/formgenerator_1_1.html

We will update this article frequently, and we are planing to publish many source code of examples. So, please visit the above URL periodically.

The instance of this class is created and pooled by:

• FormGenerator

All you have to do is to call one of:

• FormGenerator.getForm(String)
• FormGenerator.getForm(String,Locale)

After you finish working with the instance of this class, please push it back to the pool just by:

• FormGenerator.reuseForm(Form)

Creating and pooling the instances of Form This mechanism ensures that the same XML file will never be parsed more than once, which results in the significant performance improvement. And we can easily get the instance of Form through FormGenerator again and again.

Author:

Jun Inamori

Method Summary

void	clear() Set all the values to the empty String and their validity to true.
java.lang.String	getCharacterEncoding() Returns the character encoding of the original XML.
java.lang.String	getContentType() Returns the content-type specified by content.type element in the XML.
java.lang.String	getHTML() Deprecated.
java.lang.String	getMerged() Merge the inserted Strings into the code fragments and return the concatenated Strings.
boolean	isAllValid() Return true if all the Strings are valid.
void	setDefaultValidValue(java.util.Map map) Insert a set of Strings into the code fragments at a time.
void	setDefaultValue(java.util.Map map) Insert a set of Strings into the code fragments at a time.
void	setDefaultValue(java.lang.String key, java.lang.String value) Insert the arbitrary String between the code fragments.
void	setDefaultValue(java.lang.String key, java.lang.String value, boolean isValid) Insert the arbitrary String between the code fragments.
void	setRequest(com.oopreserch.web.HttpServletRequest req) Insert a set of request parameters into the code fragments at a time.
void	setValid(java.lang.String key, boolean isValid) Set explicitly the validity of the String to be inserted.
void	setValidRequest(com.oopreserch.web.HttpServletRequest req) Insert a set of request parameters into the code fragments at a time.

Methods inherited from class java.lang.Object

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

Method Detail

getContentType

public java.lang.String getContentType()

Returns the content-type specified by content.type element in the XML.

If content.type element may not be found in the XML, (because content.type element is not mandatory) this method returns null.

Returns:

The content-type specified by content.type element in the XML.

Since:

1.2

getCharacterEncoding

public java.lang.String getCharacterEncoding()

Returns the character encoding of the original XML.

Note that this has nothing to do with the charset within the Content-Type. Rather, the returned value of this method is just the value of encoding attribute of the original XML.

Returns:

The character encoding of the original XML.

Since:

1.2

setDefaultValue

public void setDefaultValue(java.lang.String key,
                            java.lang.String value,
                            boolean isValid)
                     throws SimpleException

Insert the arbitrary String between the code fragments.

At the same time, you must specify if the String is valid or not. Based on the specified validity, this class selects the appropriate code fragments. Please look into the source XML listed below:

For example, to insert Hello between the 2 code fragments for valid case, your Servlet can call:

• setDefaultValue("item","Hello",true)

on the instance of this class. Then, the concatenated HTML tags can be retrieved by:

• getMerged( )

on the instance of this class. As you easily guess, the returned value will be:

• <ul><li>Hello</li></ul>

If false is specified as the last parameter of this method, the concatenated HTML tags will be:

• <ul><li><font color="#ff0000">Hello</font></li></ul>

This method gives you the explicit control over the validity of the String to be inserted.
If you insert only the valid String, please use:

• setDefaultValue(String,String)

instead of this method.

In addition, you can insert a set of Strings at a time. To use this feature, please use one of:

• setDefaultValue(Map)
• setDefaultValidValue(Map)
• setRequest(HttpServletRequest)
• setValidRequest(HttpServletRequest)

instead of this method. Some of these methods are wise enough to set the validity of the Strings. By verify.type attribute of d.value element in the source XML, the validity of the String can be determined automaticaly by this class.

By the way, please consider what will be happen if the String to be inserted includes the special characters such as < or &. The concatenated String will be illegal as the HTML tags and the corrupted String will be shown on the web browser. To avoid this problem, the special characters should be replaced with the escaped characters, such as &lt; or &amp;. And this method is wise enough to take care of this task, i.e. the special characters in the String will be escaped before inserted into the code fragments. In the source XML listed below, please look into escape.type attribute of d.value elements:

By the value of escape.type attribute, you can specify which special characters should be replaced. For details, please read about:

• FormValueEscaper

Please also notice the value of break.type attribute. The line separators within the String can be replaced with the tags for the line break, such as <br> or <br />. For details, please read about:

• FormValueBreaker

Parameters:

key - The value of d.value element in the source XML.

value - The String to be inserted between the code fragments.

isValid - Specify whether the String to be inserted is valid or not.

Throws:

SimpleException - If the specified key is not defined in the XML.

setDefaultValue

public void setDefaultValue(java.lang.String key,
                            java.lang.String value)
                     throws SimpleException

Insert the arbitrary String between the code fragments.

This method is equivalent to:

• setDefaultValue(String,String,boolean)

with true specified as the last parameter.
The String to be inserted will always be treated as the valid one. And only the code fragments for the valid case will be selected. Please look into the source XML listed below:

For example, to insert Hello between the 2 code fragments, your Servlet can call:

• setDefaultValue("item","Hello")

on the instance of this class. Then, the concatenated HTML tags can be retrieved by:

• getMerged( )

on the instance of this class. As you easily guess, the returned value will be:

• <ul><li>Hello</li></ul>

Thus, only the code fragments for the valid case will be selected.
If you'd like to have the explicit control over the validity of the String, please use:

• setDefaultValue(String,String,boolean)

instead of this method.

In addition, you can insert a set of Strings at a time. To use this feature, please use one of:

• setDefaultValue(Map)
• setDefaultValidValue(Map)
• setRequest(HttpServletRequest)
• setValidRequest(HttpServletRequest)

instead of this method. Some of these methods are wise enough to set the validity of the Strings. By verify.type attribute of d.value element in the source XML, the validity of the String can be determined automatically by this class.

By the way, please consider what will be happen if the String to be inserted includes the special characters such as < or &. The concatenated String will be illegal as the HTML tags and the corrupted String will be shown on the web browser. To avoid this problem, the special characters should be replaced with the escaped characters, such as &lt; or &amp;. And this method is wise enough to take care of this task, i.e. the special characters in the String will be escaped before inserted into the code fragments. In the source XML listed below, please look into escape.type attribute of d.value elements:

By the value of escape.type attribute, you can specify which special characters should be replaced. For details, please read about:

• FormValueEscaper

Please also notice the value of break.type attribute. The line separators within the String can be replaced with the tags for the line break, such as <br> or <br />. For details, please read about:

• FormValueBreaker

Parameters:

key - The value of d.value element in the source XML.

value - The String to be inserted between the code fragments.

Throws:

SimpleException - If the specified key is not defined in the XML.

setDefaultValue

public void setDefaultValue(java.util.Map map)

Insert a set of Strings into the code fragments at a time. The Strings are the values in the given Map.

First, this method lists all the values of d.value. (The duplicate value will be ignored.) And for each value, it tries to find the corresponding String value in the given instance of Map. If found, the String value will be inserted. At the same time, the validity of the String is determined on the verify.type attribute of that d.value element. Please look into the source XML listed below:

In this case, the String only with a-z or A-Z can be treated as valid. For example, if the String to be inserted includes any of 0-9, it is treated as invalid and the code fragments for the invalid case will be selected. For details, please read about:

• FormValueVerifier

In any case, if escape.type attribute is specified, the special characters in the String will be escaped. For details, please read about:

• FormValueEscaper

In addition, the line separators in the String will be replaced with the tags for line break (such as <br>), based on break.type attribute.

• FormValueBreaker

In case that the String is not found in the specified Map, the empty String will be inserted. The validity of this empty String depends on not.null attribute, i.e. if YES is specified there, the empty String will be treated as invalid.

If you'd like to pass the instance of HttpServletRequest instead of Map, please use:

• setRequest(HttpServletRequest)

Or, if you'd like to set the validities of all the Strings to true, please use any of:

• setDefaultValidValue(Map)
• setValidRequest(HttpServletRequest)

These methods ignores the attributes related with the validity of the String, and all the Strings will be treated as valid one.
Note that the value and the validity can be overridden individually by

• setDefaultValue(String,String)
• setDefaultValue(String,String,boolean)

Parameters:

map - The instance of Map, whose values are the Strings to be inserted.

setDefaultValidValue

public void setDefaultValidValue(java.util.Map map)

Insert a set of Strings into the code fragments at a time. The Strings are the values in the given Map.

First, this method lists all the values of d.value. (The duplicate value will be ignored.) And for each value, it tries to find the corresponding String value in the given instance of Map. If found, the String value will be inserted. In case that the String is not found in the specified Map, the empty String will be inserted.
Note that any String (including the empty String) will be treated as valid, regardless of not.null and verify.type attributes.

If escape.type attribute is specified in the source XML, the special characters in the String will be escaped. Please look into the source XML listed below:

For details, please read about:

• FormValueEscaper

In addition, the line separators in the String will be replaced with the tags for line break (such as <br>), based on break.type attribute. For details, please read about:

• FormValueBreaker

If you'd like to pass the instance of HttpServletRequest instead of Map, please use:

• setRequest(HttpServletRequest)

Note that the value and the validity can be overridden individually by

• setDefaultValue(String,String)
• setDefaultValue(String,String,boolean)

Parameters:

map - The instance of Map, whose values are the Strings to be inserted.

setValid

public void setValid(java.lang.String key,
                     boolean isValid)
              throws SimpleException

Set explicitly the validity of the String to be inserted.

Based on the specified validity, this class selects the appropriate code fragments. Please look into the source XML listed below:

For example, to insert Hello between the 2 code fragments for valid case, your Servlet can call:

• setDefaultValue("item","Hello")

on the instance of this class. Then, the concatenated HTML tags can be retrieved by:

• getMerged( )

on the instance of this class. As you easily guess, the returned value will be:

• <ul><li>Hello</li></ul>

But, after you call:

• setValid("item",false)

on the instance of this class, the concatenated HTML tags will be:

• <ul><li><font color="#ff0000">Hello</font></li></ul>

Thus, this method gives you the explicit control over the validity of the String to be inserted.

Parameters:

key - The value of d.value element in the source XML.

isValid - Specify whether the String to be inserted is valid or not.

Throws:

SimpleException - If the specified key is not defined in the XML.

setRequest

public void setRequest(com.oopreserch.web.HttpServletRequest req)

Insert a set of request parameters into the code fragments at a time.

This method is the analogue to:

• setDefaultValue(Map)

Note that the value and the validity can be overridden individually by

• setDefaultValue(String,String)
• setDefaultValue(String,String,boolean)

Parameters:

req - The instance of HttpServletRequest, whose request parameters will be inserted into the code fragments.

See Also:

setValidRequest(HttpServletRequest), setDefaultValue(Map),


setValidRequest

public void setValidRequest(com.oopreserch.web.HttpServletRequest req)

Insert a set of request parameters into the code fragments at a time.

This method is the analogue to:

• setDefaultValidValue(Map)

Note that the value and the validity can be overridden individually by

• setDefaultValue(String,String)
• setDefaultValue(String,String,boolean)

Parameters:

req - The instance of HttpServletRequest, whose request parameters will be inserted into the code fragments.

See Also:

setRequest(HttpServletRequest), setDefaultValue(Map),


isAllValid

public boolean isAllValid()

Return true if all the Strings are valid. Otherwise, false.

If you insert the Strings by:

• setRequest(HttpServletRequest)
• setDefaultValue(Map)

the validity of the Strings already are determined by:

• not.null
• verify.type

attributes of d.value elements in the source XML. Please look into the source XML listed below:

In this example, the empty Strings is treated as invalid, because the value of not.null attribute is YES. In addition, the String only with a-z or A-Z can be treated as valid. For example, if the String to be inserted includes any of 0-9, it is treated as invalid and the code fragments for the invalid case will be selected. For details, please read about:

• FormValueVerifier

In case that you insert the Strings by:

• setValidRequest(HttpServletRequest)
• setDefaultValidValue(Map)

all the Strings are treated as valid.

Note that the value and the validity can be overridden individually by

• setDefaultValue(String,String)
• setDefaultValue(String,String,boolean)

Returns:

true if all the Strings are valid. Otherwise, false.

getMerged

public java.lang.String getMerged()

Merge the inserted Strings into the code fragments and return the concatenated Strings.

Based on the validity of the inserted String, this class selects the appropriate code fragments. Please look into the source XML listed below:

To insert Hello between the 2 code fragments for valid case, your Servlet can call:

• setDefaultValue("item","Hello")

on the instance of this class. Then, this method returns the concatenated HTML tags. As you easily guess, the returned value will be:

• <ul><li>Hello</li></ul>

But, after you call:

• setValid("item",false)

on the instance of this class, the concatenated HTML tags will be:

• <ul><li><font color="#ff0000">Hello</font></li></ul>

Returns:

The concatenated String.

getHTML

public java.lang.String getHTML()

Deprecated.

Deprecated. Please use getMerged() instead.

clear

public void clear()

Set all the values to the empty String and their validity to true. In usual case, we need not call this method.

This method is called when the instance of this class goes back to the pool by FormGenerator.reuseForm(Form). So, the next time the same instance is retrieved from the pool, it is ready to be re-used.

See Also:

FormGenerator.reuseForm(Form)