Qwicap (qwicap 1.4b26 [449] of 27-Apr-2011 Documentation)

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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

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

public final class Qwicap
extends Object
extends Object

The Qwicap class provides the core functionality of the Qwicap (Quick Web Interface for Conventional Applications) system, including the methods that send web pages to clients, and those that retrieve and verify the input returned by those pages, while automatically requesting corrections from users as necessary. It is also the thread within which each client's instance of the web application is run.

Form Input (Form Data Set) -Oriented Methods:

Form-Oriented Methods:

Page-Oriented Methods:

Download-Oriented Methods:

Upload-Oriented Methods:

Other Methods:

Author:: Chris W. Johnson

Method Summary
`Qwicap`	`addBlockingListener(QwicapBlockingListener Listener)` Adds a `QwicapBlockingListener` to the list of listeners that will be notified by this instance of `Qwicap` just before and after it blocks to wait for any user action.
`Downloadable`	`addDownloadable(Downloadable Download)` Associates a new downloadable item with the web page specified in the next `prompt` invocation.
`String`	`addDownloadable(String Name, byte[] Contents)` Associates a new downloadable item with the web page specified in the next `prompt` invocation.
`String`	`addDownloadable(String Name, String MIMEType, byte[] Contents)` Associates a new downloadable item with the web page specified in the next `prompt` invocation.
`Qwicap`	`clearMostRecentForm()` Removes all values from the XHTML markup of the form in the current page from which input was most recently received.
`Qwicap`	`convertSubmitButtonsToInputs(String[] UserAgentRegularExpressions)` Instructs Qwicap that when certain browsers are encountered, each "button" element with a "type" attribute set to "submit" in any page should be converted to an "input" element with a "type" attribute set to "submit".
`Downloadable`	`createDownloadable(String Name, String MIMEType, byte[] Contents)` Creates an instance of `Downloadable` to store the information triplet representing any downloadable item: name, MIME type, and content bytes.
`String`	`get(String ControlName)` Returns the value of the specified form control as a `String`.
`String[]`	`getAll(String ControlName)` Returns the values of the specified form control as an array of `String`s.
`Auth2SchemeReply`	`getAuth2SchemeReply()` Returns the reply object from the authentication & authorization scheme (`Auth2Scheme`), if any, that is associated with the current hit.
`BigDecimal`	`getBigDecimal(String ControlName, BigDecimal MinValue, BigDecimal MaxValue, boolean AllowedToBeBlank, BigDecimal DefaultValue)` Returns the value of the specified control as a `BigDecimal`.
`BigDecimal[]`	`getBigDecimals(String ControlName, BigDecimal MinValue, BigDecimal MaxValue, boolean AllowedToBeBlank, BigDecimal[] DefaultValues)` Returns the values of the specified controls as `BigDecimal` objects.
`BigInteger`	`getBigInteger(String ControlName, BigInteger MinValue, BigInteger MaxValue, boolean AllowedToBeBlank, BigInteger DefaultValue)` Returns the value of the specified control as a `BigInteger`.
`BigInteger[]`	`getBigIntegers(String ControlName, BigInteger MinValue, BigInteger MaxValue, boolean AllowedToBeBlank, BigInteger[] DefaultValues)` Returns the values of the specified controls as `BigInteger` objects.
`boolean`	`getBoolean(String ControlName, boolean AllowedToBeBlank, boolean DefaultValue)` Returns the value of the specified control as a `boolean` primitive.
`boolean`	`getBoolean(String ControlName, String TrueStr, String FalseStr, boolean AllowedToBeBlank, boolean DefaultValue)` Returns the value of the specified control as a `boolean` primitive.
`Context`	`getContext()` Returns the `Context` object associated with this Qwicap thread.
`static Qwicap`	`getCurrentInstance()` Returns a reference to the current Qwicap thread.
`XMLDocument`	`getDocument(String FileName)` Loads from disk, or retrieves from the document cache, an immutable representation of the XML document located on the local file system at the specified path.
`XMLDocument`	`getDocument(URL DocumentURL)` Loads from the specified URL, or retrieves from the document cache, an immutable representation of an XML document.
`double`	`getDouble(String ControlName, double MinValue, double MaxValue, boolean AllowedToBeBlank, double DefaultValue)` Returns the value of the specified control as a `double`.
`double[]`	`getDoubles(String ControlName, double MinValue, double MaxValue, boolean AllowedToBeBlank, double[] DefaultValues)` Returns the values of the specified controls as `double` primitives.
`float`	`getFloat(String ControlName, float MinValue, float MaxValue, boolean AllowedToBeBlank, float DefaultValue)` Returns the value of the specified control as a `float`.
`float[]`	`getFloats(String ControlName, float MinValue, float MaxValue, boolean AllowedToBeBlank, float[] DefaultValues)` Returns the values of the specified controls as `float` primitives.
`Form`	`getForm()` Returns a `Form` object which refers to the form that supplied the form data set most recently submitted to the current web page.
`FormDataSet`	`getFormDataSet()` Returns the form data set most recently submitted by the current web page.
`i18nServices`	`geti18nServicesForClass(Class<?> ClientClass)`
`FormDataSetFilter`	`getInputFilter()` Returns the object that is currently filtering all input received from the client machine.
`int`	`getInt(String ControlName, int MinValue, int MaxValue, boolean AllowedToBeBlank, int DefaultValue)` Returns the value of the specified control as an `int`.
`int[]`	`getInts(String ControlName, int MinValue, int MaxValue, boolean AllowedToBeBlank, int[] DefaultValues)` Returns the values of the specified controls as `int` primitives.
`long`	`getLong(String ControlName, long MinValue, long MaxValue, boolean AllowedToBeBlank, long DefaultValue)` Returns the value of the specified control as a `long`.
`long[]`	`getLongs(String ControlName, long MinValue, long MaxValue, boolean AllowedToBeBlank, long[] DefaultValues)` Returns the values of the specified controls as `long` primitives.
`Random`	`getRandom()` Returns the pseudo-random number generator (PRNG) used internally by Qwicap.
`boolean`	`getScriptsEnabled()` This method is temporary and unsupported.
`String`	`getStatusReport(boolean Clear)` Returns a string containing a human-readable report on Qwicap's current (and past) status.
`static String`	`getStatusReport(Class<?> WebAppMainClass, boolean Clear)` Returns a string containing a human-readable report on Qwicap's current (and past) status.
`String`	`getString(String ControlName, int MinLength, int MaxLength, boolean Trim)` Returns the value of the specified parameter as a `String`.
`String`	`getString(String ControlName, int MinLength, int MaxLength, boolean Trim, String ValidatorRegex, Object ValidatorRegexErrorMsg)` Returns the value of the specified control as a `String`.
`FileItem`	`getUploadedFile(String ControlName, String[] ContentTypes, boolean AllowedToBeMissing)` Returns a `FileItem` object describing the uploaded file associated with a specified control name.
`FileItem`	`getUploadedFile(String ControlName, String ContentType, boolean AllowedToBeMissing)` Returns a `FileItem` object describing the uploaded file associated with a specified control name.
`int`	`getUploadedFileRAMLimit()` Returns the maximum size of an uploaded file that will be memory-resident; larger files will be stored on disk (see `getUploadedFileRepository()`), while files beyond a certain size won't be accepted at all (see `getUploadedFileSizeLimit()`).
`String`	`getUploadedFileRepository()` Returns the path of the directory in which uploaded files are stored when they are too large to be stored in memory; see `getUploadedFileRAMLimit()`.
`long`	`getUploadedFileSizeLimit()` Returns the maximum acceptable size of an uploaded file.
`String`	`getUserAgent()` Returns the web browser (user agent) identity string that was provided by the client with its most recent request.
`static String`	`getVersionString()` Returns a string identifying this version of Qwicap.
`Qwicap`	`goodbye(Downloadable Download)` Sends the final item of this session to the user, and returns without waiting for input from the user.
`Qwicap`	`goodbye(Markup PageMarkup)` Sends the final XHTML page of this session to the user, and returns without waiting for input from the user.
`Qwicap`	`goodbye(String RedirectURL)` Redirects to the client to an arbitrary URL, and returns immediately.
`Qwicap`	`goodbye(String ContentType, byte[] Data)` Sends the final item of this session to the user, and returns without waiting for input from the user.
`boolean`	`has(String ControlName)` Returns `true` if the specified form control supplied one or more values in the current form data set, and `false` if it does not.
`boolean`	`hasFormDataSet()` Returns `true` if a form data set is available, `false` otherwise.
`static String`	`htmlDecode(String PotentiallyEncodedStr)` Decodes a string such any HTML character entities in it are translated into corresponding Unicode characters.
`static String`	`htmlEncode(String RawStr)` Encodes a string such that it can be safely embedded in an XHTML document without risk of the document's syntax being corrupted, or the contents of the string being interpreted as XHTML markup (a potential security hole).
`Qwicap`	`invokeInputFilter()` Invokes the `FormDataSetFilter` filter that was set using `setInputFilter`, if any.
`Qwicap`	`populateMostRecentForm()` Takes the form data set most recently received from the client and embeds it into the XHTML markup of the form from which it originated in the current page.
`Qwicap`	`printPageStack()` Prints to the console a summary of Qwicap's internal page stack as an aid to understanding Qwicap's automatic page stack maintenance.
`PromptModifiers`	`prompt()` Begins the process of setting-up a prompt to send an XHTML page to the user.
`Qwicap`	`prompt(MutableMarkup XHTMLPage)` Sends an XHTML page to the user, and waits for their response.
`Qwicap`	`promptComplete()` This method allows a method that displays a page (by implementing the "prompt" pattern for it) to explicitly inform Qwicap when it has finished with the page.
`Qwicap`	`redirect(String DestinationURL)` Redirects the client to the specified URL, and blocks until the user returns to this web application.
`void`	`rejectInput(Object ErrorMsg)` Inserts an error message immediately before the form whose input was most recently submitted, and sends the page containing that form back to the user for correction.
`void`	`rejectInput(String[] ControlNames, Object[] ControlValues, Object ErrorMsg)` Marks the form controls that supplied the rejected input, inserts an error message immediately before the form, and sends the page containing the form back to the user for correction.
`void`	`rejectInput(String ControlName, Object ControlValue, boolean ErrorMsgIsXHTMLFragment, String ErrorMsg)` Deprecated. Use `rejectInput(String, Object, Object)` instead, passing an `XMLString` if the error message is an XHTML fragment, or a `String`, if it is not XHTML.
`void`	`rejectInput(String ControlName, Object ControlValue, Object ErrorMsg)` Marks the form control that supplied the rejected input, inserts an error message immediately before the form, and sends the page containing the form back to the user for correction.
`Qwicap`	`removeBlockingListener(QwicapBlockingListener Listener)` Removes a `QwicapBlockingListener` from the list of listeners that will be notified by this instance of `Qwicap` just before and after it blocks to wait for any user action.
`Qwicap`	`reportException(Throwable T)` Instructs Qwicap to insert an error message relating to the specified exception into the page next passed to either the `prompt`, or the `goodbye`, methods.
`Qwicap`	`reportProblem(Object ProblemDescription)` Instructs Qwicap to insert a problem report message into the page next passed to either the `prompt`, or the `goodbye`, methods.
`Qwicap`	`reportProblem(Object ProblemDescription, Object DebugInformation)` Instructs Qwicap to insert a problem report message into the page next passed to either the `prompt`, or the `goodbye`, methods.
`Qwicap`	`setInputFilter(FormDataSetFilter Filter)` Sets an object that will filter all input received from the client machine before Qwicap passes it along to the client application.
`Qwicap`	`setScriptsEnabled(boolean ScriptsEnabled)` This method is temporary and unsupported.
`Qwicap`	`setUploadedFileLimits(int MaxSizeInRAM, long MaxSize, String RepositoryPath)` Specifies all the settings that affect the HTTP file upload functionality.
`Qwicap`	`showPage(MutableMarkup XHTMLPage)` If you have a web page which has been constructed such that the user cannot possibly interact with it incorrectly, this method can be used to send that page to the client instead of `prompt`, and without implementing the "prompt pattern".
`String`	`toString()`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Method Detail

