com.taursys.servlet
Class ServletForm

java.lang.Object
  com.taursys.xml.Component
      com.taursys.xml.Container
          com.taursys.xml.DispatchingContainer
              com.taursys.xml.DocumentElement
                  com.taursys.xml.Form
                      com.taursys.servlet.ServletForm

All Implemented Interfaces:

DocumentComponent, Element, MapperComponent

Direct Known Subclasses:

DefaultMessageForm

public class ServletForm

extends Form

ServletForm is the base container invoked used by Servlet application. It contains all the components that make up the form. The ServletForm is responsible for servicing requests which are routed to it by the ServletApp.

Your servlet forms will typically extend this base class. The ServletForm provides a default processing cycle within the doGet method.

The ServletForm is composed of many subcomponents to support the processing of the request: ParameterDispatcher, InputDispatcher, RenderDispatcher, TriggerDispatcher, DocumentAdapter and Responder.

You must supply this ServletForm with a DOM Document. There are a variety of ways you can achieve this: 1) use a DOM parser such as Xerces, 2) use a DOM compiler such as Enhydra's XMLC, 3) build the DOM programatically.

The Document is normally created and attached to this ServletForm in the initForm method. This method is normally only called once when the ServletForm is first invoked. Below is an example using the Xerces parser:

 protected void initForm() throws Exception {
   super.initForm();
   DOMParser parser = new DOMParser();
   InputSource is =
       new InputSource(getClass().getResourceAsStream("MyPage.html"));
   parser.parse(is);
   this.setDocument(parser.getDocument());
 }
 

In typical applications, you will add Components to this ServletForm and set their properties to bind to the DOM Document elements, http request parameters, and value objects. These components are capable of modifying the DOM Document, storing and retrieving value from bound objects, and reading parameters from the http request, and parsing/converting between text values and java data types. This ServletForm is the base container for these components and contains dispatchers which dispatch events to the components. This ServletForm generates the events within the doGet method in a fixed sequence (see javadoc for doGet).

