Desktop Java GUIs Based on Swing
|
JSP Tag Reference
2. Application Model
An application using Devsphere Mapping Framework can be made of:  2.1. Data BeansDevsphere Mapping Framework uses JavaBeans to encapsulate data. It introspects them in order to get information that is necessary to the mapping process: property names and property types. Additional information, like default values and error messages, is loaded from optional resource files, which are discussed in a later section. A data bean is a class that meets the following requirements:
To be conformant with the JavaBeans specification, a data bean should also implement java.io.Serializable. We recommend declaring the beans in a package to avoid naming conflicts.
package packageName;
public class BeanName implements java.io.Serializable {
private PropertyType propertyName;
...
public PropertyType getPropertyName() {
return propertyName;
}
public void setPropertyType(PropertyType value) {
propertyName = value;
}
...
}
The properties of the data beans can be
The mapping utilities separate the properties in four categories:
If a property is an array then it should be an indexed property. (In addition to property accessors, it should have accessors for array elements, though the latter ones aren't used. The introspection mechanism of JavaBeans needs them in order to recognize indexed properties.) Examples of data beans:
2.2. FormsDevsphere Mapping Framework takes pure HTML forms and maps them to data beans. This process consists of making associations between bean properties and form elements. For example,
Note: These are just a few of the mapping possibilities. The associations between bean properties and form elements are made by their names. The mapping utilities can take the form data and set the values of the bean properties. The reverse process is possible too, i.e. the mapping utilities can take the bean data and insert VALUE attributes for text fields, CHECKED attributes for checkboxes and radio buttons and SELECTED attributes for list items. The mapping between data beans and HTML forms is the subject of a later chapter. The form documents may contain variables that are replaced with dynamically generated content using the setValue() methods of FormDocument. Each variable has a name and is defined using an HTML comment: <!-- VARIABLE NAME="variableName" --> You may also define an indexed variable like this: static_html_content <!-- VARIABLE NAME="variableName" INDEX="0" --> static_html_content <!-- VARIABLE NAME="variableName" INDEX="1" --> static_html_content ... <!-- VARIABLE NAME="variableName" INDEX="N" --> static_html_content The index attribute is optional, but you have to use it if you want to control the indexing of multi-value variables. The framework defines automatically the variables that are used to insert default values and error messages. The names of these variables are [DEFAULT_VALUE.propertyName] and [ERROR_MESSAGE.propertyName]. You may see where they are placed using the toString() method of FormTemplate. You may not access the values of these internal variables defined by the framework. Their values are set automatically by the mapping utilities. You may, however, relocate the [ERROR_MESSAGE.propertyName] variables by simply redefining them: <!-- VARIABLE NAME="[ERROR_MESSAGE.propertyName]" --> If you redefine an error message variable you also get access to its value. The default value variables cannot be redefined. Examples of forms:
2.3. Bean ResourcesYou can attach a resource bundle to each bean. The mapping utilities of Devsphere Mapping Framework can operate without them. However, we recommend you to define the resources, because they allow you to specify default values, error message and more. A bean resource bundle is a class that meets the following requirements:
The bean resource bundle can also be a .properties file as long as
We recommend enclosing the resource keys within squared brackets and starting them with a prefix followed by dot: "[prefix.keyName]" or "[prefix.keyName.propertyName]". The prefix may be the package name or the application's name. Using a prefix you avoid name collisions with the resources used by the framework whose keys have no prefix. All mapping utilities use the following resources if they exist: 2.3.1. Default valueskey: [DEFAULT_VALUE.propertyName] Only standard properties (strings, primitives, primitive wrappers, BigInteger and BigDecimal) and standard indexed properties (string arrays, primitive arrays, wrapper arrays, BigInteger[] and BigDecimal[]) may have default values. Since you may not store primitives in a resource bundle, use strings or primitive wrappers for their default values:
{ "[DEFAULT_VALUE.propertyName]", "value" } or
{ "[DEFAULT_VALUE.propertyName]", new Wrapper(value) } or
[DEFAULT_VALUE.propertyName]=value
Arrays may be stored as default values of the indexed standard properties, in case you use a list resource bundle:
{ "[DEFAULT_VALUE.propertyName]",
new PropertyType[] { value0, value1, ..., valueN } }
If you want to use .properties files an array may be encoded using multiple key-value pairs: [DEFAULT_VALUE.propertyName.length]=N [DEFAULT_VALUE.propertyName.0]=value0 [DEFAULT_VALUE.propertyName.1]=value1 ... [DEFAULT_VALUE.propertyName.N]=valueN If you don't specify a default value for a standard property, the mapping utilities will use an empty string, 0, false or an empty array, depending on the property's type. 2.3.2. Error messageskey: [ERROR_MESSAGE.propertyName] The error message should be a string:
{ "[ERROR_MESSAGE.propertyName]", "errorMessage" } or
[ERROR_MESSAGE.propertyName]=errorMessage
The error message of a property is shown in one of the following situations:
If you don't specify an error message for a property, a default message will be used to signal the errors. 2.3.3. Optional propertieskey: [OPTIONAL_PROPERTIES] An optional parameter should be mapped to an optional property so that no error is signaled when the parameter value is missing. The list of optional properties must be declared as a string array or as a string. If it isn't present, the mapping utilities assume that there are no optional properties.
{
"[OPTIONAL_PROPERTIES]",
new String[] {
"propertyName1",
"propertyName2",
...
"propertyNameK"
}
}
or [OPTIONAL_PROPERTIES]=propertyName1 propertyName2 ... propertyNameK 2.3.4. Processing orderkey: [PROCESSING_ORDER] By default, all properties of a bean participate to the mapping process, their processing order being determined by the introspection API of JavaBeans. You can define the list of properties as a string array or as a string if you want to control the order in which the mapping utilities set/get the values of the bean properties. That could be useful if the validation of a property value is done in the setter method and it depends on the values of other properties. Also, you may exclude some of the properties from the mapping process by not including them in the property list. You will have to do this for read only properties whose values are computed as a function of other property values.
{
"[PROCESSING_ORDER]",
new String[] {
"propertyName1",
"propertyName2",
...
"propertyNameN"
}
}
or [PROCESSING_ORDER]=propertyName1 propertyName2 ... propertyNameN
2.3.5. XML indentation stringkey: [XML_INDENTATION_STRING]
2.3.6. Starter, separator and terminator of error messageskey: [HTML_MESSAGE_START] key: [HTML_MESSAGE_SEPARATOR] key: [HTML_MESSAGE_END] 2.3.7. Fixed length of bean arrayskey: [FIXED_LENGTH.propertyName] If you use static HTML forms, the bean arrays will be mapped to a fixed number of groups of form elements. In this case, you may specify that fixed number within the bean's resources. If you use dynamic forms, the length of a bean array will have to be stored as the default value of a hidden form element. The use of these techniques will be exemplified in later chapters.
2.3.8. Form namekey: [FORM_NAME] Forms are used to collect bean data using a browser and they are described in the previous section of this chapter. 2.3.9. Processor namekey: [PROC_NAME] Processors receive valid beans from handlers and they are described in a later section of this chapter. Examples of bean resources:
2.4. HandlersA handler is a component that receives form data via HTTP and tries to map it to one or more data beans. If the mapping succeeds, the valid beans are forwarded to a processor, which is responsible for responding to the HTTP request. Otherwise, the handler sends back to the user an HTML form containing already inputted valid data and messages that signal the errors. The handler is also used to get the HTML form the first time. The handlers make heavy use of the APIs provided by Devsphere Mapping Framework. For example, a JSP handler could look like this:
<%@ page language="java" import="com.devsphere.mapping.*, com.devsphere.logging.*" %>
<jsp:useBean id="beanID" class="BeanName" scope="request"/>
<%
// 1. Get the bean resources
java.util.ResourceBundle beanRes = HandlerUtils.getBeanResources(beanID.getClass());
// 2. Construct the base path
String basePath = request.getServletPath();
int slashIndex = basePath.lastIndexOf('/');
basePath = slashIndex != -1 ? basePath.substring(0, slashIndex+1) : "";
// 3. Determine the HTTP method
boolean isPostMethod = request.getMethod().equals("POST");
// 4. Create a logger that wraps the servlet context
ServletLogger logger = new ServletLogger(application);
// 5. Wrap the form data
FormData formData = new ServletFormData(request);
// 6. Form-to-bean mapping: request parameters are mapped to bean properties
java.util.Hashtable errorTable = FormUtils.formToBean(formData, beanID, logger);
if (isPostMethod && errorTable == null) {
// 7. Construct the processor's path
String procPath = basePath + beanRes.getString("[PROC_NAME]").trim();
// 8. Process the valid data bean instance
application.getRequestDispatcher(procPath).forward(request, response);
} else {
if (!isPostMethod)
// 9. Ignore the user errors if the form is requested with GET.
errorTable = HandlerUtils.removeUserErrors(errorTable);
// 10. Construct the form's path
String formPath = basePath + beanRes.getString("[FORM_NAME]").trim();
formPath = application.getRealPath(formPath);
// 11. Get the form template
FormTemplate template = FormUtils.getTemplate(new java.io.File(formPath));
// 12. Get a new document
FormDocument document = template.getDocument();
// 13. Bean-to-form mapping: bean properties are mapped to form elements
FormUtils.beanToForm(beanID, errorTable, document, logger);
// 14. Send the form document
document.send(out);
}
%>
The first line of the handler imports the packages of the framework: com.devsphere.mapping and com.devsphere.logging. The second line declares and instantiates a bean whose class is BeanName. Processors (discussed in the next section) can use the same line to get the bean object. The JSP engine translates the following line <jsp:useBean id="beanID" class="BeanName" scope="request"/> into something like this:
BeanName beanID = null;
synchronized (request) {
beanID = (BeanName) pageContext.getAttribute("beanID", PageContext.REQUEST_SCOPE);
if ( beanID == null ) {
try {
beanID = (BeanName) Beans.instantiate(getClassLoader(), "BeanName");
} catch (Exception e) {
throw new ServletException("Cannot create bean of class " + "BeanName");
}
pageContext.setAttribute("beanID", beanID, PageContext.REQUEST_SCOPE);
}
}
Therefore, instead of using the <jsp:useBean> tag twice, in handler and processor, it would be sufficient to use
BeanName beanID = new BeanName();
request.setAttribute("beanID", beanID);
in handler and
BeanName beanID = (BeanName) request.getAttribute("beanID");
in processor. Of course, the use of <jsp:useBean> is simpler and better. The above Java snippets are just meant to explain that the <jsp:useBean> tag creates the bean in handler and retrieves the bean in processor. This is true, for the application model described here, because the handler receives the HTTP request and forwards it to the processor. The first two lines are followed by a scriptlet whose steps are described next:
This is just a typical use of the mapping utilities within a JSP handler that works with a static HTML form and a JSP processor. The mapping utilities are very flexible and can be used in many ways. A later chapter will exemplify how to build handlers that work with dynamic HTML forms. It is also possible to replace the JSPs with servlets. The next chapter will present a generic handler servlet. Examples of handlers:
2.5. ProcessorsA processor is a JSP, a servlet or a Java class that receives valid beans for processing. It could store the bean to a database, file or another repository, it could send it over a network using any protocol or it could perform other tasks. Devsphere Mapping Framework can be used to convert the bean data to XML or plain text. These mappings are the subject of some later chapters. Examples of processors:
2.6. Hints and TipsWhen you build an application that uses Devsphere Mapping Framework,
 |