edu.utexas.its.eis.tools.qwicap.servlet
Class FormDataSet

java.lang.Object
  edu.utexas.its.eis.tools.qwicap.servlet.FormDataSet

All Implemented Interfaces:

Iterable<FormControlValue>

public final class FormDataSet
extends Object
implements Iterable<FormControlValue>

Provides a complete representation of a set of web parameters (a "Form Data Set" in official W3C nomenclature) that is independent of the HttpServletRequest that supplied them. Thus, this form data set may be retained between requests. Also stored is information on the origin of the data set including the method by which it was submitted (GET, POST, etc.), and the path to the servlet that received them.

Author:

Chris W. Johnson

See Also:

Form Data Set as defined in section 17.13.3 of the HTML 4 Specification

Constructor Summary

FormDataSet()
Creates an empty FormDataSet object.

FormDataSet(HttpServletRequest Req)
Creates a FormDataSet object representing the data set available from the supplied HttpServletRequest object.

FormDataSet(String WWWFormURLEncodedString, String DefaultCharSetName)
Creates a FormDataSet instance populated with the data set extracted from a string encoded in the "application/x-www-form-urlencoded" format.

FormDataSet(String Method, String ContextPath, String ServletPath, byte[] ReqBytes)
Creates a FormDataSet object representing the data set contained in the supplied byte array.

Method Summary

FormDataSet	addControlValues(String Name, String... Values) Deprecated. Use addData(java.lang.String, java.lang.Object...) instead.
FormDataSet	addData(String Name, Object... Values) Adds control name/value(s) pairs to this form data set.
void	clear() Removes all data from this data set.
FormDataSet	deleteData(String... ControlNames) Removes from this form data set all values associated with each of the controls identified by a name in the ControlNames parameter.
FormDataSet	deleteData(String ControlName) Removes from this form data set all values associated with the control named by the ControlName parameter.
FormControlValue[]	get(Pattern Regex) Returns an array of FormControlValue objects containing all of the values in this form data set that were supplied by controls whose names matched the supplied regular expression.
FormControlValue	get(String ControlName) Returns a FormControlValue object containing all of the values in this form data set that were supplied by controls having the specified name.
String	getActionURL() Returns the action URL of this data set, if available.
String	getCharacterSetName() If this data set was instantiated from a String, or byte array, of input, this method returns the name of the character set in which the input was originally represented.
String	getContextPath() As stated in the HttpServletRequest.getContextPath documentation: Returns the portion of the request URI that indicates the context of the request.
String	getDatum(Pattern Regex) Returns the first value in this form data set that was supplied by a control whose names matches the supplied regular expression.
String	getDatum(String ControlName) Returns the first value in this form data set that was supplied by a control having the specified name.
String	getMethod() Returns the name of the HTTP mechanism used to send this form data set to the server: "GET" or "POST".
Exception	getProcessingException() Returns the Exception, if any, that was produced when this object's constructor retrieved, or attempted to retrieve, this form data set.
String	getServletPath() As stated in the HttpServletRequest.getServletPath documentation: Returns the part of this request's URL that calls the servlet.
String	getValue(Pattern Regex) Deprecated. Use getDatum(Pattern) instead.
String	getValue(String ControlName) Deprecated. Use getDatum(String) instead.
boolean	has(String ControlName) Returns true if there is data from the named control in this data set, or false otherwise.
boolean	hasControlNamesMatching(Pattern Regex) Returns true if this form data set includes vlaues from controls whose names match the supplied regular expression.
boolean	hasControlNamesStartingWith(String ControlNamePrefix) Returns true if this form data set includes values from controls whose names begin with the specified string.
boolean	isEmpty() Returns true if this form data set is empty, false otherwise.
Iterator<FormControlValue>	iterator() Returns an iterator for the complete set of FormControlValue objects in this form data set.
boolean	notEmpty() Returns true if this form data set contains data, false if it is empty.
FormDataSet	print() A debugging method that prints to System.out all information about this form data set and its contents.
FormDataSet	setActionURL(String ActionURL) Sets the action URL of this data set.
FormDataSet	setCharacterSetName(String NewCharSetName) Sets the name of the character set to be used to encode the characters of this form data set.
FormDataSet	setData(String Name, Object... Values) Adds control name/value(s) pairs to this form data set.
FormDataSet	setMethod(String Method) Sets the name of the HTTP mechanism to be used to send this form data set to a server: "GET" or "POST".
String	toString() Returns a human-readable representation of this data set.
byte[]	toWWWFormURLEncodedBytes() Returns this data set represented as a byte array in "application/x-www-form-urlencoded" format.
byte[]	toWWWFormURLEncodedBytes(String CharSet) Returns this data set represented as a byte array in "application/x-www-form-urlencoded" format.
byte[]	toWWWFormURLEncodedBytes(String CharSet, char URIAttributeSeparator) Returns this data set represented as a byte array in "application/x-www-form-urlencoded" format.
String	toWWWFormURLEncodedString() Returns this data set represented as a String in "application/x-www-form-urlencoded" format.
String	toWWWFormURLEncodedString(String CharSet) Returns this data set represented as a String in "application/x-www-form-urlencoded" format.
String	toWWWFormURLEncodedString(String CharSet, char URIAttributeSeparator) Returns this data set represented as a String in "application/x-www-form-urlencoded" format.