The below example creates a HTMLInputText component which binds to an HTML form input text field. It also binds to the lastName property of a Java value object class.

 public class MyPage extends ServletForm {
   HTMLInputText lastName = new HTMLInputText();
   VOValueHolder person = new VOValueHolder();

   public MyPage() {
     lastName.setPropertyName("lastName");
     lastName.setValueHolder(person);
     lastName.setId("lastName");
     this.add(lastName);
   }
   ...
   protected void openForm() throws Exception {
     // Retrieve or create the value object
     Person personVO = new Person(1629, "Pulaski", "Katherine", null);
     // Bind value object to person ValueHolder
     person.setValueObject(personVO);
   }
 

There are many components you can use in a ServletForm. These include: Parameter, Template, TextField, Trigger, Button, HTMLAnchorURL, HTMLCheckBox, HTMLInputText, HTMLSelect, HTMLTextArea, and others.

You can control the response of this ServletForm by changing the Responder subcomponent at runtime. The default Responder is an HTMLResponder which sends the DOM Document as the response.

The ServletForm is a reusable object. The ServletApp (master servlet) will normally recycle ServletForms for an application unless their recycle method returns false. The recycle method dispatches a RecycleEvent to all components.

The ServletForm also supports multipart type requests. A multipart request is sent by the browser when form data contains 1 or more uploaded files. To support this feature, if the incoming request has a content type of "multipart/form-data", the request is wrapped in another request object which is capable of processing multipart requests. The wrapper request is created via the createRequestWrapper method. By default, createRequestWrapper returns a HttpMultiPartServletRequest object which has a maximum file size of 1 megabyte and maximum single line size of 4,096 bytes. You can change this by overriding the createRequestWrapper method:

 protected HttpServletRequest createRequestWrapper(HttpServletRequest rq)
     throws Exception {
   HttpMultiPartServletRequest multi = new HttpMultiPartServletRequest(rq);
   // set maximum sizes if defaults if needed
   multi.setMaxFileSize(2048);
   multi.setMaxLineLength(80);
   // parse the request
   multi.parseRequest();
   return multi;
 }
 

See Also:

HttpMultiPartServletRequest

Field Summary

Fields inherited from class com.taursys.xml.Form

PARAMETER_MAP

Constructor Summary

ServletForm()
Creates new servlet form and default dispatchers.

Method Summary

protected Responder	createDefaultResponder() Creates the default Responder for this component.
java.util.Map	createParameterMap() Create a Map of parameters contained in the request.
protected javax.servlet.http.HttpServletRequest	createRequestWrapper(javax.servlet.http.HttpServletRequest rq) Creates a multipart request wrapper to service a multipart request.
protected void	dispatchInitContext() This method is invoked by run to dispatch the formContext to nested Forms.
void	doGet(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp) This method is invoked by the application servlet to service the request.
javax.servlet.http.HttpServletRequest	getRequest() Gets the HttpServletRequest object for this ServletForm.
Responder	getResponder() Get the Responder which will provide appropriate response.
javax.servlet.http.HttpServletResponse	getResponse() Gets the HttpServletResponse object for this ServletForm.
protected void	handleException(java.lang.Exception ex) This method is invoked whenever an exception occurs within doGet.
boolean	isEnableActions() Get enableActions flag indicating whether or not to process actions.
boolean	isEnableInput() Get enableInput flag indicating whether or not to process input.
protected void	processInitContextEvent(InitContextEvent e) Processes a given InitContextEvent by setting the formContext, parameterMap, request and response from the given message, then dispatching an InitContextEvent to the Form's children, and finally propagating the InitContextEvent to registered listeners.
boolean	recycle() Dispatches a RecycleEvent to all components and returns true if successful.
protected void	sendResponse() Send the appropriate response.
void	setEnableActions(boolean newEnableActions) Set enableActions flag indicating whether or not to process actions.
void	setEnableInput(boolean newEnableInput) Set enableInput flag indicating whether or not to process input.
void	setRequest(javax.servlet.http.HttpServletRequest newRequest) Sets the HttpServletRequest object for this ServletForm.
void	setResponder(Responder newResponder) Set the Responder which will provide appropriate response.
void	setResponse(javax.servlet.http.HttpServletResponse newResponse) Sets the HttpServletResponse object for this ServletForm.
void	testFullCycle(java.lang.String outputFile) Testing method to initialize, open and render the form to the screen and to a file if given.
java.lang.String	toString() Returns a string representation of this object.

Methods inherited from class com.taursys.xml.Form

addCloseFormListener, addInitContextListener, addInitFormListener, addOpenFormListener, closeForm, createDefaultRenderer, dispatchCloseForm, dispatchInitForm, dispatchOpenForm, fireCloseFormReceived, fireInitContextReceived, fireInitFormReceived, fireOpenFormReceived, getDocument, getDocumentAdapter, getDocumentAdapterBuilder, getDocumentURI, getFormContext, getSourceId, initForm, isInitialized, lookup, openForm, printComponentTree, processCloseFormEvent, processEvent, processInitFormEvent, processOpenFormEvent, removeCloseFormListener, removeInitContextListener, removeInitFormListener, removeOpenFormListener, setDocument, setDocumentAdapter, setDocumentAdapterBuilder, setDocumentURI, setFormContext, setInitialized, setSourceId

Methods inherited from class com.taursys.xml.DocumentElement

addAttribute, addNotify, addTextNode, createAttribute, createAttribute, createAttribute, createBoundAttribute, createBoundTextNode, createTextNode, createTextNode, createTextNode, getAttribute, getAttributeText, getAttributeValue, getElementDelegate, getId, getRenderer, getTextNode, getTextNodeText, getTextNodeValue, processRecycleEvent, processRenderEvent, removeAttribute, removeAttribute, removeNotify, removeTextNode, removeTextNode, setAttributeText, setAttributeValue, setId, setTextNodeText, setTextNodeValue

Methods inherited from class com.taursys.xml.DispatchingContainer

add, createInputDispatcher, createParameterDispatcher, createRecycleDispatcher, createRenderDispatcher, createTriggerDispatcher, dispatchActions, dispatchInput, dispatchParameters, dispatchRecycle, dispatchRender, getParameterMap, processInputEvent, processParameterEvent, processTriggerEvent, setParameterMap

Methods inherited from class com.taursys.xml.Container

addDispatcher, contains, get, getComponents, getDispatcher, getDispatchers, getInputDispatcher, getParameterDispatcher, getRecycleDispatcher, getRenderDispatcher, getTriggerDispatcher, remove, removeDispatcher, setComponents

Methods inherited from class com.taursys.xml.Component

addEventType, addInputListener, addParameterListener, addRecycleListener, addRenderListener, addTriggerListener, dispatchEvent, fireActionPerformed, fireInputReceived, fireParameterReceived, fireRecycle, fireRender, getEventTypeList, getParent, isNotifySet, isVisible, lazyAddNotify, lazyRemoveNotify, removeEventType, removeInputListener, removeParameterListener, removeRecycleListener, removeRenderListener, removeTriggerListener, setVisible

Methods inherited from class java.lang.Object

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

Constructor Detail

ServletForm

public ServletForm()

Creates new servlet form and default dispatchers.

Method Detail

recycle

public boolean recycle()

Dispatches a RecycleEvent to all components and returns true if successful. If an exception occurs during recycling, it is logged using Debug and this method returns false. If the form cannot be reused, override this method and return false. Override this method to provide custom behavior to recycle this form for future re-use.

doGet

public void doGet(javax.servlet.http.HttpServletRequest req,
                  javax.servlet.http.HttpServletResponse resp)
           throws java.lang.Exception

This method is invoked by the application servlet to service the request. It is invoked by the ServletApp for all request types (GET, POST, etc). This method invokes a series of other support methods in a specific sequence:

• saves request and response in properties (available using getRequest and getResponse)
• initForm (only invoked if isInitialized is false)
• If this is a multipart type request, uses the request wrapper returned by createRequestWrapper in place of the original request
• initializes the parameterMap property with parameters contained in the request using the createParameterMap method.
• dispatchInitContext is invoked which dispatches an InitContextEvent to any nested forms
• dispatchInitForm is invoked which dispatches an InitFormEvent to any nested forms
• dispatchParameters is invoked
• openForm is invoked
• dispatchOpenForm is invoked which dispatches an OpenFormEvent to any nested forms
• if enableInput flag is true, dispatchInput is invoked
• if enableActions flag is true, dispatchActions is invoked
• sendResponse is invoked
• dispatchCloseForm is invoked which dispatches an CloseFormEvent to any nested forms
• closeForm is invoked

If an exception is generated by any of these methods, the handleException method is invoked. It can either handle the exception and send the response, or it can rethrow the exception and let the application servlet handle it (latter is default behavior).

Parameters:

req - the incoming HttpServletRequest

resp - the outgoing HttpServletResponse

Throws:

java.lang.Exception - if problem during processing the request

dispatchInitContext

protected void dispatchInitContext()
                            throws java.lang.Exception

This method is invoked by run to dispatch the formContext to nested Forms. This method depends on the request, response, and parameterMap properties being set. A new context is constructed which contains everything already in this ServletForm's plus the request, response and parameterMap.

Overrides:

dispatchInitContext in class Form

Throws:

java.lang.Exception

sendResponse

protected void sendResponse()
                     throws java.lang.Exception

Send the appropriate response. It is invoked by doGet following the dispatchActions method. This method invokes the current Responder's respond method to provide the appropriate response. Change the Responder to provide custom response.

Throws:

java.lang.Exception

handleException

protected void handleException(java.lang.Exception ex)
                        throws java.lang.Exception

This method is invoked whenever an exception occurs within doGet. Override this method to provide custom exception handling behavior. Throwing an exception will delegate the exception handling to the caller of the doGet method. The default behavior of this method is to simply re-throw the exception.

Throws:

java.lang.Exception

createRequestWrapper

protected javax.servlet.http.HttpServletRequest createRequestWrapper(javax.servlet.http.HttpServletRequest rq)
                                                              throws java.lang.Exception

Creates a multipart request wrapper to service a multipart request. By default, this implementation creates a com.taursys.servlet.HttpMultiPartServletRequest and invokes its parseRequest() method. You can override this method to create and initialize your own default request wrapper.

Returns:

a request wrapper to service a multipart request.

Throws:

java.lang.Exception - if problem creating or initializing request wrapper

createDefaultResponder

protected Responder createDefaultResponder()

Creates the default Responder for this component. This implementation creates an com.taursys.servlet.respond.HTMLResponder. You can override this method to create your own default Responder.

Returns:

new instance of the default Responder for this component.

createParameterMap

public java.util.Map createParameterMap()

Create a Map of parameters contained in the request. The resulting Map is not modifiable. The Map contains String keys for each parameter and String[] arrays for each parameter value. This method was included to supplement the Servlet 2.2 spec which does not provide this method in the ServletRequest interface.

Returns:

a Map of parameters contained in the request.

processInitContextEvent

protected void processInitContextEvent(InitContextEvent e)
                                throws java.lang.Exception

Processes a given InitContextEvent by setting the formContext, parameterMap, request and response from the given message, then dispatching an InitContextEvent to the Form's children, and finally propagating the InitContextEvent to registered listeners.

Overrides:

processInitContextEvent in class Form

Parameters:

e - the InitContextEvent to process

Throws:

java.lang.Exception

setRequest

public void setRequest(javax.servlet.http.HttpServletRequest newRequest)

Sets the HttpServletRequest object for this ServletForm. This is normally only valid during the invocation of the run method.

Parameters:

newRequest - the HttpServletRequest object for this ServletForm

getRequest

public javax.servlet.http.HttpServletRequest getRequest()

Gets the HttpServletRequest object for this ServletForm. This is normally only valid during the invocation of the run method.

Returns:

the HttpServletRequest object for this ServletForm

setResponse

public void setResponse(javax.servlet.http.HttpServletResponse newResponse)

Sets the HttpServletResponse object for this ServletForm. This is normally only valid during the invocation of the run method.

Parameters:

newResponse - the HttpServletResponse object for this ServletForm

getResponse

public javax.servlet.http.HttpServletResponse getResponse()

Gets the HttpServletResponse object for this ServletForm. This is normally only valid during the invocation of the run method.

Returns:

the HttpServletResponse object for this ServletForm

setEnableInput

public void setEnableInput(boolean newEnableInput)

Set enableInput flag indicating whether or not to process input. If this flag is set, the run method will invoke the dispatchInput method to process input parameters for components. Disable input if you are processing a request where no input parameters are expected. This will avoid any input being set by default values (or behavior of HTMLCheckbox). The default value for this flag is true.

Parameters:

newEnableInput - flag indicating whether or not to process input.

isEnableInput

public boolean isEnableInput()

Get enableInput flag indicating whether or not to process input. If this flag is set, the run method will invoke the dispatchInput method to process input parameters for components. Disable input if you are processing a request where no input parameters are expected. This will avoid any input being set by default values (or behavior of HTMLCheckbox). The default value for this flag is true.

Returns:

flag indicating whether or not to process input.

setEnableActions

public void setEnableActions(boolean newEnableActions)

Set enableActions flag indicating whether or not to process actions. If this flag is set, the run method will invoke the dispatchActions method to process action parameters for trigger components. Disable actions if you are processing a request where no action parameters are expected. This will avoid any actions being triggered by default values. The default value for this flag is true.

Parameters:

newEnableActions - flag indicating whether or not to process actions.

isEnableActions

public boolean isEnableActions()

Get enableActions flag indicating whether or not to process actions. If this flag is set, the run method will invoke the dispatchActions method to process action parameters for trigger components. Disable actions if you are processing a request where no action parameters are expected. This will avoid any actions being triggered by default values. The default value for this flag is true.

Returns:

flag indicating whether or not to process actions.

setResponder

public void setResponder(Responder newResponder)

Set the Responder which will provide appropriate response. You can change the Responder during runtime to provide different kinds of responses. A default Responder is created when this ServletForm is created by the createDefaultResponder method. This method also sets the Responder's servletForm property to this ServletForm.

Parameters:

newResponder - the Responder which will provide appropriate response.

getResponder

public Responder getResponder()

Get the Responder which will provide appropriate response. You can change the Responder during runtime to provide different kinds of responses. A default Responder is created when this ServletForm is created by the createDefaultResponder method.

Returns:

the Responder which will provide appropriate response.

toString

public java.lang.String toString()

Returns a string representation of this object. This contains the object identity and state information.

Overrides:

toString in class Form

Returns:

a string representation of this object

testFullCycle

public void testFullCycle(java.lang.String outputFile)
                   throws java.lang.Exception

Testing method to initialize, open and render the form to the screen and to a file if given.

Parameters:

outputFile - full path of file to write to or null

Throws:

java.lang.Exception