getVersionString

public static String getVersionString()

Returns a string identifying this version of Qwicap. The version numbering convention is: "M.N[.R][SB]".

M - Major Version Number
N - Minor Version Number
R - Revision Number, added/incremented when features haven't really changed, but bugs, etc. have been fixed.
S - Build Status:
- 'd' - Development build. Often doesn't leave the developer's machine. Will seldom go beyond the members of the development team.
- 'a' - Alpha test. Not feature complete, but suitable for early testing, and much more stable than a development build.
- 'b' - Beta test. Feature complete in every important respect. Available to general testing audience.
- none - Release.
B - Build Number. Only used while code is in development, alpha or beta test.

Typically, the date of the build is appended, for example: "1.1 of 29-Apr-2004". The date is in DD-MMM-YYYY format because it's fairly easy to read, and it's fairly unambiguous in international contexts.

Returns:: Version number string for this build of Qwicap.

getStatusReport

public static String getStatusReport(Class<?> WebAppMainClass,
                                     boolean Clear)

Returns a string containing a human-readable report on Qwicap's current (and past) status. Due to the changeable nature of the data gathered, no API for programmatically accessing this data has been defined.

Parameters:: WebAppMainClass - The class that contains the public static void main(String[]) method which is this web application's entry point. This reference to the entry point class is required in order to determine which application's status should be returned. (In cases where Qwicap is deployed as a shared library, it may be maintaining status information for any number of web applications.); Clear - true if the data in the report should be reset after the report is generated, false if the data should continue to accumulate.
Returns:: A String containing the human-readable status report.

getStatusReport

public String getStatusReport(boolean Clear)

Parameters:: Clear - true if the data in the report should be reset after the report is generated, false if the data should continue to accumulate.
Returns:: A String containing the human-readable status report.

getRandom

public Random getRandom()

Returns the pseudo-random number generator (PRNG) used internally by Qwicap. This PRNG is shared by all Qwicap threads in a particular web application. It is initialized when Qwicap is first loaded, using various system-specific information as its source of entropy, in a manner inspired by the SecureRandom class. The algorithm is based on a "rule 30", one-dimensional, cellular automaton, as suggested by Stephen Wolfram in his book A New Kind of Science, page 317 (see also page 974). As Wolfram points-out, this is the same method that Mathematica has always used to generate its random numbers.

By using this PRNG in your web applications, you avoid the overhead of creating a new PRNG, and the unpredictable interleaving of usage by the various concurrent sessions (threads) in your web application makes the sequence obtained by any given session even more unpredictable than it would be anyway.

Note: If the application server's security manager permits it, this PRNG implementation is made available through the "Provider" mechanism of the Security class. Thus, a SecureRandom instance which utilizes this PRNG implementation, and which, by default, is seeded from Qwicap's internal instance of this PRNG, may be obtained by using the following invocation: SecureRandom.getInstance("Rule30", "Qwicap");. Note that this particular "rule 30" PRNG implementation has not been subjected to FIPS 140-2 compliance testing, though it has been subjected to similar tests, and other "rule 30" PRNG implementations appear to have satisfied FIPS 140-2 requirements.

Returns:: Qwicap's internal pseudo-random number generator instance.

getCurrentInstance

public static Qwicap getCurrentInstance()

Returns a reference to the current Qwicap thread.

Returns:: Current Qwicap thread.
Throws:: IllegalStateException - If invoked from a non-Qwicap thread.

getContext

public Context getContext()

Returns the Context object associated with this Qwicap thread.

Returns:: The Context object associated with this Qwicap thread.

getUserAgent

public String getUserAgent()

Returns the web browser (user agent) identity string that was provided by the client with its most recent request.

Returns:: The web browser (user agent) identity string that was provided by the client with its most recent request, or an empty String, if there was none.

getAuth2SchemeReply

public Auth2SchemeReply getAuth2SchemeReply()

Returns the reply object from the authentication & authorization scheme (Auth2Scheme), if any, that is associated with the current hit.

Returns:: The Auth2SchemeReply instance associated with the current hit.

geti18nServicesForClass

public i18nServices geti18nServicesForClass(Class<?> ClientClass)

getScriptsEnabled

public boolean getScriptsEnabled()

This method is temporary and unsupported. It is part of a potential new feature that is still a work-in-progress.

Returns:: true if Qwicap is placing scripts in web pages, false if not.

setScriptsEnabled