Methods inherited from class java.lang.Object

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

Constructor Detail

FormDataSet

public FormDataSet()

Creates an empty FormDataSet object.

FormDataSet

public FormDataSet(String WWWFormURLEncodedString,
                   String DefaultCharSetName)

Creates a FormDataSet instance populated with the data set extracted from a string encoded in the "application/x-www-form-urlencoded" format.

Parameters:

WWWFormURLEncodedString - A String in "application/x-www-form-urlencoded" format.

DefaultCharSetName - The name of the character set used to encode the characters of this data set. Note that standards require that the characters of which the WWWFormURLEncodedString parameter is composed must all be encoded using the "US-ASCII" character set, but that the characters represented by those characters may be encoded using any character set. The DefaultCharSetName parameter identifies the latter character set.

FormDataSet

public FormDataSet(String Method,
                   String ContextPath,
                   String ServletPath,
                   byte[] ReqBytes)

Creates a FormDataSet object representing the data set contained in the supplied byte array.

Parameters:

Method - The value returned by the HttpServletRequest.getMethod() method of the current request.

ContextPath - The value returned by the HttpServletRequest.getContextPath() method of the current request.

ServletPath - The value returned by the HttpServletRequest.getServletPath() method of the current request.

ReqBytes - The bytes of the current request in application/x-www-form-urlencoded format. Can be null.

See Also:

RFC 1738, section 2.2, "URL Character Encoding Issues"

FormDataSet

public FormDataSet(HttpServletRequest Req)

Creates a FormDataSet object representing the data set available from the supplied HttpServletRequest object.

Parameters:

Req - The current HttpServletRequest object.

Method Detail

clear

public void clear()

Removes all data from this data set.

addControlValues

@Deprecated
public FormDataSet addControlValues(String Name,
                                               String... Values)

Deprecated. Use addData(java.lang.String, java.lang.Object...) instead.

Adds control name/value(s) pairs to this form data set. If the named control is already represented in this data set, the additional value(s) supplied to this method are appended to its existing list of values (rather than replacing the existing values, for example). This method is used internally for building-up the data set, and user code shouldn't need it, ordinarily.

Parameters:

Name - The name of the control.

Values - The value(s) of the control.

Returns:

This FormDataSet object.

addData

public FormDataSet addData(String Name,
                           Object... Values)

Adds control name/value(s) pairs to this form data set. If the named control is already represented in this data set, the additional value(s) supplied to this method are appended to its existing list of values (rather than replacing the existing values, for example). This method is used internally for building-up the data set, and user code shouldn't need it, ordinarily.

Parameters:

Name - The name of the control.

Values - The value(s) of the control.

