com.taursys.xml
Class Form

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

All Implemented Interfaces:

DocumentComponent, Element, MapperComponent

Direct Known Subclasses:

ServletForm

public class Form

extends DocumentElement

Form is a top level Container for applications.

Version:

1.0

Author:

Marty Phelan

Field Summary

static java.lang.String

PARAMETER_MAP

Constructor Summary

Form()
Constructs a new Form

Method Summary

void	addCloseFormListener(CloseFormListener l) Adds given listener to notification list for CloseFormEvents
void	addInitContextListener(InitContextListener l) Adds given listener to notification list for InitContextEvents
void	addInitFormListener(InitFormListener l) Adds given listener to notification list for InitFormEvents
void	addOpenFormListener(OpenFormListener l) Adds given listener to notification list for OpenFormEvents
protected void	closeForm() Closes the form and any resources it may have opened.
protected DocumentElementRenderer	createDefaultRenderer() Creates the default DocumentElementRenderer for this component.
protected void	dispatchCloseForm() Initiate the dispatch of the CloseFormEvent to registered nested Forms.
protected void	dispatchInitContext() This method is invoked by run to dispatch the formContext to nested Forms.
protected void	dispatchInitForm() Initiate the dispatch of the InitFormEvent to registered nested Forms.
protected void	dispatchOpenForm() Initiate the dispatch of the OpenFormEvent to registered nested Forms.
protected void	fireCloseFormReceived(CloseFormEvent e) Notifies all registered listeners of a given CloseFormEvent
protected void	fireInitContextReceived(InitContextEvent e) Notifies all registered listeners of a given InitContextEvent
protected void	fireInitFormReceived(InitFormEvent e) Notifies all registered listeners of a given InitFormEvent
protected void	fireOpenFormReceived(OpenFormEvent e) Notifies all registered listeners of a given OpenFormEvent
org.w3c.dom.Document	getDocument() Returns the document for this form.
DocumentAdapter	getDocumentAdapter() Gets the documentAdapter for this form.
DocumentAdapterBuilder	getDocumentAdapterBuilder() Get the DocumentAdapterBuilder for this Form and create it if null.
java.lang.String	getDocumentURI() Get the documentURI which is used to create the Document
java.util.Map	getFormContext() Get the Map of key/value pairs for this Form's context.
java.lang.String	getSourceId() Returns the id of the node this component is bound to.
protected void	initForm() Initialize form for first time use by building/parsing Document.
boolean	isInitialized() Indicates whether the form has been initialized (via the initForm method).
java.lang.Object	lookup(java.lang.Object key) Lookup a value from this Form's context.
protected void	openForm() This method is invoked as part of the processOpenFormEvent method.
void	printComponentTree(Container parent, java.lang.String level) Prints the component tree contents to the console
protected void	processCloseFormEvent(CloseFormEvent e) Processes a given CloseFormEvent by invoking the Form's closeForm method, then dispatching an CloseFormEvent to the Form's children, and finally propagating the CloseFormEvent to registered listeners.
protected void	processEvent(java.util.EventObject e) Processes given event by invoking the appropriate processX__Event method.
protected void	processInitContextEvent(InitContextEvent e) Processes a given InitContextEvent by setting the formContext and parameterMap from the given message, then dispatching an InitContextEvent to the Form's children, and finally propagating the InitContextEvent to registered listeners.
protected void	processInitFormEvent(InitFormEvent e) Processes a given InitFormEvent by invoking the Form's initForm method (unless initialized is true), then dispatching an InitFormEvent to the Form's children, and finally propagating the InitFormEvent to registered listeners.
protected void	processOpenFormEvent(OpenFormEvent e) Processes a given OpenFormEvent by invoking the Form's openForm method, then dispatching an OpenFormEvent to the Form's children, and finally propagating the OpenFormEvent to registered listeners.
void	removeCloseFormListener(CloseFormListener l) Removes given listener from notification list for CloseFormEvents
void	removeInitContextListener(InitContextListener l) Removes given listener from notification list for InitContextEvents
void	removeInitFormListener(InitFormListener l) Removes given listener from notification list for InitFormEvents
void	removeOpenFormListener(OpenFormListener l) Removes given listener from notification list for OpenFormEvents
void	setDocument(org.w3c.dom.Document newDocument) Sets the document and creates the documentAdapter for this form.
void	setDocumentAdapter(DocumentAdapter newDocumentAdapter) Sets the documentAdapter for this form.
void	setDocumentAdapterBuilder(DocumentAdapterBuilder builder) Set the DocumentAdapterBuilder for this Form
void	setDocumentURI(java.lang.String documentURI) Set the documentURI which is used to create the Document
void	setFormContext(java.util.Map formContext) Set the Map of key/value pairs for this Form's context.
void	setInitialized(boolean newInitialized) Sets an indicator that the form has been initialized (via the initForm method).
void	setSourceId(java.lang.String sourceId) Sets the id of the node this component is bound to.
java.lang.String	toString() Returns a string representation of this object.

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

