4. Component Architecture

4.1 Components

This is the foundation object for MapperXML components. All components share this base abstract class. It provides common attributes and basic event dispatching methods with limited implementation.

This object defines the following properties:

• parent - the parent Container for this Component. This property is set by the Container methods: add and remove.
• visible - this property is used by render subcomponents to determine whether to hide or show this component during rendering.

This object is designed to respond to 5 types of events. The following are the events this component is designed to respond to:

• ParameterEvent - this event is generated when parameter values are available for this component. A ParameterEvent differs from an InputEvent only by WHEN it is dispatched. ParameterEvents are normally dispatched before InputEvents
• InputEvent - this event is generated when input values are available for this component. An InputEvent differs from a ParameterEvent only by WHEN it is dispatched. InputEvents are normally dispatched after ParameterEvents
• TriggerEvent - this event is generated when a specific name/value pair appears (or does not appear) in the request.
• RenderEvent - this event is generated when it is time for components to render their value to the document.
• RecycleEvent - this event is generated after the request/response cycle as a signal that components should return to a default or initial state. Components may also modify the document as part of their response to this event.

In order to be notified of these events, this component must register with each of the appropriate dispatchers. This is done by adding/removing the types of events you wish to be notified of to the eventTypeList. This is done by invoking the addEventType or removeEventType method with the fully qualified class name of the desired event. The eventTypeList is used by the addNotify and removeNotify methods which are invoked by the Container during the add and remove Container methods.

This component contains a 2 general purpose methods modeled after AWT and Swing: dispatchEvent and processEvent. These 2 methods simply call the specific processXXXEvent method based on the event type.

For each of the specific event types, there are a set of 3 related methods.

• processXXXEvent - this method is where you would provide the necessary behavior to respond to the event. This abstract implementation simply propagates the event to registered listeners. You should override this method to provide appropriate behavior.
• addXXXListener - registers the given listener with this component to be notified whenever this component has began/ended processing the event.
• removeXXXListener - unregisters the given listener so it will no longer be notified.

4.2 Containers

This class is a foundation container for MapperXML components. This class defines all required properties and methods for a container and provides basic implementation for many of them. The Container provides 3 primary functions:

• Component management - provides methods to add, remove and retrieve Components.
• Provide access to a DocumentAdapter for the Components to render themselves to. This implementation simply looks to its parent Container to obtain the DocumentAdapter. Bottom level or master Containers should override this method and provide access to a DocumentAdapter.
• Provide access to Dispatchers for the various event types to the Components. This is done through the getDispatcher method which takes the fully qualified class name of the Event. Components need to access these Dispatchers whenever they are added or removed from this Container so they can add or remove themselves from the various event notification lists. This provides an internal HashMap of Dispatchers which are keyed by their fully qualified event name. Implementations can maintain their own Dispatchers using the add/removeDispatcher methods.

4.3 Models

Models are used to store and retrieve the "state" or value for Components. Models are responsible for any conversion, parsing, or formatting of values. The following is the heirarchy of Model interfaces and implementations:

        * interface com.taursys.model.TextModel
            * interface com.taursys.model.CheckboxModel
            * interface com.taursys.model.SelectModel

        * class com.taursys.model.DefaultTextModel (implements
                javax.swing.event.ChangeListener, com.taursys.model.TextModel)
            * class com.taursys.model.DefaultCheckboxModel (implements
                    com.taursys.model.CheckboxModel)
            * class com.taursys.model.DefaultSelectModel (implements
                    com.taursys.model.SelectModel)
        

MapperXML also uses some of the exsiting Swing(tm) model: javax.swing.ButtonModel.

MapperXML models use ValueHolders to store the actual value or state internally. These models create their own ValueHolder during construction. They can also be attached to an external ValueHolder (which can be shared by multiple models)

The TextModel is a foundation model for MapperXML. The TextModel provides access to the internal "state" or value via the getText and setText methods. It is the responsibility of theses methods to provide any required parsing or formatting as they transform the value between its String representation and actual internal representation (int, Date, BigDecimal, etc). There are 2 properties which govern the parse/format process: format and formatPattern. These use the standard java.text.Format objects and patterns.

The TextModel uses a ValueHolder to hold the actual "state" or value. A ValueHolder can provide storage for any data type. Implementations of the TextModel can create and use their own internal ValueHolder. They can also be assigned an external ValueHolder to use. Multiple TextModels can share the same ValueHolder. A specific property of the ValueHolder host object can also be targeted. The target property can be specified by setting the propertyName property. (Note: the ValueHolder itself must be one that actually supports access to individual properties for this feature to work, otherwise the propertyName setting is ignored).

The TextModel also provides notification to ChangeListeners whenever the "state" or value changes. Interested listeners can register or unregister to receive notification of ChangeEvents by using the addChangeListener or removeChangeListener methods.

4.4 ValueHolders

A ValueHolder is a foundation subcomponent for MapperXML which is used by TextModels to store/retrieve the current "state" or value. A ValueHolder can be used exclusively by a single TextModel or shared by multiple TextModels. A specific property of the ValueHolder host object can also be targeted. The targeted property can be specified by setting the propertyName property. (Note: the ValueHolder implementation must be one that actually supports access to individual properties for this feature to work, otherwise the propertyName setting is ignored and the whole host object is accessed).

The data type of the targeted host object property (or the host object itself) is available via the getJavaDataType method.

The alias property provides a way of naming this ValueHolder. This name is required when using the ComponentFactory to automatically create and bind MapperXML components from an HTML/XML document.

The ValueHolder also provides notification to ChangeListeners whenever the "state" or value changes. Interested listeners can register or unregister to receive notification of ChangeEvents by using the addChangeListener or removeChangeListener methods.

For more information about ValueHolders see section 7

4.5 Renderers (Views)

4.6 Events and Dispatchers