Returns:

This FormDataSet object.

setData

public FormDataSet setData(String Name,
                           Object... Values)

Adds control name/value(s) pairs to this form data set. If the named control is already represented in this data set, the new value(s) replace its existing value(s).

Parameters:

Name - The name of the control.

Values - The value(s) of the control.

Returns:

This FormDataSet object.

getCharacterSetName

public String getCharacterSetName()

If this data set was instantiated from a String, or byte array, of input, this method returns the name of the character set in which the input was originally represented. (In its encoded form, the input is required by RFC 1738 to be in the US-ASCII character set, but the encoded bytes could represent characters in any character set.) If this data set was instantiated using the default constructor, a general-purpose character set (almost certainly UTF-8) will have been selected as the default, and this method will return the name of that character set.

Returns:

The name of the character set used by this data set.

setCharacterSetName

public FormDataSet setCharacterSetName(String NewCharSetName)

Sets the name of the character set to be used to encode the characters of this form data set.

Parameters:

NewCharSetName - The name of the character set used to be used to encode the characters of this form data set.

Returns:

A reference to this FormDataSet instance.

getMethod

public String getMethod()

Returns the name of the HTTP mechanism used to send this form data set to the server: "GET" or "POST".

Returns:

The name of the HTTP mechanism used to send this form data set to the server: "GET" or "POST".

setMethod

public FormDataSet setMethod(String Method)

Sets the name of the HTTP mechanism to be used to send this form data set to a server: "GET" or "POST".

Parameters:

Method - The name of the HTTP mechanism ("get" or "post") to be used to send this form data set to a server.

Returns:

A reference to this FormDataSet instance.

getActionURL

public String getActionURL()

Returns the action URL of this data set, if available. If not available, null is returned. The action URL of a data set received from an HttpServletRequest is the URL to which the data set was sent. The action URL of a data set extracted from an XHTML page is the URL to which the data set should be sent. If the method used by this data set is "get" (see getMethod()), this data set will be appropriately encoded and appended to the URL as URI attributes, for example: "http://localhost/app/?hello=world&foo=bar".

Returns:

The action URL of this data set, or null.

setActionURL

public FormDataSet setActionURL(String ActionURL)

Sets the action URL of this data set. In the case of a data set received from an HttpServletRequest, the action URL should indicate the URL to which the data set was sent (see HttpServletRequest.getRequestURL()). In the case of a data set extract from an XHTML page, the action URL should specify where the data set is meant to be sent.

Parameters:

ActionURL - The action URL of this data set.

Returns:

A reference to this FormDataSet instance.

getContextPath

public String getContextPath()

As stated in the HttpServletRequest.getContextPath documentation:

Returns the portion of the request URI that indicates the context of the request. The context path always comes first in a request URI. The path starts with a "/" character but does not end with a "/" character. For servlets in the default (root) context, this method returns "". The container does not decode this string.

Returns:

"[T]he portion of the request URI that indicates the context of the request."

getServletPath

public String getServletPath()

As stated in the HttpServletRequest.getServletPath documentation:

Returns the part of this request's URL that calls the servlet. This includes either the servlet name or a path to the servlet, but does not include any extra path information or a query string.

Returns:

The portion of the request's URL that called the servlet.

getProcessingException

public Exception getProcessingException()

Returns the Exception, if any, that was produced when this object's constructor retrieved, or attempted to retrieve, this form data set.

Returns:

The Exception produced when this form data set was built, or null if everything worked correctly.

isEmpty

public boolean isEmpty()

Returns true if this form data set is empty, false otherwise.

Returns:

true if this form data set is empty, false otherwise.

notEmpty

public boolean notEmpty()

Returns true if this form data set contains data, false if it is empty.

Returns:

true if this form data set contains data, false if it is empty.

get

public FormControlValue get(String ControlName)

Returns a FormControlValue object containing all of the values in this form data set that were supplied by controls having the specified name.

Parameters:

ControlName - The name of the control(s) whose value(s) should be returned.

Returns:

A FormControlValue object containing all of the values supplied by controls having the specified name, or null if there are no such values.

get

public FormControlValue[] get(Pattern Regex)

Returns an array of FormControlValue objects containing all of the values in this form data set that were supplied by controls whose names matched the supplied regular expression.

Parameters:

Regex - The regular expression compiled as a Pattern object.

Returns:

A FormControlValue object for each value (or set of values) whose name matched the regular expression, or an empty array if there are no such controls.

getValue

@Deprecated
public String getValue(String ControlName)

Deprecated. Use getDatum(String) instead.

Returns the first value in this form data set that was supplied by a control having the specified name.

Parameters:

ControlName - The name of the control(s) whose first value should be returned.

Returns:

The first value of the named control(s), or null if there are no such values.

getDatum

public String getDatum(String ControlName)

Returns the first value in this form data set that was supplied by a control having the specified name.

Parameters:

ControlName - The name of the control(s) whose first value should be returned.

Returns:

The first value of the named control(s), or null if there are no such values.

getValue

@Deprecated
public String getValue(Pattern Regex)

Deprecated. Use getDatum(Pattern) instead.

Returns the first value in this form data set that was supplied by a control whose names matches the supplied regular expression.

Parameters:

Regex - The regular expression compiled as a Pattern object.

Returns:

The first value of the matching control(s), or null if there are no such values.

getDatum

public String getDatum(Pattern Regex)

Returns the first value in this form data set that was supplied by a control whose names matches the supplied regular expression.

Parameters:

Regex - The regular expression compiled as a Pattern object.

Returns:

The first value of the matching control(s), or null if there are no such values.

has

public boolean has(String ControlName)

Returns true if there is data from the named control in this data set, or false otherwise.

Parameters:

ControlName - Control name.

Returns:

true if there is data from the named control in this data set, or false otherwise.

hasControlNamesStartingWith

public boolean hasControlNamesStartingWith(String ControlNamePrefix)

Returns true if this form data set includes values from controls whose names begin with the specified string. The substring comparison is case-sensitive.

Parameters:

ControlNamePrefix - Control name prefix for which to test.

Returns:

true if this form data set includes values from controls whose names begin with the specified string, false otherwise.

hasControlNamesMatching

public boolean hasControlNamesMatching(Pattern Regex)

Returns true if this form data set includes vlaues from controls whose names match the supplied regular expression.

Parameters:

Regex - The regular expression compiled as a Pattern object.

Returns:

true if this form data set includes values from controls whose names are matched by the specified regular expression, false otherwise.

deleteData

public FormDataSet deleteData(String ControlName)

Removes from this form data set all values associated with the control named by the ControlName parameter. If there is no such control in the data set, nothing happens.

Parameters:

ControlName - The name of the control whose values should be removed from this form data set.

Returns:

A reference to this FormDataSet instance, in order to enable method invocation chaining.

deleteData

public FormDataSet deleteData(String... ControlNames)

Removes from this form data set all values associated with each of the controls identified by a name in the ControlNames parameter. When there is no control corresponding to a specified name, nothing happens.

Parameters:

ControlNames - The names of the controls whose values should be removed from this form data set.

Returns:

A reference to this FormDataSet instance, in order to enable method invocation chaining.

iterator

public Iterator<FormControlValue> iterator()

Returns an iterator for the complete set of FormControlValue objects in this form data set. Don't be surprised to find more than just the values from your own form controls, because the full-up Qwicap system (as opposed to the templater) adds hidden "input" controls to all forms for its internal use. Their names are always prefixed with "qwicap" to avoid name collisions. You can use the FormControlValue.isQwicapControl method to conveniently identify the control values that Qwicap has added.

Specified by:

iterator in interface Iterable<FormControlValue>

Returns:

An iterator for the complete set of FormControlValue objects in this form data set.

toString

public String toString()

Returns a human-readable representation of this data set.

Overrides:

toString in class Object

Returns:

A human-readable representation of this data set.

toWWWFormURLEncodedString