public Qwicap setScriptsEnabled(boolean ScriptsEnabled)

This method is temporary and unsupported. It is part of a potential new feature that is still a work-in-progress.

Parameters:: ScriptsEnabled - true if Qwicap is allowed to place scripts in web pages, false if not.
Returns:: A reference to this Qwicap instance, to facilitate method invocation chaining.

addBlockingListener

public Qwicap addBlockingListener(QwicapBlockingListener Listener)

Adds a QwicapBlockingListener to the list of listeners that will be notified by this instance of Qwicap just before and after it blocks to wait for any user action. If this instance of Qwicap is in the process of blocking/unblocking (which can only be the case if this method is invoked from within a QwicapBlockingListener), the specified listener will not be added until after the unblocking is complete.

Parameters:: Listener - An instance of a class that implements the QwicapBlockingListener interface.
Returns:: A reference to this Qwicap instance, to facilitate method invocation chaining.

removeBlockingListener

public Qwicap removeBlockingListener(QwicapBlockingListener Listener)

Removes a QwicapBlockingListener from the list of listeners that will be notified by this instance of Qwicap just before and after it blocks to wait for any user action. If this instance of Qwicap is in the process of blocking/unblocking (which can only be the case if this method is invoked from within a QwicapBlockingListener), the specified listener will not be removed until after the unblocking is complete.

Parameters:: Listener - An instance of a class that implements the QwicapBlockingListener interface, and which has previously been passed to the addBlockingListener method of this Qwicap instance.
Returns:: A reference to this Qwicap instance, to facilitate method invocation chaining.

setInputFilter

public Qwicap setInputFilter(FormDataSetFilter Filter)

Sets an object that will filter all input received from the client machine before Qwicap passes it along to the client application. There can be only one filter at a time. To remove the current filter, pass null.

The data set (if any) sent with the current hit is filtered the next time an invocation of a prompt method, or the redirect method, occurs, unless invokeInputFilter is used before then.

Parameters:: Filter - The object which will filter all input received from the client machine. To specify that there should be no filter, pass null.
Returns:: A reference to this Qwicap instance, to facilitate method invocation chaining.

invokeInputFilter

public Qwicap invokeInputFilter()
                         throws QwicapException

Invokes the FormDataSetFilter filter that was set using setInputFilter, if any. The filter is sent the data set that arrived with the current hit.

Returns:: A reference to this Qwicap instance, to facilitate method invocation chaining.
Throws:: QwicapException - If execution of the filter produces any exceptions.

getInputFilter

public FormDataSetFilter getInputFilter()

Returns the object that is currently filtering all input received from the client machine.

Returns:: The current filter object.

getDocument

public XMLDocument getDocument(String FileName)
                        throws TagException,
                               IOException

Loads from disk, or retrieves from the document cache, an immutable representation of the XML document located on the local file system at the specified path. When a requested document is found in the cache, the file on disk from which it was originally read is checked for modification by examining its size and modification date. If found to have been modified, the document is reloaded and the cache updated. In order to pass the document to the prompt(MutableMarkup) or goodbye(Markup) methods, or to do anything else that modifies the document, you'll need to acquire a mutable version of the document by using the ImmutableMarkup.getMutable() method.

Parameters:: FileName - Path to the document on the local file system.
Returns:: An immutable representation of the requested document.
Throws:: FileNotFoundException - If the specified file was not found.; TagException - If there was a problem with parsing the document.; IOException - If there was a problem with reading the document.
See Also:: ImmutableMarkup.getMutable()

getDocument

public XMLDocument getDocument(URL DocumentURL)
                        throws TagException,
                               IOException

Loads from the specified URL, or retrieves from the document cache, an immutable representation of an XML document. Documents originally loaded from URLs are not cecked for modifications when they are found in the cache, so the cache can become stale. In order to pass the document to the prompt(MutableMarkup) or goodbye(Markup) methods, or to do anything else that modifies the document, you'll need to acquire a mutable version of the document by using the ImmutableMarkup.getMutable() method.

Parameters:: DocumentURL - URL specifying the location of the document.
Returns:: An immutable representation of the requested document.
Throws:: TagException - If there was a problem with parsing the document.; IOException - If there was a problem with reading the document.
See Also:: ImmutableMarkup.getMutable()

toString

public String toString()

Overrides:: toString in class Object

reportProblem

public Qwicap reportProblem(Object ProblemDescription)
                     throws QwicapSessionDeathException,
                            QwicapAbandonmentException

Instructs Qwicap to insert a problem report message into the page next passed to either the prompt, or the goodbye, methods. The problem description will also be provided to the server's log (level "FINE", class "edu.utexas.its.eis.tools.qwicap.servlet.IncidentProblem").

Parameters:: ProblemDescription - The object that will supply the text of the problem report that is to be inserted into the page markup. Generally, this will be a String object, but it can be any type of object. Certain common classes (for example Markup and its subclasses, Results, etc.) receive special handling appropriate to their functions. Other objects are handled merely by invoking their toString methods and inserting the resulting String object into the page markup. Note: Passing a Throwable, or any of its subclasses, will cause reportException(java.lang.Throwable) to be invoked. This behavior prevents reportException's security features from being bypassed merely by the expedient of passing exceptions to reportProblem, instead. To maintain the security of their applications, it is important for developers to carefully consider the nature of the information that they allow their applications to pass along to users (who may be attackers).
Returns:: A reference to this Qwicap instance, to facilitate method invocation chaining.
Throws:: QwicapSessionDeathException - If you attempt to report a QwicapSessionDeathException, it will be rethrown, instead. This exception should not be caught, let alone reported.; QwicapAbandonmentException - If you attempt to report any subclass of QwicapAbandonmentException, it will be rethrown, instead. This exception should not be reported, and shouldn't even be caught, except when implementing the standard Qwicap "prompt" pattern.

reportProblem

public Qwicap reportProblem(Object ProblemDescription,
                            Object DebugInformation)
                     throws QwicapSessionDeathException,
                            QwicapAbandonmentException

Instructs Qwicap to insert a problem report message into the page next passed to either the prompt, or the goodbye, methods. The problem description and associated debugging information will also be provided to the server's log (level "FINE", class "edu.utexas.its.eis.tools.qwicap.servlet.IncidentProblem"). Additionally, when Qwicap is operating in its low-security "development" mode (the "qwicap-development-mode" context parameter in the web application's "web.xml" file is set to "true"), the debug information will also be placed into an HTML comment block and embedded into the page along with the user-visible problem report message. Conversely, when Qwicap is operating in its default, high-security mode, the debugging information will never be included in any web page.

Parameters:: ProblemDescription - The object that will supply the text of the problem report that is to be inserted into the page markup. Generally, this will be a String object, but it can be any type of object. Certain common classes (for example Markup and its subclasses, Results, etc.) receive special handling appropriate to their functions. Other objects are handled merely by invoking their toString methods and inserting the resulting String object into the page markup. Note: Passing a Throwable, or any of its subclasses, will cause reportException(java.lang.Throwable) to be invoked. This behavior prevents reportException's security features from being bypassed merely by the expedient of passing exceptions to reportProblem, instead. To maintain the security of their applications, it is important for developers to carefully consider the nature of the information that they allow their applications to pass along to users (who may be attackers).; DebugInformation - An object that, when converted to a String will supply debugging information relevant to this problem.
Returns:: A reference to this Qwicap instance, to facilitate method invocation chaining.
Throws:: QwicapSessionDeathException - If you attempt to report a QwicapSessionDeathException, it will be rethrown, instead. This exception should not be caught, let alone reported.; QwicapAbandonmentException - If you attempt to report any subclass of QwicapAbandonmentException, it will be rethrown, instead. This exception should not be reported, and shouldn't even be caught, except when implementing the standard Qwicap "prompt" pattern.

reportException

public Qwicap reportException(Throwable T)
                       throws QwicapSessionDeathException,
                              QwicapAbandonmentException

