Download the
JavaForms.zip archive.
Copy the folder into your NetBeansProjects folder.
After some discussion and preparation
we will install it as a Web Application with Existing Sources.
NetBeans Commons/Lang Library
This and other Web projects which use and display text input
rely on the ability to escape the text input for display with
HTML (see below). The standard Java distribution provide no function which
does this, but it is provided in the
Apache Commons/Lang Java distribution at:
Decide on a permanent location for these three files.
Possiblities are these:
on Windows, using
My Documents\
as a base
My Documents\java\commons-lang-2.4.jar
My Documents\src\commons-lang-2.4-sources.jar
My Documents\docs\commons-lang-2.4-javadoc.jar
on Linux/Mac, using
~/lib
as a base
~/lib/java/commons-lang-2.4.jar
~/lib/src/commons-lang-2.4-sources.jar
~/lib/docs/commons-lang-2.4-javadoc.jar
In NetBeans, go to Tools Libraries
and click the New Library button (bottom, left). In
the Library Name, type CommonsLang.
Then add, via the three tabs using the Add ... button:
Classpath tab: navigate to the location of
commons-lang-2.4.jar.
Sources tab: navigate to the location of
commons-lang-2.4-sources.jar.
Javadoc tab:
the Add button indicates a ZIP file, but a JAR file is a ZIP file;
navigate to the location of
commons-lang-2.4-javadoc.jar
And we're done.
Installation/Execution of JavaForms in NetBeans
Extract the JavaForms.zip archive as the directory
JavaForms in the NetBeans project folder.
Create a new Web Project as Web Application with Existing Source.
In the Location field of the next popup, Browse to
JavaForms in the NetBeans project folder.
Everything else should probably be as is. Click Next.
Click Finish in the next popup.
Right-click on the Libraries entry
in the JavaForms project. Select Add Library and
choose CommonsLang.
Run the project (the Run button should work).
Web-based applications
Java has the ability to create a dynamic
web page by obtaining non-static information, say from a database,
and presenting this to the user.
The user then interacts with this program-generated
web page and further dynamic web pages are created.
The user interacts with a web page presenting HTML
form elements and/or hyperlinks.
After making choices and/or clicking some
element (like a button), data is submitted to another
program (possibly the same one which generated the original form)
which then generates the next web page, and so on.
Web-based applications have a very different style than, say,
Java Swing-based GUI applications. They are event-driven, as indicated,
but not thought of as a single program, rather a series of
programs which start and terminate for each page generated.
Even though it's not technically correct,
the term stateless applies to web applications due to the fact
that they are not a single program running.
The other major difference with web applications is that the activations
normally are stacked.
This is what the "Back" button in the browser is all about:
keeping of a history with the ability to go back to previous activations.
This feature has both good points and bad points. Say, for example, a
web activation represents a "one-time" transaction, like deleting
a database record. The notion of going back to that activation
is error-prone at best.
One of the features of AJAX-based web applications is the ability
to make efficient server-side executions which
browser refreshing, and thus avoid stacking.
Such a style makes a Web application appear more like
other non web-based GUI applications.
Hyperlink activations
The default hyperlink activation is based on HTML code which looks
like this:
<a href="some-url">some description</a>
Hyperlink activations can be made to do other actions by replacing
the URL by a JavaScript call:
<a href="javascript:javascript-code">.....</a>
The above hyperlink's activation
is equivalent to this usage with the JavaScript location object:
User-generated web data is transmitted as a list
of parameters and values in a data string like this:
name1=value1&name2=value2&...
where name1, name2, etc., typically correspond
to the names of the form elements.
The values are (typically) generated by the user
by text entry or selecting from various choices.
A parameter name can appear
more than once, in which case it is called multi-valued,
otherwise, it is single-valued.
GET/POST queries
A GET request to a server-side script is one which sends
this parameter data string attached to the script's URL in the
form of a query string following a ? after the script
name:
http://.../SCRIPT?name1=value1&name2=value2&...
A POST request is one which sends this parameter
string to the script through standard input
When to use GET vs. POST
There are reasons for choosing to use GET or POST queries:
GET queries are simpler to understand and debug
by virtue of the data being part of the URL.
GET queries are thus more easily "repeatable."
Users can easily bookmark GET queries and
thereby remember and communicate web "finds" in through them.
For security reasons, some servers do not want to permit
handling data through POST requests; so if you're sending form
information to an external server (over which you have no control),
it's best to use GET.
POST queries, by virtue of sending data through standard output, and
not through the URL, are more secure for password entry, etc. Additionally,
POST queries permit larger amounts of data to be transmitted, say, as
documents loaded in a text area or via file upload.
GET method is the method used by standard hyperlink activations.
GET method is the default used by an HTML form (see below).
Nevetheless, web-based applications generally prefer POST for form
data transmission.
Keep in mind that a GET query is "visible" and "repeatable"
because the query is stored
in the URL. Thus:
Web activations which have side effects, such as update, add, delete
of data should be POST queries.
Web activations which involve transmission of sensitive data, such as
passwords, should be POST queries.
Web activations which involve transmission of large amounts of
data (file uploads, document submissions) should be POST queries.
Web activations which generate the search/display of data should
be GET queries.
Processing parameters
The doGet and doPost methods, which handle browser requests,
use these parameters:
The request parameter is used for input (typically the parameters from
the browser request) and response is used for output sent back to the
browser.
The javax.servlet.http.HttpServletRequest
class inherits most of the functionality
you'll use from the javax.servlet.ServletRequest class.
The ones I most frequently used are these:
String request.getParameter("name"): retrieve value
of a specific (single-valued) parameter of given name.
String[] request.getParameterValues("name") retrieve
the array of all values of a parameter of given name.
If there are no parameters for a given name,
the null value is returned.
Below is the ShowParams servlet which can be used to
see the immediate effects of receiving get inputs through the
query string. The example itself contains a description of how
to test it by adding query strings.
params.jsp
<%@page contentType="text/html" pageEncoding="UTF-8"%>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Parameters</title>
</head>
<body>
<h2>Parameters</h2>
In the browser location field, tack on a query string with
parameter/value pairs like these:
<pre> ?a=1 ?a=1&b=2 ?a=1&b=2&a=3</pre>
and view the results below.
<hr />
<h4>number of parameters: <%=request.getParameterMap().size()%></h4>
<h4>values</h4>
<%
java.util.Enumeration names = request.getParameterNames();
while (names.hasMoreElements()) {
String param = (String) names.nextElement();
%>
parameter: <%=param%><br />
value: <%=request.getParameter(param)%><br />
values:
<%=java.util.Arrays.toString(request.getParameterValues(param))%>
<br /><br />
<%
}
%>
</body>
</html>
This example uses the request.getParameterMap() to obtain
a list of all the parameters. In reality, this is rarely needed
because we usually have an expectation of which parameter names
are going to be used.
The web server environment
The web server environment constitutes all the dynamic information
which a server-side program has access to. This includes the
parameter information plus other information regarding who is
accessing this page with what request, etc. Java makes this information
available via the request parameter through a variety
of member functions including these:
getHeader(str) = attribute information from the HTTP header
getQueryString() = portion of URL following the ?; input to a script
getServletPath() = the full path of the servlet
getContextPath() = my context (web app name)
getRequestURL() = the activing URL without query string
getRequestURI() = the full URL with query string
getRemoteAddr() = the IP address of the "caller"
A simple servlet which prints out some of these values is this:
<form action="PROGRAM" method="METHOD" target="TARGET">
<!-- form elements -->
</form>
where
PROGRAM is what is called when the form is submitted;
this is some type of program which will process the information
sent through form parameters
METHOD is either GET (parameters passed through query string in URL)
or POST (parameters passed through standard input)
TARGET indicates where the action SCRIPT
will display. The default is to display in the frame containing
the form but can be targetted to a different frame; there
are 4 predefined targets:
_blank: always to a new browser window
_parent: the parent in a frameset
_self: the window/frame containing the form (this is the default)
_top: the top in a frameset
Form Components
The HTML form components provide the user interface. They consist of
buttons: used to submit the form.
textfields and password fields: single line inputs
textareas: multi-line inputs
check boxes and radio buttons:
allow the user to say yes/no to a choice, or one of several choices.
selection lists: these give a choice through a popup or
scroll list
The elements use attributes specific to the element to change the
appearance or behavior.
Certain attributes, called boolean attributes, have no value and
are activated simply be being present.
For example,
any form element can be disabled by using
the boolean attribute
disabled
Using the disabled attribute
typically "grays out" the element and makes it unusable, with
the content still visible.
JavaScript attributes
These mouse and keyboard JavaScript event attributes
take JavaScript code as their values. They can be used to
modify the form-handling behavior, for example, by calling the
JavaScript "submit()" value:
onclick
mouse clicked in element
ondblclick
mouse double-clicked in element
onmousedown/onmouseup
mouse pressed/released in element
onmouseover
mouse over element
onmouseout
mouse not over element
onmousemove
mouse position changed within element
onkeydown/onkeyup
a key was pressed/released
onkeypress
a key was pressed, then released
onfocus/onblur
element acquires/loses focus by mouse click or tabbing
onselect
text selected in a textfield or textarea
onchange
value has been modified
(for input, select, textarea )
Text Elements, Buttons, Hidden inputs
Text elements different from other form components in that the
user determines the value associated with a parameter name.
The HTML input element is used to create a variety
of different components including textfields, buttons,
hidden inputs, checkboxes, radio buttons, etc.
The input element has the form:
where the NAME identifies the parameter name
passed to the action script.
These are also used to control behavior ot textfields and textareas:
readonly: boolean attribute for textfields
size: integer for textfields
maxlength: integer: maximum number chars for textfields
tabindex: integer position in tabbing order
Displaying User Input
When you want to display user-generated input in a target script,
you have to deal with the fact
that this input may contain certain HTML-special characters,
in particular these:
"<",
"&",
""",
">".
There are are possiblities:
leave the characters alone, assuming that the input is
to be rendered as HTML
translate the characters into HTML special sequences
< <
& &
" "
> >
so that they are rendered literally
For most part we want the latter choice, and
towards this end we use the
Java function from the Commons/Lang
package:
A form need not be activated by the pressing of a button. But if
it is, the easiest way to know that the form was activated
is to see a non-null value of a named button.
A hidden input name/value combination is one that doesn't show
in any explicit way. These often offer a way of maintaining the
"state" by passing a value from one form to another.
Sample form and handler
The HTML file text.html is a form with basic text components
which also illustrates other features such as buttons
and hidden parameters.
The handler is the servlet TextHandler.java.
as indicated in the script, try the "problematic" inputs
with both buttons to see why we need to use
StringEscapeUtils.escapeHtml
add method="post" in the
form start tag, rerun and observe the difference.
text.jsp
<%@page contentType="text/html" pageEncoding="UTF-8"%>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<%
String file = new java.io.File(request.getRequestURI()).getName();
String title = "Text with external handler (" + file + ")";
%>
<html>
<head>
<title><%= title %></title>
<link rel="stylesheet" href="css/entry.css" type="text/css" />
<style type="text/css">
table.entry td.left { width: 90px; }
</style>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body>
<h2><%= title %></h2>
<blockquote class="feedback">
Try these "torture" values using both submit buttons:<br />
<tt>tf: a<b>c"d<br />
ta: a</textarea>b<br /></tt>
</blockquote>
<form action="TextHandler">
<table class="entry">
<tr>
<td class="left">text field (<b>tf</b>):</td>
<td><input type="text" class="text" name="tf"/></td>
</tr>
<tr valign="top">
<td class="left">text area (<b>ta</b>):</td>
<td>
<!-- no whitespace between start & end tags -->
<textarea name="ta" rows="10"></textarea>
</td>
</tr>
</table>
<input type="submit" name="raw_button" value="submit (raw)"/>
<input type="submit" name="escaped_button" value="submit (escaped)"/>
</form>
</body>
</html>
Selection elements are those where we are presented with
a limited number of choices from which we can choose one or
more values.
The HTML elements which provide these choices are checkboxes,
radio buttons and selection lists.
In most situation
we have control over the values generated by these elements which
stands in contrast to the text elements.
Radio/Checkbox Elements
These types of elements are often used in groups in
which the elements have the same name. The effect on checkboxes
is to create multi-valued parameter data, whereas with
radio buttons the data is single-valued because radio
button group selection is mutually exclusive.
The HTML input element is also used to create checkboxes
and radio buttons. We use:
TYPE is radio, this is a radio button;
elements of the same NAME are mutually exclusive.
The boolean
attribute checked causes this element to be pre-selected
(a radio group can, of course, have only one pre-selected value).
In each case,
the value "on" is assigned if there is no value specified.
Selection Lists
The HTML select and option elements
are used to create selection lists. The format is like this:
size="SIZE": an integer.
If SIZE is 1 (the default),
the selection is a drop-down list, like the Java ComboBox.
If SIZE > 1 the selection is a scrolling list
multiple: a boolean attribute which, if present,
permits multiple selection from the list, making the
parameter multi-valued.
The option element permits the boolean
attribute selected
which sets that option to be pre-selected.
Single Selection Elements
From a form handler's point-of-view, parameter which are single-valued
can be treated in pretty much the same way. In this respect we identify
the two elements as being single-selection elements:
radio groups
single-selection lists (i.e., the multiple attribute is not present)
A second distinction among these single-selection elements is this:
those with one pre-selected element, one of three possibilities:
a radio group with one choice checked
a selection list of size 1 (by default the first item is selected)
a selection list of any size with one option selected
those with no pre-selected element, one of two possibilities:
a radio group with no choices checked
a selection list of size > 1
with no options selected
In the former cases, you can never be in the state where nothing
is chosen, whereas, in the latter case there is initially no choice
made, but once a choice is made you can only go
back to "choiceless" state by resetting the form.
In Java, we use request.getParameter(..) to retrieve the
value. When no choice is made, this value is null,
otherwise it is a non-null String.
The following example illustrates some of these possibilities:
Multiple selection element are those which deliver parameters with
multiple values. Again, from a form handler's point-of-view,
these are treated in pretty much the same way. In this respect we identify
the two elements as being multi-selection elements:
checkbox groups (more than one checkbox with same name)
multi-selection lists
(i.e., the multiple is present, there are more than one
option, and the size attribute usually has a value
> 1)
In these cases, zero or more choices can be selected yielding a
parameter whose value is either unset, if nothing is chosen, or
multi-valued, if more than one is chosen. Given any preset choices,
we can always go back to nothing being chosen.
In Java, we use request.getParameterValues(..) to retrieve the
value as an String array. When no choices are made,
this value is null.
The following example illustrates some of these possibilities:
The term reentrant
means that the form call itself as the action handler.
The easiest way to create the reentrant effect is to
make the action attribute empty:
<form>
or
<form action="" >
Often we want to differentiate between the initial activation of the script
(typically with no parameters) and the reentrant activations which do
have parameters. We can do so by testing whether a certain parameter
(often a button's name) is defined or not.
Reentrant Activation through redirection/forwarding
One can also effect reentrant activation by calling an external script
and having the external script "call back" to the original. There
are two ways that the external script can do this "call back":
redirection: The script redirects back to the caller, making the
browser do a second activation, but otherwise making the process "invisible".
The advantage is that, in certain cases, the parameters can be processed
by the called script, making it appear that the browser has simply "refreshed"
the original script. The disadvantage is that of speed due to the second
activation. The handler makes its redirection
request by doing:
String caller = /* the URL that called the handler */;
response.sendRedirect(caller);
forwarding: This is an internal mechanism
whereby the caller maintains
its URL, but effect the actions that would happen if the reentrant call
were made. This has the advantage of keeping the handler "outside" the
calling script, but has the disadvantage of setting a new URL, thus not
"looking like" reentrant behavior. The handler makes its forwarding
request by doing:
String caller = /* the URL that called the handler */;
request.getRequestDispatcher(caller).forward(request, response);
Note the obvious difference in that redirection makes the client
"do something" by virtue of the response, whereas with forwarding,
the server does something by virtue of using the request.
Stable vs. unstable form elements
A static form element, without any programming feature, used
in a reentrant script is
unstable because it does not preserve any user modifications
on a reentrant call.
A programmed element which does preserve the input settings
on reentry is
stable.
Creating stability implies that we have to capture the parameter
value(s) set by the form, and use these values to reset
the form elements accordingly.
The method of achieving this effect depends on the element:
Textfield: set value="the (escaped) parameter value"
Textarea: insert the (escaped) parameter value between the
start and end textarea tags
Radio group: loop through the radio button values, test for
equality with the parameter value, and set to checked when true
Single-selection list: loop through the option values, test for
equality with the parameter value, and set to selected when true
Checkbox group, multi-selection list: same respective ideas
as with a radio group and single-selection list, except that there
is set of parameter values to which the generated value may belong.
In Java we have to create a (possibly empty) Set<String>
of values which corresponds to a parameter p. With this
set we can test each generated
value, value, for containment to see whether to select that element.
String[] p = request.getParameterValues("p"); // null, or an array
Set p_set = new HashSet();
if (p != null) for (String value: p) { p_set.add(value); }
if (p_set.contains(value))
/* then this checkbox/option should be checked/selected */
Sample Reentrant Scripts
All of the scripts are reentrant.
For variety, we've made the text-reentrant.jsp
script effect its reentrant action by forwarding through the
TextReentrantHandler
servlet with the action setting:
action="TextReentrantHandler"
Compare it to the "direct reentrant" behavior by setting
action=""
Also note our first usage of a package import used within a JSP page.
This is effected by the special tag:
Libraries
and click the New Library button (bottom, left). In
the Library Name, type CommonsLang.