Message-mapping JavaServer Pages (JSP) files are required whenever user input fields are displayed by user-defined JSP files. Message-mapping JSP files:
Receiving data
Message data that is provided by the user in the input fields of a user-defined JSP file can be received by the javax.servlet.http.HttpServletRequest object in the subsequent message-mapping JSP file. The following code snippet shows how to access user input data in a user-defined JSP file:
String symbol = request.getParameter("Symbol_Input"); String number = request.getParameter("Number_Input"); String limit = request.getParameter("Limit_Input"); [...]
Processing data
When all of the user input is available, it is appropriate to perform type checks and validate the input data. For example, some input fields might be mandatory, or some input fields might be required to accept values in a certain range or format only. You can use a message-mapping JSP file to do these checks.
Examples of type checking and data validation are given in the following code snippet:
if (number.equals("")) { throw new ServletException("The required field 'number' has not been completed. Please specify a number."); } try { int intValueOfNumber = Integer.valueOf(number)).intValue(); } catch (NumberFormatException ex) { throw new ServletException("The specified number '"+number+"' is not valid. "); }
When you check and validate input data, it is recommended that you use the built-in error feature of JSP files to display errors that occur. Define a user-defined error page, error.jsp in the page header of the message-mapping JSP file:
<%@ page errorPage="error.jsp" %>
Wrap the exceptions that occur when the data is checked in a ServletException exception. Whenever a ServletException exception (wrapping an error that occurred during data validation and checking) occurs, the error page is displayed. Detailed information about the error can be displayed on the error page, for example, The required field 'user id' has not been completed. Users can use the browser back button to return to the Web client. They can correct their entries and then send a message (an input or output message of a process or an activity) with the corrected data.
Wrapping data
After the user input is received and validated, the data must be wrapped in a message object that can be processed by the business process container.
You can use an org.apache.wsif.base.WSIFDefaultMessage class for all messages. If message data is to be retrieved, for example, it is always wrapped in a WSIFDefaultMessage class.
Suppose a process input message has the following structure:
symbol | java.lang.String |
number | int |
limit | double |
id | java.lang.String |
WSIFDefaultMessage wsifProcessInMessage = new WSIFDefaultMessage(); wsifProcessInMessage.setObjectPart("symbol", symbol); wsifProcessInMessage.setIntPart("number", intValueOfNumber); wsifProcessInMessage.setDoublePart("limit", doubleValueOfLimit); wsifProcessInMessage.setObjectPart("id", id);
Forwarding data
To send a message to the business process container, you can use the forwardMessageToController static method in the com.ibm.bpe.client.MessageUtilities class. The signature of this method is:
public static void forwardMessageToController( javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, java.io.Serializable message, java.util.Map furtherParameters, java.util.Vector excludeRequestParameters) throws javax.servlet.ServletException, java.io.IOException
The following code snippet shows how a process input message might be forwarded:
ClientObjectWrapper messageWrapper = new ClientObjectWrapper(message); //where message is the WSIFMessage instance that was previously populated MessageUtilities.forwardMessageToController(request, response, messageWrapper, null, null);