Instructs Qwicap to insert an error message relating to the specified exception into the page next passed to either the prompt, or the goodbye, methods. The exception will be provided to the server's log (level "SEVERE", class "edu.utexas.its.eis.tools.qwicap.servlet.IncidentThrowable"). Additionally, when Qwicap is operating in its low-security "development" mode (the "qwicap-development-mode" context parameter in the web application's "web.xml" file is set to "true"), the exception's full stack trace will be placed into an HTML comment block and embedded into the page along with the user-visible error message. Conversely, when Qwicap is operating in its default, high-security mode, neither the exception's message, nor its stack trace, will ever be included in any web page. Instead, only an "incident code"—comprised of the date and a random hexadecimal sequence, for example "20080131-A79DF0"—will be reported to the user. The incident code is logged with the exception, so that when a user reports a problem and cites its incident code, personnel with access to the server's logs can easily identify the relevant log entry.

Parameters:: T - The Throwable to be reported.
Returns:: A reference to this Qwicap instance, to facilitate method invocation chaining.
Throws:: QwicapSessionDeathException - If you attempt to report a QwicapSessionDeathException, it will be rethrown, instead. This exception should not be caught, let alone reported.; QwicapAbandonmentException - If you attempt to report any subclass of QwicapAbandonmentException, it will be rethrown, instead. This exception should not be reported, and shouldn't even be caught, except when implementing the standard Qwicap "prompt" pattern.
See Also:: reportProblem(java.lang.Object)

convertSubmitButtonsToInputs

public Qwicap convertSubmitButtonsToInputs(String[] UserAgentRegularExpressions)

Instructs Qwicap that when certain browsers are encountered, each "button" element with a "type" attribute set to "submit" in any page should be converted to an "input" element with a "type" attribute set to "submit". This works-around hideous bugs in Internet Explorer for both Macintosh and Windows. (Ordinarily, Internet Explorer for either platform can be identified using the regular expression "; MSIE [0-9]+[.][0-9]+([a-z]+[0-9]*)?;".)

This conversion works hard to be transparent. For one thing, once it is enabled using this method, the conversion takes place automatically, every time you invoke a prompt method, and the conversion is then automatically undone before the prompt method returns control to your code. The goal is that your code shouldn't be affected by the conversion at all. However, it isn't practical to make the process perfect. For instance, a "button" element like "<button name='shootto' value='17' type='submit' id='shoot3'>Shoot Into <span class='room'>17</span></button>" will loose the "span" element inside its button label during the conversion, and it won't get it back when the conversion is reversed. By way of illustration, the "button" element shown above will be converted into the following "input" element: "<input type='submit' value='Shoot Into 17' name='qwicap-input-submit?shootto=17' id='shoot3'/>". When the conversion is reversed, that will yield the following "button" element: "<button type='submit' name='shootto' value='17' id='shoot3'>Shoot Into 17</button>". If your code manipulates that same markup in a manner that depends on the presence of the "span" elements in the "button" titles, it will not acheive the desired result.

Parameters:: UserAgentRegularExpressions - An array of regular expression strings that will be used to identify the browser(s) for which this conversion should be performed. If any of them match any portion of the browser's user agent string, the conversion will be performed.
Returns:: A reference to this Qwicap instance, to facilitate method invocation chaining.

showPage

public Qwicap showPage(MutableMarkup XHTMLPage)
                throws QwicapException

If you have a web page which has been constructed such that the user cannot possibly interact with it incorrectly, this method can be used to send that page to the client instead of prompt, and without implementing the "prompt pattern". Typically, such pages are used to non-interactively display information to the user, and the user is given no option except to acknowledge the information. Therefore, there is no possibility of having to display the page again in response to an input error. Nor does your code need any input from the page to determine what to do next. Whatever input the user supplies to the page, typically by clicking on an acknowledgement button (for example "OK"), is automatically discarded.

Parameters:: XHTMLPage - XHTML page to be sent to the user.
Returns:: A reference to this Qwicap instance, to facilitate method invocation chaining.
Throws:: QwicapException - If anything goes wrong, or if the page is abandoned.

promptComplete

public Qwicap promptComplete()

This method allows a method that displays a page (by implementing the "prompt" pattern for it) to explicitly inform Qwicap when it has finished with the page. Qwicap then regards the page as dead, and knows to ignore input from cached copies of it. Frequently, it is isn't necessary to invoke this method, because Qwicap will automatically figure-out that a page is dead if its supporting method (the one that implemented the "prompt" pattern for it) has exited before the next invocation of one of the "prompt" methods. Nonetheless, there are situations where the automatic dead page detection is not sufficient, and this method will let you disambiguate those situations. Failure to use this method when it is necessary can lead to some sub-optimal page management, but won't lead to a crisis, so think of this method as a page navigation optimization, rather than a necessity.

Returns:: A reference to this Qwicap instance, to facilitate method invocation chaining.

prompt

public Qwicap prompt(MutableMarkup XHTMLPage)
              throws QwicapException

Sends an XHTML page to the user, and waits for their response. The form control values returned by the user are automatically embedded into the supplied XHTML page.

Parameters:: XHTMLPage - XHTML page to be sent to the user.
Returns:: A reference to this Qwicap instance, to facilitate method invocation chaining.
Throws:: QwicapException - If anything goes wrong, or if the page is abandoned.
See Also:: goodbye(Markup)

prompt

public PromptModifiers prompt()

Begins the process of setting-up a prompt to send an XHTML page to the user. An instance of the PromptModifiers class is returned. By invoking various methods on it, the behavior of the prompt operation may be fully specified, and the prompt is finally performed by invoking PromptModifiers.usingPage. This sounds cumbersome, but it's intended that all of this be performed in-line, and in an IDE that will show you the available methods at any given time. Used in that context it should be convenient and yield highly readable code. See the examples below:

Q.prompt().modelessly().withFormData().rejectingWithFormData().usingPage(MyMarkup);
Q.prompt().modally().withoutFormData().rejectingWithoutFormData().usingPage(MyMarkup);

The first example actually represents the default prompt configuration, and would ordinarily be written merely as "Q.prompt().usingPage(MyMarkup);". The second example represents the opposite of the default configuration, and is, therefore, the worst case. The PromptModifiers methods may be invoked in any order, except for PromptModifiers.usingPage, which must always come last, because it triggers the actual "prompt" operation. Like the various Qwicap.prompt methods, it returns a reference to your Qwicap instance, just in case it's convenient.

Returns:: A PromptModifiers object to allow the behavior of the prompt to be customized.

rejectInput

@Deprecated
public void rejectInput(String ControlName,
                                   Object ControlValue,
                                   boolean ErrorMsgIsXHTMLFragment,
                                   String ErrorMsg)
                 throws QwicapException

Deprecated. Use rejectInput(String, Object, Object) instead, passing an XMLString if the error message is an XHTML fragment, or a String, if it is not XHTML.

Marks the form control that supplied the rejected input, inserts an error message immediately before the form, and sends the page containing the form back to the user for correction. All of the user's input is embedded into the form when it is sent back, so the user will not have to re-enter the form contents in order to correct the rejected input. The web application blocks when rejectInput is invoked, and unblocks only after potentially valid input is received from the user.

If the ErrorMsg parameter contains one or more XML elements marked with the class "qwicap-label-text", the contents of those elements will be replaced with the labels of the form elements that supplied the rejected parameters. By the same token, the contents of elements marked with the class "qwicap-param-value" will be replaced with the values that are being rejected. For example, if a form element labelled "Wombat Burrow" was rejected, and the ErrorMsg markup was as follows:

The input <span class='qwicap-param-value'></span> is not a valid value for the field <span class='qwicap-label-text'></span>. Please fix it.

...then the error message that appeared above the form which supplied the parameter would end-up reading:

The input "42" is not a valid value for the field Wombat Burrow. Please fix it.

A side-effect of this feature, in which the error message is treated as an XHTML fragment, is that the error message string must not contain reserved characters like chevrons ('<' and '>') unless they are parts of properly formed XHTML tags. When including arbitrary strings in the error message, encode them using the htmlEncode method before incorporating them into the message.

Parameters:: ControlName - Name of the control whose input is being rejected.; ControlValue - The input that is being rejected. Can be null; see Form.getControl.; ErrorMsgIsXHTMLFragment - true if the ErrorMsg string contains XHTML markup. In this case, the string is not run through the htmlEncode method. If false, the string is encoded with htmlEncode, which prevents arbitrary strings from causing parsing exceptions, or being used in cross-site scripting attacks. Encoding of strings is part of the default behavior of the other rejectInput method, rejectInput(String, Object, Object), so using this method with ErrorMsgIsXHTMLFragment set to false is unnecessary; rejectInput(String, Object, Object) can be used instead.; ErrorMsg - Error message to be placed above the form. If this string is a valid XHTML fragment, set the parameter ErrorMsgIsXHTMLFragment to true. In all other cases, pass false.
Throws:: QwicapException - Always thrown by this method in order to restart the caller's input processing logic. (The Qwicap "prompt pattern" ensures this behavior on the part of the client.)