Field Detail

PARAMETER_MAP

public static final java.lang.String PARAMETER_MAP

See Also:

Constant Field Values

Constructor Detail

Form

public Form()

Constructs a new Form

Method Detail

createDefaultRenderer

protected DocumentElementRenderer createDefaultRenderer()

Creates the default DocumentElementRenderer for this component. By Default this methos returns a new DocumentElementRenderer. Override this method to define your own DocumentElementRenderer.

Overrides:

createDefaultRenderer in class DocumentElement

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 parameterMap property being set. A new context is constructed which contains everything already in this Form's plus the parameterMap.

Throws:

java.lang.Exception

dispatchInitForm

protected void dispatchInitForm()
                         throws java.lang.Exception

Initiate the dispatch of the InitFormEvent to registered nested Forms. This method should only be invoked after the InitContextEvent has been dispatched.

Throws:

java.lang.Exception

dispatchOpenForm

protected void dispatchOpenForm()
                         throws java.lang.Exception

Initiate the dispatch of the OpenFormEvent to registered nested Forms. This method should only be invoked after the InitFormEvent and ParameterEvent have been dispatched.

Throws:

java.lang.Exception

dispatchCloseForm

protected void dispatchCloseForm()
                          throws java.lang.Exception

Initiate the dispatch of the CloseFormEvent to registered nested Forms. This method should be invoked after all processing is complete. Normally, nested Forms should be allowed to close before this form closes.

Throws:

java.lang.Exception

processEvent

protected void processEvent(java.util.EventObject e)
                     throws java.lang.Exception

Processes given event by invoking the appropriate processX__Event method. The appropriate event type is determined by the class of the given EventObject.

Overrides:

processEvent in class Component

Throws:

java.lang.Exception

processInitContextEvent

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

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

Parameters:

e - the InitContextEvent to process

Throws:

java.lang.Exception

removeInitContextListener

public void removeInitContextListener(InitContextListener l)

Removes given listener from notification list for InitContextEvents

addInitContextListener

public void addInitContextListener(InitContextListener l)

Adds given listener to notification list for InitContextEvents

fireInitContextReceived

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

Notifies all registered listeners of a given InitContextEvent

Throws:

java.lang.Exception

initForm

protected void initForm()
                 throws java.lang.Exception

Initialize form for first time use by building/parsing Document. This method is invoked by run to initialize the form. It is the first method invoked by the doGet method before any parameters have been dispatched. Parses Document and Creates DocumentAdapter using DocumentAdapterBuilder. This method sets the initialized flag to true. Override this method to provide custom behavior. If you override, be sure to invoke super.initForm or setInitialized(true) if this method should only be called once.

Throws:

java.lang.Exception

processInitFormEvent

protected void processInitFormEvent(InitFormEvent e)
                             throws java.lang.Exception

Processes a given InitFormEvent by invoking the Form's initForm method (unless initialized is true), then dispatching an InitFormEvent to the Form's children, and finally propagating the InitFormEvent to registered listeners.

Parameters:

e - the InitFormEvent to process

Throws:

java.lang.Exception

removeInitFormListener

public void removeInitFormListener(InitFormListener l)

Removes given listener from notification list for InitFormEvents

addInitFormListener

public void addInitFormListener(InitFormListener l)

Adds given listener to notification list for InitFormEvents

fireInitFormReceived

protected void fireInitFormReceived(InitFormEvent e)
                             throws java.lang.Exception

Notifies all registered listeners of a given InitFormEvent

Throws:

java.lang.Exception

openForm

protected void openForm()
                 throws java.lang.Exception

This method is invoked as part of the processOpenFormEvent method. It is normally invoked after processParameterEvent, but before processInputEvent. Override this method to provide custom behavior such as opening data sources. This implementation has no specific behavior.

Throws:

java.lang.Exception

processOpenFormEvent

protected void processOpenFormEvent(OpenFormEvent e)
                             throws java.lang.Exception

Processes a given OpenFormEvent by invoking the Form's openForm method, then dispatching an OpenFormEvent to the Form's children, and finally propagating the OpenFormEvent to registered listeners.

Parameters:

e - the OpenFormEvent to process

Throws:

java.lang.Exception

removeOpenFormListener

public void removeOpenFormListener(OpenFormListener l)

Removes given listener from notification list for OpenFormEvents

addOpenFormListener

public void addOpenFormListener(OpenFormListener l)

Adds given listener to notification list for OpenFormEvents

fireOpenFormReceived

protected void fireOpenFormReceived(OpenFormEvent e)
                             throws java.lang.Exception

Notifies all registered listeners of a given OpenFormEvent

Throws:

java.lang.Exception

closeForm

protected void closeForm()
                  throws java.lang.Exception

Closes the form and any resources it may have opened. This method is invoked by the processCloseForm method which is normally invoked at the end of the processing cycle but before this Form is recycled. Override this method to provide custom behavior. This implementation has no specific behavior.

Throws:

java.lang.Exception

processCloseFormEvent

protected void processCloseFormEvent(CloseFormEvent e)
                              throws java.lang.Exception

Processes a given CloseFormEvent by invoking the Form's closeForm method, then dispatching an CloseFormEvent to the Form's children, and finally propagating the CloseFormEvent to registered listeners.

Parameters:

e - the CloseFormEvent to process

Throws:

java.lang.Exception

removeCloseFormListener

public void removeCloseFormListener(CloseFormListener l)

Removes given listener from notification list for CloseFormEvents

addCloseFormListener

public void addCloseFormListener(CloseFormListener l)

Adds given listener to notification list for CloseFormEvents

fireCloseFormReceived

protected void fireCloseFormReceived(CloseFormEvent e)
                              throws java.lang.Exception

Notifies all registered listeners of a given CloseFormEvent

Throws:

java.lang.Exception

getDocumentURI

public java.lang.String getDocumentURI()

Get the documentURI which is used to create the Document

Returns:

the documentURI which is used to create the Document

See Also:

for URI syntax

setDocumentURI

public void setDocumentURI(java.lang.String documentURI)

Set the documentURI which is used to create the Document

Parameters:

documentURI - which is used to create the Document

See Also:

for URI syntax

setDocument

public void setDocument(org.w3c.dom.Document newDocument)
                 throws DocumentAdapterBuilderException

Sets the document and creates the documentAdapter for this form. This is the document which will be typically be modified and sent back as the response.

Parameters:

newDocument - for this form.

Throws:

DocumentAdapterBuilderException

getDocument

public org.w3c.dom.Document getDocument()

Returns the document for this form. This is the document which will be sent back as the response. This is also the document which the components of this form will modify.

setDocumentAdapter

public void setDocumentAdapter(DocumentAdapter newDocumentAdapter)

Sets the documentAdapter for this form. The document adapter is used by components as an adapter for the actual Document. The adapter provides the needed methods for components to manipulate the Document regardless of the DOM version.

Parameters:

newDocumentAdapter - for this form.

getDocumentAdapter

public DocumentAdapter getDocumentAdapter()

Gets the documentAdapter for this form. The document adapter is used by components as an adapter for the actual Document. The adapter provides the needed methods for components to manipulate the Document regardless of the DOM version.

Overrides:

getDocumentAdapter in class Container

Returns:

the documentAdapter for this form.

getDocumentAdapterBuilder

public DocumentAdapterBuilder getDocumentAdapterBuilder()
                                                 throws DocumentAdapterBuilderException

Get the DocumentAdapterBuilder for this Form and create it if null.

Returns:

the DocumentAdapterBuilder for this Form

Throws:

DocumentAdapterBuilderException

setDocumentAdapterBuilder

public void setDocumentAdapterBuilder(DocumentAdapterBuilder builder)

Set the DocumentAdapterBuilder for this Form

Parameters:

builder - the DocumentAdapterBuilder for this Form

getFormContext

public java.util.Map getFormContext()

Get the Map of key/value pairs for this Form's context.

Returns:

the Map of key/value pairs for this Form's context.

setFormContext

public void setFormContext(java.util.Map formContext)

Set the Map of key/value pairs for this Form's context.

Parameters:

formContext - the Map of key/value pairs for this Form's context.

Throws:

java.lang.IllegalArgumentException - if the given value is null

lookup

public java.lang.Object lookup(java.lang.Object key)

Lookup a value from this Form's context.

Parameters:

key - the key for the value to lookup

Returns:

the value as an Object or null if not found.

getSourceId

public java.lang.String getSourceId()

Returns the id of the node this component is bound to. This is the node which this component will replicate.

setSourceId

public void setSourceId(java.lang.String sourceId)

Sets the id of the node this component is bound to. This is the node which this component will replicate.

setInitialized

public void setInitialized(boolean newInitialized)

Sets an indicator that the form has been initialized (via the initForm method). The run method will only invoke the initForm method if this indicator is false, and then it will set this indicator to true. This will prevent the form from being initialized again (if it is recycled).

isInitialized

public boolean isInitialized()

Indicates whether the form has been initialized (via the initForm method). The run method will only invoke the initForm method if this indicator is false, and then it will set this indicator to true. This will prevent the form from being initialized again (if it is recycled).

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 DocumentElement

Returns:

a string representation of this object

printComponentTree

public void printComponentTree(Container parent,
                               java.lang.String level)

Prints the component tree contents to the console

Parameters:

parent - starting parent container

level - spaces to indent initially