public String toWWWFormURLEncodedString()

Returns this data set represented as a String in "application/x-www-form-urlencoded" format. Like any String in Java, the characters comprising this string are Unicode, but, as required by RFC 1738 all of the Unicode characters used in this string correspond directly to "the graphic printable characters of the US-ASCII coded character set", excluding those characters that RFC 1738 labels "unsafe" (see section 2.2). Thus, while this string is not actually in the required US-ASCII character set (it's in UTF-16, like all Java String objects), it is guaranteed to be perfectly convertable to US-ASCII, in keeping with all of the requirements of RFC 1738.

The characters comprising the actual names and values of the data in this data set are encoded in the original/default character set for this data set (see getCharacterSetName()). The bytes produced by that encoding are the bytes that are subsequently encoded in the "application/x-www-form-urlencoded" format using only the prescribed portions of the US-ASCII character set as specified by RFC 1738. Thus, the data of this data set may be encoded in any character set, but still be represented entirely by US-ASCII characters, as required.

Returns:

A String representation of this data set in the "application/x-www-form-urlencoded" format.

toWWWFormURLEncodedString

public String toWWWFormURLEncodedString(String CharSet)

Returns this data set represented as a String in "application/x-www-form-urlencoded" format. Like any String in Java, the characters comprising this string are Unicode, but, as required by RFC 1738 all of the Unicode characters used in this string correspond directly to "the graphic printable characters of the US-ASCII coded character set", excluding those characters that RFC 1738 labels "unsafe" (see section 2.2). Thus, while this string is not actually in the required US-ASCII character set (it's in UTF-16, like all Java String objects), it is guaranteed to be perfectly convertable to US-ASCII, in keeping with all of the requirements of RFC 1738.

The characters comprising the actual names and values of the data in this data set are encoded in the character set specified by the CharSet parameter. The bytes produced by that encoding are the bytes that are subsequently encoded in the "application/x-www-form-urlencoded" format using only the prescribed portions of the US-ASCII character set as specified by RFC 1738. Thus, the data of this data set may be encoded in any character set, but still be represented entirely by US-ASCII characters, as required.

Parameters:

CharSet - The name of the character set in which the names and values of the data in this data set are to be encoded.

Returns:

A String representation of this data set in the "application/x-www-form-urlencoded" format.

toWWWFormURLEncodedString

public String toWWWFormURLEncodedString(String CharSet,
                                        char URIAttributeSeparator)

Returns this data set represented as a String in "application/x-www-form-urlencoded" format. Like any String in Java, the characters comprising this string are Unicode, but, as required by RFC 1738 all of the Unicode characters used in this string correspond directly to "the graphic printable characters of the US-ASCII coded character set", excluding those characters that RFC 1738 labels "unsafe" (see section 2.2). Thus, while this string is not actually in the required US-ASCII character set (it's in UTF-16, like all Java String objects), it is guaranteed to be perfectly convertable to US-ASCII, in keeping with all of the requirements of RFC 1738.

The characters comprising the actual names and values of the data in this data set are encoded in the character set specified by the CharSet parameter. The bytes produced by that encoding are the bytes that are subsequently encoded in the "application/x-www-form-urlencoded" format using only the prescribed portions of the US-ASCII character set as specified by RFC 1738. Thus, the data of this data set may be encoded in any character set, but still be represented entirely by US-ASCII characters, as required.

When a data set is encoded in "application/x-www-form-urlencoded" format for use in an HTTP URL, the name/value pairs of the data set may be separated by either ampersand ('&'), or semicolon (';'), characters. (See HTML 4 Specification, Section B.2.2, "Ampersands in URI Attribute Values".) The ampersand is the most common separator, but the semicolon is the most covenient when the string is to be placed into HTML markup, because a semicolon does not have to be encoded as an HTML character entity reference, unlike an ampersand (which ends-up as either "&amp;", or "&#59;"). The URIAttributeSeparator parameter allows you to specify whether an ampersand or a semicolon should be used.

Parameters:

CharSet - The name of the character set in which the names and values of the data in this data set are to be encoded.

URIAttributeSeparator - Either an ampersand ('&'), or a semicolon (';'), character.

Returns:

A String representation of this data set in the "application/x-www-form-urlencoded" format.

toWWWFormURLEncodedBytes

public byte[] toWWWFormURLEncodedBytes()

Returns this data set represented as a byte array in "application/x-www-form-urlencoded" format. As required by RFC 1738, all bytes in the array correspond directly to "the graphic printable characters of the US-ASCII coded character set", excluding those characters that RFC 1738 labels "unsafe" (see section 2.2).

The characters comprising the actual names and values of the data in this data set are encoded in the original/default character set for this data set (see getCharacterSetName()). The bytes produced by that encoding are the bytes that are subsequently encoded in the "application/x-www-form-urlencoded" format using only the prescribed portions of the US-ASCII character set as specified by RFC 1738. Thus, the data of this data set may be encoded in any character set, but still be represented entirely by US-ASCII character codes, as required.

Returns:

A byte array representing this data set in the "application/x-www-form-urlencoded" format.

toWWWFormURLEncodedBytes

public byte[] toWWWFormURLEncodedBytes(String CharSet)

Returns this data set represented as a byte array in "application/x-www-form-urlencoded" format. As required by RFC 1738, all bytes in the array correspond directly to "the graphic printable characters of the US-ASCII coded character set", excluding those characters that RFC 1738 labels "unsafe" (see section 2.2).

The characters comprising the actual names and values of the data in this data set are encoded in the character set specified by the CharSet parameter. The bytes produced by that encoding are the bytes that are subsequently encoded in the "application/x-www-form-urlencoded" format using only the prescribed portions of the US-ASCII character set as specified by RFC 1738. Thus, the data of this data set may be encoded in any character set, but still be represented entirely by US-ASCII character codes, as required.

Parameters:

CharSet - The name of the character set in which the names and values of the data in this data set are to be encoded.

Returns:

A byte array representing this data set in the "application/x-www-form-urlencoded" format.

toWWWFormURLEncodedBytes

public byte[] toWWWFormURLEncodedBytes(String CharSet,
                                       char URIAttributeSeparator)

Returns this data set represented as a byte array in "application/x-www-form-urlencoded" format. As required by RFC 1738, all bytes in the array correspond directly to "the graphic printable characters of the US-ASCII coded character set", excluding those characters that RFC 1738 labels "unsafe" (see section 2.2).

The characters comprising the actual names and values of the data in this data set are encoded in the character set specified by the CharSet parameter. The bytes produced by that encoding are the bytes that are subsequently encoded in the "application/x-www-form-urlencoded" format using only the prescribed portions of the US-ASCII character set as specified by RFC 1738. Thus, the data of this data set may be encoded in any character set, but still be represented entirely by US-ASCII character codes, as required.

When a data set is encoded in "application/x-www-form-urlencoded" format for use in an HTTP URL, the name/value pairs of the data set may be separated by either ampersand ('&'), or semicolon (';'), characters. (See HTML 4 Specification, Section B.2.2, "Ampersands in URI Attribute Values".) The ampersand is the most common separator, but the semicolon is the most covenient when the string is to be placed into HTML markup, because a semicolon does not have to be encoded as an HTML character entity reference, unlike an ampersand (which ends-up as either "&amp;", or "&#59;"). The URIAttributeSeparator parameter allows you to specify whether an ampersand or a semicolon should be used.

Parameters:

CharSet - The name of the character set in which the names and values of the data in this data set are to be encoded.

URIAttributeSeparator - Either an ampersand ('&'), or a semicolon (';'), character.

Returns:

A byte array representing this data set in the "application/x-www-form-urlencoded" format.

print

public FormDataSet print()

A debugging method that prints to System.out all information about this form data set and its contents. Note that, in general, the best way to see this information is not by modifying your code to invoke this print method, but by setting the logging level for this class to FINE.

Returns:

A reference to this FormDataSet instance.