rejectInput

public void rejectInput(String ControlName,
                        Object ControlValue,
                        Object ErrorMsg)
                 throws QwicapException

If the ErrorMsg parameter is any subclass of Markup, and it contains one or more XML elements marked with the class "qwicap-label-text", the contents of those elements will be replaced with the labels of the form elements that supplied the rejected parameters. By the same token, the contents of elements marked with the class "qwicap-param-value" will be replaced with the values that are being rejected. For example, if a form element labelled "Wombat Burrow" was rejected, and the ErrorMsg markup was as follows:

The input <span class='qwicap-param-value'></span> is not a valid value for the field <span class='qwicap-label-text'></span>. Please fix it.

...then the error message that appeared above the form which supplied the parameter would end-up reading:

The input "42" is not a valid value for the field Wombat Burrow. Please fix it.

If the ErrorMsg parameter is of any other type, the rules documented in MutableMarkup.insert will be applied. (Strictly speaking, those rules always apply, even when the message is a subclass of Markup.)

Parameters:: ControlName - Name of the control whose input is being rejected.; ControlValue - The input that is being rejected. Can be null; see Form.getControl.; ErrorMsg - Error message to be placed above the form. This parameter can be any class of object. See MutableMarkup.insert for the specific rules employed in the handling of various classes.
Throws:: QwicapException - Always thrown by this method in order to restart the caller's input processing logic. (The Qwicap "prompt pattern" ensures this behavior on the part of the client.)

rejectInput

public void rejectInput(String[] ControlNames,
                        Object[] ControlValues,
                        Object ErrorMsg)
                 throws QwicapException

Marks the form controls that supplied the rejected input, inserts an error message immediately before the form, and sends the page containing the form back to the user for correction. All of the user's input is embedded into the form when it is sent back, so the user will not have to re-enter the form contents in order to correct the rejected input. The web application blocks when rejectInput is invoked, and unblocks only after potentially valid input is received from the user.

If the ErrorMsg parameter is of any type other than Markup, the rules documented in MutableMarkup.insert will be applied. (Strictly speaking, those rules always apply, even when the message is a subclass of Markup.)

Parameters:: ControlNames - Names of the controls whose input is being rejected.; ControlValues - The input values that are being rejected, in the same order as the names in the ControlNames array. This array must be the same length as the ControlNames array, or null. Any element of the array may also be null. Where null is encountered, the input from all form controls of the specified name is considered rejected, regardless of the particular values.; ErrorMsg - Error message to be placed above the form. This parameter can be any class of object. See MutableMarkup.insert for the specific rules employed in the handling of various classes.
Throws:: QwicapException - Always thrown by this method in order to restart the caller's input processing logic. (The Qwicap "prompt pattern" ensures this behavior on the part of the client.)

rejectInput

public void rejectInput(Object ErrorMsg)
                 throws QwicapException

Inserts an error message immediately before the form whose input was most recently submitted, and sends the page containing that form back to the user for correction. All of the user's input is embedded into the form when it is sent back, so the user will not have to re-enter the form contents in order to correct the rejected input. The web application blocks when rejectInput is invoked, and unblocks only after potentially valid input is received from the user.

If the ErrorMsg parameter is any subclass of Markup, it is inserted as-is. If the ErrorMsg parameter is not an instance of Markup, the rules documented in MutableMarkup.insert will be applied. (Strictly speaking, those rules always apply, even when the message is a subclass of Markup.)

Parameters:: ErrorMsg - Error message to be placed above the form. This parameter can be any class of object. See MutableMarkup.insert for the specific rules employed in the handling of various classes.
Throws:: QwicapException - Always thrown by this method in order to restart the caller's input processing logic. (The Qwicap "prompt pattern" ensures this behavior on the part of the client.)

redirect

public Qwicap redirect(String DestinationURL)
                throws QwicapException

Redirects the client to the specified URL, and blocks until the user returns to this web application.

Parameters:: DestinationURL - The URL to which the client should be redirected.
Returns:: A reference to this Qwicap instance, to facilitate method invocation chaining.
Throws:: QwicapException - If anything goes wrong.
See Also:: goodbye(String)

getForm

public Form getForm()
             throws FormNotFoundException

Returns a Form object which refers to the form that supplied the form data set most recently submitted to the current web page.

Returns:: A Form object referencing the form that supplied the current form data set, or null, if no such form can be identified.
Throws:: FormNotFoundException - If the form element has disappeared from the page markup.

getFormDataSet

public FormDataSet getFormDataSet()

Returns the form data set most recently submitted by the current web page.

Returns:: A FormDataSet object containing all of the input most recently submitted to the current web page, or null, if no input is available.

hasFormDataSet

public boolean hasFormDataSet()

Returns true if a form data set is available, false otherwise.

Returns:: true if a form data set is available, false otherwise.

has

public boolean has(String ControlName)

Returns true if the specified form control supplied one or more values in the current form data set, and false if it does not.

Parameters:: ControlName - Name of the form control.
Returns:: true if the control supplied one or more values in the current form data set, false otherwise.

get

public String get(String ControlName)

Returns the value of the specified form control as a String. Since this can only return one value, this method should not be used to retrieve the value of mutliple-selection form elements, for instance: groups of checkboxes, or "select"s whose "multiple" attribute is set.

Parameters:: ControlName - Name of the form control whose value is to be returned.
Returns:: The value supplied by the specified form control, or null, if it supplied no value.
See Also:: getAll(String), rejectInput(String, Object, Object)

getAll

public String[] getAll(String ControlName)

Returns the values of the specified form control as an array of Strings.

Parameters:: ControlName - Name of the form control whose values are to be returned.
Returns:: The values supplied by the specified form control as an array of String objects. If there are no values associated with that control, a zero-length array is returned.
See Also:: rejectInput(String, Object, Object)

setUploadedFileLimits

public Qwicap setUploadedFileLimits(int MaxSizeInRAM,
                                    long MaxSize,
                                    String RepositoryPath)

Specifies all the settings that affect the HTTP file upload functionality. By default, MaxSize and MaxSizeInRAM are set to the same value, because this makes RepositoryPath irrelevant. That's useful because there's no single value for RepositoryPath that will work across all platforms.

Parameters:: MaxSizeInRAM - The maximum size for uploaded files that are to be stored in memory; larger files will be stored on disk.; MaxSize - The maximum acceptable size of an uploaded file. Larger files will be rejected.; RepositoryPath - The directory in which uploaded files are to be stored when they are too large to be stored in memory. This parameter can be null when MaxSizeInRAM equals MaxSize, since all uploads will be stored in memory.
Returns:: A reference to this Qwicap instance, to facilitate method invocation chaining.
See Also:: FileItem.delete()

getUploadedFileRAMLimit

public int getUploadedFileRAMLimit()

Returns the maximum size of an uploaded file that will be memory-resident; larger files will be stored on disk (see getUploadedFileRepository()), while files beyond a certain size won't be accepted at all (see getUploadedFileSizeLimit()).

Returns:: The maximum size of uploaded files that will be stored in memory.
See Also:: setUploadedFileLimits(int, long, String)

getUploadedFileSizeLimit

public long getUploadedFileSizeLimit()

Returns the maximum acceptable size of an uploaded file. Larger files are rejected.

Returns:: The maximum acceptable size of an uploaded file.
See Also:: setUploadedFileLimits(int, long, String)

getUploadedFileRepository

public String getUploadedFileRepository()

Returns the path of the directory in which uploaded files are stored when they are too large to be stored in memory; see getUploadedFileRAMLimit().

Returns:: Path of the directory which is the repository for uploaded files.
See Also:: setUploadedFileLimits(int, long, String), FileItem.delete()

getUploadedFile

public FileItem getUploadedFile(String ControlName,
                                String ContentType,
                                boolean AllowedToBeMissing)
                         throws QwicapException

Returns a FileItem object describing the uploaded file associated with a specified control name. If the file is absent, and the AllowedToBeMissing parameter is false, the XHTML page is sent back to the user with a message describing the problem, and this method blocks until the user eventually uploads a file.

