com.devsphere.mapping
Interface FormDocument

public interface FormDocument

A form document contains static HTML and variables where dynamic content can be inserted. The beanToForm methods of FormUtils take a bean object and insert the bean data within the document as default values of the form elements. Error messages are inserted by these methods too. In addition, dynamic HTML content can be inserted within a document using its setValue() methods. Form documents are created by form templates.

Do not implement this interface. The mapping utilities recognize only the internal implementation of the framework.

See Also:

CharacterEncoding, FormTemplate, FormUtils

Method Summary

boolean	exists(java.lang.String varName) Returns true if a variable with the given name exists.
boolean	exists(java.lang.String varName, int index) Returns true if a variable identified by name and index exists.
int	getMaxIndex(java.lang.String varName) Returns the maximum index for a given variable name.
java.util.Enumeration	getNames() Returns the names of all variables.
java.lang.String	getValue(java.lang.String varName) Gets the value of a variable.
java.lang.String	getValue(java.lang.String varName, int index) Gets the value of a variable identified by name and index.
void	reset() Clears the default values and the error messages of all form elements and sets all variables to null.
void	send(java.io.OutputStream output) Sends the content of the document to an output stream.
void	send(java.io.OutputStream output, int encoding) Sends the content of the document to an output stream.
void	send(java.io.Writer writer) Sends the content of the document to a writer.
void	setValue(java.lang.String varName, int index, java.lang.String value) Sets the value of a variable identified by name and index.
void	setValue(java.lang.String varName, java.lang.String value) Sets the value of a variable.

Method Detail

send

public void send(java.io.OutputStream output)
          throws java.io.IOException

Sends the content of the document to an output stream. This method is typically used to respond to an HTTP GET/POST request with an HTML form.

Parameters:

output - the output stream whose methods are called to write the document's content. For example, it could be the stream returned by getOutputStream() of javax.servlet.ServletResponse

Throws:

NullPointerException - if output is null

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

send

public void send(java.io.OutputStream output,
                 int encoding)
          throws java.io.IOException

Sends the content of the document to an output stream. This method is typically used to respond to an HTTP GET/POST request with an HTML form.

Parameters:

output - the output stream whose methods are called to write the document's content. For example, it could be the stream returned by getOutputStream() of javax.servlet.ServletResponse

encoding - the character encoding. See the constants declared by CharacterEncoding.

Throws:

NullPointerException - if output is null

java.lang.IllegalArgumentException - if encoding has an invalid value.

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

send

public void send(java.io.Writer writer)
          throws java.io.IOException

Sends the content of the document to a writer. This method is typically used to respond to an HTTP GET/POST request with an HTML form.

Parameters:

writer - the writer whose methods are called to write the document's content. For example, it could be the writer returned by getWriter() of javax.servlet.ServletResponse

Throws:

NullPointerException - if writer is null

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

getNames

public java.util.Enumeration getNames()

Returns the names of all variables.

Returns:

the names of all variables

exists

public boolean exists(java.lang.String varName)

Returns true if a variable with the given name exists. If the variables with the given name were declared with indices, this method returns true only if one of them has the index 0).

Parameters:

varName - the name of the variable

Returns:

true if the variable exists

Throws:

NullPointerException - if varName is null

setValue

public void setValue(java.lang.String varName,
                     java.lang.String value)

Sets the value of a variable. If the variables with the given name were declared with indices, this method operates on the one whose index is 0). This method can be used to insert dynamic content within the document.

Parameters:

varName - the name of the variable

value - the new value of the variable

Throws:

NullPointerException - if varName is null

java.lang.IllegalArgumentException - if there is no variable with the given name

IndexOutOfBoundsException - if 0 is an invalid variable index

getValue

public java.lang.String getValue(java.lang.String varName)

Gets the value of a variable. If the variables with the given name were declared with indices, this method operates on the one whose index is 0).

Parameters:

varName - the name of the variable

Returns:

the value of the variable

Throws:

NullPointerException - if varName is null

java.lang.IllegalArgumentException - if there is no variable with the given name

IndexOutOfBoundsException - if 0 is an invalid variable index

getMaxIndex

public int getMaxIndex(java.lang.String varName)

Returns the maximum index for a given variable name. An index that is greater than or equal to 0 and is also less than or equal to the value returned by this method may or may not be valid. It can be tested with exists(). Any index less than 0 or greater than the value returned by this method is invalid.

Parameters:

varName - the name of the variable

Returns:

the maximum index for a variable name

Throws:

NullPointerException - if varName is null

java.lang.IllegalArgumentException - if there is no variable with the given name

exists

public boolean exists(java.lang.String varName,
                      int index)

Returns true if a variable identified by name and index exists.

Parameters:

varName - the name of the variable

index - the index of the variable

Returns:

true if the variable exists

Throws:

NullPointerException - if varName is null

setValue

public void setValue(java.lang.String varName,
                     int index,
                     java.lang.String value)

Sets the value of a variable identified by name and index. This method can be used to insert dynamic content within the document.

Parameters:

varName - the name of the variable

value - the new value of the variable

index - the index of the variable

Throws:

NullPointerException - if varName is null

java.lang.IllegalArgumentException - if there is no variable with the given name

IndexOutOfBoundsException - if index is an invalid variable index

getValue

public java.lang.String getValue(java.lang.String varName,
                                 int index)

Gets the value of a variable identified by name and index.

Parameters:

varName - the name of the variable

index - the index of the variable

Returns:

the value of the variable

Throws:

NullPointerException - if varName is null

java.lang.IllegalArgumentException - if there is no variable with the given name

IndexOutOfBoundsException - if index is an invalid variable index

reset

public void reset()

Clears the default values and the error messages of all form elements and sets all variables to null. This method should be called to bring the form document in its initial state so that it can be reused.