Parameters:: ControlName - Name of the form control associated with the uploaded file.; ContentType - The required MIME content type for the uploaded file, or null if all types are acceptable. If the uploaded file is not of the required type, the file is deleted, and the user is prompted to supply a file of the required type.; AllowedToBeMissing - true, if it's OK to return null when no file has been uploaded. If false, and no file has been uploaded, the user is automatically requested to upload a file, and this method blocks until a file is uploaded.
Returns:: A FileItem object representing the uploaded file.
Throws:: QwicapException - If anything goes wrong.
See Also:: setUploadedFileLimits(int, long, String), FileItem.delete()

getUploadedFile

public FileItem getUploadedFile(String ControlName,
                                String[] ContentTypes,
                                boolean AllowedToBeMissing)
                         throws QwicapException

Parameters:: ControlName - Name of the form control associated with the uploaded file.; ContentTypes - A list of MIME content types that are acceptable, or null if all types are acceptable. If the uploaded file is not of an acceptable type, the file is deleted, and the user is prompted to supply a file of one of the acceptable types.; AllowedToBeMissing - true, if it's OK to return null when no file has been uploaded. If false, and no file has been uploaded, the user is automatically requested to upload a file, and this method blocks until a file is uploaded.
Returns:: A FileItem object representing the uploaded file.
Throws:: QwicapException - If anything goes wrong.
See Also:: setUploadedFileLimits(int, long, String), FileItem.delete()

getBoolean

public boolean getBoolean(String ControlName,
                          boolean AllowedToBeBlank,
                          boolean DefaultValue)
                   throws QwicapException

Returns the value of the specified control as a boolean primitive. If the value supplied by the user is invalid, absent, or isn't one of the two acceptable values, the XHTML page is sent back to the user with a message describing the problem, and this method blocks until the user eventually supplies a valid value.

Parameters:: ControlName - Name of the form control whose value is to be returned.; AllowedToBeBlank - true if the input can be missing or blank.; DefaultValue - Value to return if AllowedToBeBlank is true, and the input was missing or blank.
Returns:: The value of the form control represented as a boolean.
Throws:: QwicapException - If anything goes wrong.

getBoolean

public boolean getBoolean(String ControlName,
                          String TrueStr,
                          String FalseStr,
                          boolean AllowedToBeBlank,
                          boolean DefaultValue)
                   throws QwicapException

Parameters:: ControlName - Name of the form control whose value is to be returned.; TrueStr - Value to be interpreted as true.; FalseStr - Value to be interpreted as false.; AllowedToBeBlank - true if the input can be missing or blank.; DefaultValue - Value to return if AllowedToBeBlank is true, and the input was missing or blank.
Returns:: The value of the form control represented as a boolean.
Throws:: QwicapException - If anything goes wrong.

getInt

public int getInt(String ControlName,
                  int MinValue,
                  int MaxValue,
                  boolean AllowedToBeBlank,
                  int DefaultValue)
           throws QwicapException

Returns the value of the specified control as an int. If the value supplied by the user is invalid, absent, or falls outside the range of acceptable values, the XHTML page is sent back to the user with a message describing the problem, and this method blocks until the user eventually supplies a valid value.

If you want to further constrain the acceptable values of this control, evaluate the value returned by this method and, if it does not meet your constraints, invoke the rejectInput method. Repeat as necessary, until you get a value that satisfies your constraints.

Parameters:: ControlName - Name of the form control whose value is to be returned.; MinValue - Minimum acceptable value of the control (inclusive).; MaxValue - Maximum acceptable value of the control (inclusive).; AllowedToBeBlank - true if the input can be missing or blank.; DefaultValue - Value to return if AllowedToBeBlank is true, and the input was missing or blank. Note that this value need not be between MinValue and MaxValue. Also, if AllowedToBeBlank is false, you may pass null for this parameter.
Returns:: The value of the form control represented as an int.
Throws:: QwicapException - If anything goes wrong.

getLong

public long getLong(String ControlName,
                    long MinValue,
                    long MaxValue,
                    boolean AllowedToBeBlank,
                    long DefaultValue)
             throws QwicapException

Returns the value of the specified control as a long. If the value supplied by the user is invalid, absent, or falls outside the range of acceptable values, the XHTML page is sent back to the user with a message describing the problem, and this method blocks until the user eventually supplies a valid value.

Parameters:: ControlName - Name of the form control whose value is to be returned.; MinValue - Minimum acceptable value of the control (inclusive).; MaxValue - Maximum acceptable value of the control (inclusive).; AllowedToBeBlank - true if the input can be missing or blank.; DefaultValue - Value to return if AllowedToBeBlank is true, and the input was missing or blank. Note that this value need not be between MinValue and MaxValue. Also, if AllowedToBeBlank is false, you may pass null for this parameter.
Returns:: The value of the form control represented as a long.
Throws:: QwicapException - If anything goes wrong.

getBigInteger

public BigInteger getBigInteger(String ControlName,
                                BigInteger MinValue,
                                BigInteger MaxValue,
                                boolean AllowedToBeBlank,
                                BigInteger DefaultValue)
                         throws QwicapException

Returns the value of the specified control as a BigInteger. If the value supplied by the user is invalid, absent, or falls outside the range of acceptable values, the XHTML page is sent back to the user with a message describing the problem, and this method blocks until the user eventually supplies a valid value.

Parameters:: ControlName - Name of the form control whose value is to be returned.; MinValue - Minimum acceptable value of the control (inclusive).; MaxValue - Maximum acceptable value of the control (inclusive).; AllowedToBeBlank - true if the input can be missing or blank.; DefaultValue - Value to return if AllowedToBeBlank is true, and the input was missing or blank. Note that this value need not be between MinValue and MaxValue. Also, if AllowedToBeBlank is false, you may pass null for this parameter.
Returns:: The value of the form control represented as a BigInteger.
Throws:: QwicapException - If anything goes wrong.

getFloat

public float getFloat(String ControlName,
                      float MinValue,
                      float MaxValue,
                      boolean AllowedToBeBlank,
                      float DefaultValue)
               throws QwicapException

Returns the value of the specified control as a float. If the value supplied by the user is invalid, absent, or falls outside the range of acceptable values, the XHTML page is sent back to the user with a message describing the problem, and this method blocks until the user eventually supplies a valid value.

Parameters:: ControlName - Name of the form control whose value is to be returned.; MinValue - Minimum acceptable value of the control (inclusive).; MaxValue - Maximum acceptable value of the control (inclusive).; AllowedToBeBlank - true if the input can be missing or blank.; DefaultValue - Value to return if AllowedToBeBlank is true, and the input was missing or blank. Note that this value need not be between MinValue and MaxValue. Also, if AllowedToBeBlank is false, you may pass null for this parameter.
Returns:: The value of the form control represented as a float.
Throws:: QwicapException - If anything goes wrong.

getDouble

public double getDouble(String ControlName,
                        double MinValue,
                        double MaxValue,
                        boolean AllowedToBeBlank,
                        double DefaultValue)
                 throws QwicapException

Returns the value of the specified control as a double. If the value supplied by the user is invalid, absent, or falls outside the range of acceptable values, the XHTML page is sent back to the user with a message describing the problem, and this method blocks until the user eventually supplies a valid value.

Parameters:: ControlName - Name of the form control whose value is to be returned.; MinValue - Minimum acceptable value of the control (inclusive).; MaxValue - Maximum acceptable value of the control (inclusive).; AllowedToBeBlank - true if the input can be missing or blank.; DefaultValue - Value to return if AllowedToBeBlank is true, and the input was missing or blank. Note that this value need not be between MinValue and MaxValue. Also, if AllowedToBeBlank is false, you may pass null for this parameter.
Returns:: The value of the form control represented as a double.
Throws:: QwicapException - If anything goes wrong.

getBigDecimal

public BigDecimal getBigDecimal(String ControlName,
                                BigDecimal MinValue,
                                BigDecimal MaxValue,
                                boolean AllowedToBeBlank,
                                BigDecimal DefaultValue)
                         throws QwicapException

Returns the value of the specified control as a BigDecimal. If the value supplied by the user is invalid, absent, or falls outside the range of acceptable values, the XHTML page is sent back to the user with a message describing the problem, and this method blocks until the user eventually supplies a valid value.

Parameters:: ControlName - Name of the form control whose value is to be returned.; MinValue - Minimum acceptable value of the control (inclusive).; MaxValue - Maximum acceptable value of the control (inclusive).; AllowedToBeBlank - true if the input can be missing or blank.; DefaultValue - Value to return if AllowedToBeBlank is true, and the input was missing or blank. Note that this value need not be between MinValue and MaxValue. Also, if AllowedToBeBlank is false, you may pass null for this parameter.
Returns:: The value of the form control represented as a BigDecimal.
Throws:: QwicapException - If anything goes wrong.

getInts

public int[] getInts(String ControlName,
                     int MinValue,
                     int MaxValue,
                     boolean AllowedToBeBlank,
                     int[] DefaultValues)
              throws QwicapException

Returns the values of the specified controls as int primitives. If any of the values supplied by the user are invalid, absent, or fall outside the range of acceptable values, the XHTML page is sent back to the user with a message describing the problem, and this method blocks until the user eventually supplies valid values.

If you want to further constrain the acceptable values of these controls, evaluate the values returned by this method and, if they do not meet your constraints, invoke the rejectInput method. Repeat as necessary, until you get a value that satisfies your constraints.

Parameters:: ControlName - Name of the form control whose value is to be returned.; MinValue - Minimum acceptable value of the control (inclusive).; MaxValue - Maximum acceptable value of the control (inclusive).; AllowedToBeBlank - true if the input can be missing or blank.; DefaultValues - Values to return if AllowedToBeBlank is true, and the inputs were missing or blank. Note that this value need not be between MinValue and MaxValue. Also, if AllowedToBeBlank is false, you may pass null for this parameter.
Returns:: The values of these form controls represented as an array of int primitives.
Throws:: QwicapException - If anything goes wrong.

getLongs

public long[] getLongs(String ControlName,
                       long MinValue,
                       long MaxValue,
                       boolean AllowedToBeBlank,
                       long[] DefaultValues)
                throws QwicapException

Returns the values of the specified controls as long primitives. If any of the values supplied by the user are invalid, absent, or fall outside the range of acceptable values, the XHTML page is sent back to the user with a message describing the problem, and this method blocks until the user eventually supplies valid values.

Parameters:: ControlName - Name of the form control whose value is to be returned.; MinValue - Minimum acceptable value of the control (inclusive).; MaxValue - Maximum acceptable value of the control (inclusive).; AllowedToBeBlank - true if the input can be missing or blank.; DefaultValues - Values to return if AllowedToBeBlank is true, and the inputs were missing or blank. Note that this value need not be between MinValue and MaxValue. Also, if AllowedToBeBlank is false, you may pass null for this parameter.
Returns:: The values of these form controls represented as an array of long primitives.
Throws:: QwicapException - If anything goes wrong.

getBigIntegers

public BigInteger[] getBigIntegers(String ControlName,
                                   BigInteger MinValue,
                                   BigInteger MaxValue,
                                   boolean AllowedToBeBlank,
                                   BigInteger[] DefaultValues)
                            throws QwicapException

Returns the values of the specified controls as BigInteger objects. If any of the values supplied by the user are invalid, absent, or fall outside the range of acceptable values, the XHTML page is sent back to the user with a message describing the problem, and this method blocks until the user eventually supplies valid values.

Parameters:: ControlName - Name of the form control whose value is to be returned.; MinValue - Minimum acceptable value of the control (inclusive).; MaxValue - Maximum acceptable value of the control (inclusive).; AllowedToBeBlank - true if the input can be missing or blank.; DefaultValues - Values to return if AllowedToBeBlank is true, and the inputs were missing or blank. Note that this value need not be between MinValue and MaxValue. Also, if AllowedToBeBlank is false, you may pass null for this parameter.
Returns:: The values of these form controls represented as an array of BigInteger objects.
Throws:: QwicapException - If anything goes wrong.

getFloats

public float[] getFloats(String ControlName,
                         float MinValue,
                         float MaxValue,
                         boolean AllowedToBeBlank,
                         float[] DefaultValues)
                  throws QwicapException

Returns the values of the specified controls as float primitives. If any of the values supplied by the user are invalid, absent, or fall outside the range of acceptable values, the XHTML page is sent back to the user with a message describing the problem, and this method blocks until the user eventually supplies valid values.

Parameters:: ControlName - Name of the form control whose value is to be returned.; MinValue - Minimum acceptable value of the control (inclusive).; MaxValue - Maximum acceptable value of the control (inclusive).; AllowedToBeBlank - true if the input can be missing or blank.; DefaultValues - Values to return if AllowedToBeBlank is true, and the inputs were missing or blank. Note that this value need not be between MinValue and MaxValue. Also, if AllowedToBeBlank is false, you may pass null for this parameter.
Returns:: The values of these form controls represented as an array of float primitives.
Throws:: QwicapException - If anything goes wrong.

getDoubles

public double[] getDoubles(String ControlName,
                           double MinValue,
                           double MaxValue,
                           boolean AllowedToBeBlank,
                           double[] DefaultValues)
                    throws QwicapException

Returns the values of the specified controls as double primitives. If any of the values supplied by the user are invalid, absent, or fall outside the range of acceptable values, the XHTML page is sent back to the user with a message describing the problem, and this method blocks until the user eventually supplies valid values.

Parameters:: ControlName - Name of the form control whose value is to be returned.; MinValue - Minimum acceptable value of the control (inclusive).; MaxValue - Maximum acceptable value of the control (inclusive).; AllowedToBeBlank - true if the input can be missing or blank.; DefaultValues - Values to return if AllowedToBeBlank is true, and the inputs were missing or blank. Note that this value need not be between MinValue and MaxValue. Also, if AllowedToBeBlank is false, you may pass null for this parameter.
Returns:: The values of these form controls represented as an array of double primitives.
Throws:: QwicapException - If anything goes wrong.

getBigDecimals

public BigDecimal[] getBigDecimals(String ControlName,
                                   BigDecimal MinValue,
                                   BigDecimal MaxValue,
                                   boolean AllowedToBeBlank,
                                   BigDecimal[] DefaultValues)
                            throws QwicapException

Returns the values of the specified controls as BigDecimal objects. If any of the values supplied by the user are invalid, absent, or fall outside the range of acceptable values, the XHTML page is sent back to the user with a message describing the problem, and this method blocks until the user eventually supplies valid values.

Parameters:: ControlName - Name of the form control whose value is to be returned.; MinValue - Minimum acceptable value of the control (inclusive).; MaxValue - Maximum acceptable value of the control (inclusive).; AllowedToBeBlank - true if the input can be missing or blank.; DefaultValues - Values to return if AllowedToBeBlank is true, and the inputs were missing or blank. Note that this value need not be between MinValue and MaxValue. Also, if AllowedToBeBlank is false, you may pass null for this parameter.
Returns:: The values of these form controls represented as an array of BigDecimal objects.
Throws:: QwicapException - If anything goes wrong.

getString

public String getString(String ControlName,
                        int MinLength,
                        int MaxLength,
                        boolean Trim)
                 throws QwicapException

Returns the value of the specified parameter as a String. If the value supplied by the user is too long, or too short, the XHTML page is sent back to the user with a message describing the problem, and this method blocks until the user eventually supplies a valid value.

If you want to further constrain the acceptable values of this control, evaluate the value returned by this method and if it does not meet your constraints, invoke the rejectInput method. Repeat as necessary, until you get a value that satisfies your constraints.

Parameters:: ControlName - Name of the form control whose value is to be returned.; MinLength - Minimum acceptable length of input, after optional trimming is performed.; MaxLength - Maximum acceptable length of input, after optional trimming is performed.; Trim - true if leading and trailing white space should be removed from the input string.
Returns:: The value of the specified control, after optional trimming, if it met all of the length and pattern requirements.
Throws:: QwicapException - If anything goes wrong.
See Also:: get(String)

getString

public String getString(String ControlName,
                        int MinLength,
                        int MaxLength,
                        boolean Trim,
                        String ValidatorRegex,
                        Object ValidatorRegexErrorMsg)
                 throws QwicapException

Returns the value of the specified control as a String. If the value supplied by the user is too long, too short, or fails to conform to the specified pattern, the XHTML page is sent back to the user with a message describing the problem, and this method blocks until the user eventually supplies a valid value.

Parameters:: ControlName - Name of the form control whose value is to be returned.; MinLength - Minimum acceptable length of input, after optional trimming is performed.; MaxLength - Maximum acceptable length of input, after optional trimming is performed.; Trim - true if leading and trailing white space should be removed from the input string.; ValidatorRegex - null, or a regular expression defining the acceptable pattern for the input string.; ValidatorRegexErrorMsg - null, or an error message to be displayed when the string does not conform to the pattern specified by the regular expression. If the error message object is a subclass of Markup, it is inserted into the web page as-is. If the error message is any other type of object, it is converted to a String, and HTML encoded before it is inserted.
Returns:: The value of the specified control, after optional trimming, if it met all of the length and pattern requirements.
Throws:: QwicapException - If anything goes wrong.
See Also:: get(String)

createDownloadable

public Downloadable createDownloadable(String Name,
                                       String MIMEType,
                                       byte[] Contents)

Creates an instance of Downloadable to store the information triplet representing any downloadable item: name, MIME type, and content bytes. Creating an instance of Downloadable does cause a unique, relative URI to be assigned to the instance, but does not instruct Qwicap to make it available for download. That is done by invoking Qwicap.addDownloadable.

Parameters:: Name - The name of this downloadable, for example: "myimage.jpg".; MIMEType - The MIME type of this downloadable, for example: "image/jpeg".; Contents - The contents of this download, represented as the array of bytes that will be trasmitted to the client.
Returns:: The new instance of Downloadable.

addDownloadable

public String addDownloadable(String Name,
                              byte[] Contents)

Associates a new downloadable item with the web page specified in the next prompt invocation. If that page already has a downloadable item of the same name, this item will replace it, and the previous item will become available for garbage collection. Note that this item is assigned a new URI, even if it replaces a previous item of the same name, so any links in the document will still have to be updated. When the page is no longer in-play, all downloadable items associated with it will be made available for garbage collection.

The MIME type of the item is inferred from its name, using the ServletContext.getMimeType(java.lang.String) method. Because the outcome of the this inference is determined by the configuration of the underlying servlet engine, it will always be more dependable to explicity specify the MIME type using the addDownloadable(String, String, byte[]) method.

Parameters:: Name - The name to be given to this download, for example "mypicture.jpg".; Contents - The contents of this download, represented as the array of bytes that will be trasmitted to the client.
Returns:: A relative URI for this downloadable item. Use this URI as the link to this item.

addDownloadable

public String addDownloadable(String Name,
                              String MIMEType,
                              byte[] Contents)

Parameters:: Name - The name to be given to this download, for example "mypicture.jpg".; MIMEType - The MIME type of the this download, for example "image/jpeg".; Contents - The contents of this download, represented as the array of bytes that will be trasmitted to the client.
Returns:: A relative URI for this downloadable item. Use this URI as the link to this item.

addDownloadable

public Downloadable addDownloadable(Downloadable Download)

Parameters:: Download - A Downloadable object to be made available for download.
Returns:: A relative URI for this downloadable item. Use this URI as the link to this item.

htmlEncode

public static String htmlEncode(String RawStr)

Encodes a string such that it can be safely embedded in an XHTML document without risk of the document's syntax being corrupted, or the contents of the string being interpreted as XHTML markup (a potential security hole).

Parameters:: RawStr - The string to be encoded.
Returns:: A string with all reserved characters encoded, or the original string object if no encoding was necessary.

htmlDecode

public static String htmlDecode(String PotentiallyEncodedStr)

Decodes a string such any HTML character entities in it are translated into corresponding Unicode characters.

Parameters:: PotentiallyEncodedStr - The string to be decoded.
Returns:: A string with all HTML characters entities decoded into corresponding Unicode characters.

populateMostRecentForm

public Qwicap populateMostRecentForm()
                              throws TagException,
                                     FormNotFoundException

Takes the form data set most recently received from the client and embeds it into the XHTML markup of the form from which it originated in the current page. This happens automatically when input is rejected by one of the "get" methods, or when rejectInput is called. If there is no most-recent-form, this method does nothing.

Returns:: A reference to this Qwicap instance, to facilitate method invocation chaining.
Throws:: TagException - If there was a problem with the manipulation of the page markup.; FormNotFoundException - If the form element has disappeared from the markup.

clearMostRecentForm

public Qwicap clearMostRecentForm()
                           throws TagException,
                                  FormNotFoundException

Removes all values from the XHTML markup of the form in the current page from which input was most recently received. If there is no most-recent-form, this method does nothing.

Returns:: A reference to this Qwicap instance, to facilitate method invocation chaining.
Throws:: TagException - If there was a problem with the manipulation of the page markup.; FormNotFoundException - If the form element has disappeared from the markup.

goodbye

public Qwicap goodbye(Markup PageMarkup)
               throws QwicapException

Sends the final XHTML page of this session to the user, and returns without waiting for input from the user. (Since it's the end of the session, there would be no point in the final page including a form that supplies any input, and therefore there's no need to worry about the possibility of input.) Any further attempts by the application to retrieve input, send pages to the user, or to act like this session is still in progress will cause QwicapSessionDeathExceptions to be thrown.

Parameters:: PageMarkup - Final XHTML page to be sent to the user.
Returns:: A reference to this Qwicap instance, to facilitate method invocation chaining.
Throws:: QwicapException - If anything went wrong.

goodbye

public Qwicap goodbye(String ContentType,
                      byte[] Data)
               throws QwicapException

Sends the final item of this session to the user, and returns without waiting for input from the user. Any further attempts by the application to retrieve input, send pages to the user, or to act like this session is still in progress will cause QwicapSessionDeathExceptions to be thrown.

Parameters:: ContentType - MIME type of data to be sent to client. Examples: "image/jpeg", "image/svg+xml; charset=UTF-8".; Data - The data to be sent to the client. If the data is text, it must already be encoded in the character set specified in the ContentType parameter.
Returns:: A reference to this Qwicap instance, to facilitate method invocation chaining.
Throws:: QwicapException - If anything went wrong.

goodbye

public Qwicap goodbye(Downloadable Download)
               throws QwicapException

Parameters:: Download - A Downloadable to sent to the client.
Returns:: A reference to this Qwicap instance, to facilitate method invocation chaining.
Throws:: QwicapException - If anything went wrong.

goodbye

public Qwicap goodbye(String RedirectURL)
               throws QwicapException

Redirects to the client to an arbitrary URL, and returns immediately. Any further attempts by the application to retrieve input, send pages to the user, or to act like this session is still in progress will cause QwicapSessionDeathExceptions to be thrown.

Parameters:: RedirectURL - The URL to which the client should be redirected.
Returns:: A reference to this Qwicap instance, to facilitate method invocation chaining.
Throws:: QwicapException - If anything went wrong.
See Also:: redirect(String)

printPageStack

public Qwicap printPageStack()

Prints to the console a summary of Qwicap's internal page stack as an aid to understanding Qwicap's automatic page stack maintenance.

Returns:: A reference to this instance of the Qwicap class.

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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

getVersionString

getStatusReport

getStatusReport

getRandom

getCurrentInstance

getContext

getUserAgent

getAuth2SchemeReply

geti18nServicesForClass

getScriptsEnabled

setScriptsEnabled

addBlockingListener

removeBlockingListener

setInputFilter

invokeInputFilter

getInputFilter

getDocument

getDocument

toString

reportProblem

reportProblem

reportException

convertSubmitButtonsToInputs

showPage

promptComplete

prompt

prompt

rejectInput

rejectInput

rejectInput

rejectInput

redirect

getForm

getFormDataSet

hasFormDataSet

has

get

getAll

setUploadedFileLimits

getUploadedFileRAMLimit

getUploadedFileSizeLimit

getUploadedFileRepository

getUploadedFile

getUploadedFile

getBoolean

getBoolean

getInt

getLong

getBigInteger

getFloat

getDouble

getBigDecimal

getInts

getLongs

getBigIntegers

getFloats

getDoubles

getBigDecimals

getString

getString

createDownloadable

addDownloadable

addDownloadable

addDownloadable

htmlEncode

htmlDecode

populateMostRecentForm

clearMostRecentForm

goodbye

goodbye

goodbye

goodbye

printPageStack

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