Objective Html - With Struts

Author Keith Wong, keithwong@optushome.com.au

Last updated: 23rd Feb 2002

Objective Html provides a high-level of integration with the Struts framework. This integration allows developers to configure their Objective Html forms using xml configuration files. In these configuration files you can specify the signal and slot connections for a form and between forms. You can also specify how the forms are to behave when a Objective Html/Struts action is triggered. This flexibility allows developers to build highly self-contained forms that are loosely coupled with each other and highly reuseable. The behaviour and interactions of the forms can be easy configured in the xml file for a particular problem domain.

Struts Requirements

This code has been tested with Struts 1.02. Other versions may not work, especially later ones as some of the packages have been renamed. Please contact me if you have issues getting it working for other versions.

Jar Files

Make sure the struts.jar and the objectivehtml-X.jar are both in the WEB-INF/lib folder.

Setting Up Objective Html With Struts

web.xml

The servlet class needs to be the ObjectiveHtmlServlet class. This servlet class is a subclass of the Struts ActionServlet class. This servlet class configures itself from the xml configuration file and also configures the Struts components as well. Make sure the following directive is in web.xml:

    <servlet-class>objectivehtml.struts.ObjectiveHtmlServlet</servlet-class>

The servlet init-parameter "ohtmlconfig" specifies the location of Objective Html configuration file. This parameter does not need to be specified if you are using the default file location /WEB-INF/ohtml-config.xml. This is the default setting:

    <init-param>
      <param-name>ohtmlconfig</param-name>
      <param-value>/WEB-INF/ohtml-config.xml</param-value>
    </init-param>

struts-config.xml

To configure an Objective Html action then you must first configure a corresponding Struts action with the same path. The action needs to use the action class objectivehtml.struts.ObjectiveHtmlAction or a subclass of this. This is example of how an Objective Html action needs to configured in the Struts configuration file:

    <!-- loading up the customer form -->
    <action    path="/customerload"
               type="objectivehtml.struts.ObjectiveHtmlAction">
      <forward name="success"              path="/customer.jsp"/>
    </action>

The Objective Html configuration file will have a corresponding action directive with the same path "/customerload".

Multipart/form-data

Objective Html natively supports multipart/form-data via the Struts framework. All uploaded files can be referenced by the getUploadedFile() method on each HtmlFileInput object.

EventResult Object

This object is used by the Objective Html forms to store the result of a request. Whenever an Objective Html action is invoked it will create a new instance of the EventResult object and will store the object in the request object. Any forms or objects invoked by the action can set the result in the EventResult object or any other associate details such as an exception object. After all the necessary forms and objects have been invoked by the action the result object will be inspected for a result. It will use this result to set the appropriate next forward page.

ohtml-config.xml

This is the Objective Html configuration file. You can use a different file name if you wish, simply change the init-param "ohtml-config" (see above). All Objective Html configuration files need to declare the dtd file:

<!DOCTYPE ohtml-config PUBLIC
       "-//Objective Html//DTD Objective Html Configuration 1.0//EN"
       "http://objectivehtml.sourceforge.net/dtds/ohtml-config_1_0.dtd">

Result Object

The ohtml-result tag allows you specify the name the EventResult object is to bound with in the request object. For example:

	<ohtml-result>ohtml.result</ohtml-result>

The result object will be bound with the name 'ohtml.result' in the request object. You can simply extract the object by calling getAttribute("ohtml.result") on the request object.

Declaring Forms

In this section of the configuration file we can configure the properties and behaviour of our Objective Html forms. Here we'll simply show an example configuration and then we'll outline the use and purpose of each directive.

	<ohtml-forms>

		<ohtml-form>
			<name>CustomerForm</name>
			<type>mypackage.CustomerForm</type>

			<update-orders>

				<update-order>
					<name>m_txtPostCode</name>
					<order>10</order>
				</update-order>

				<update-order>
					<name>m_btnSave</name>
					<order>20</order>
				</update-order>

			</update-orders>

			<connections>

				<connection>
					<slot-obj>this</slot-obj>
					<slot>saveForm()</slot>
					<signal-obj>m_btnSave</signal-obj>
					<signal>clicked()</signal>
				</connection>

				<connection>
					<slot-obj>this</slot-obj>
					<slot>updatePostCodeFields(String)</slot>
					<signal-obj>m_txtPostCode</signal-obj>
					<signal>valueChanged(String,String)</signal>
					<set-error-handler>false</set-error-handler>
				</connection>

			</connections>

		</ohtml-form>

	</ohtml-forms>

<ohtml-form>

Element Description Values Mandatory Child Element

<name> This tag contains the name for this form. This name will be used to reference this form in other parts of the configuration file. The name should be unique for each form. Anything Y -

<type> This tag contains the fully qualified Java class name (including package name) of the object that we are configurating properties for. A fully qualified Java class name Y -

<update-orders> This tag lists the update-orders of all the fields in this form. - N update-order

<connections> This tag lists the signal and slot intra-connections of this form. - N connection

<update-order>

Element Description Values Mandatory Child Element

<name> This tag contains the member variable name of the form component to set the update-order for. This member variable must a public access-level. A public member variable of this form Y -

<order> This tag contains the update-order for this particular form component. A positive integer (zero included) Y -

Element Description Values Mandatory Child Element

<slot-obj> This tag contains the name of the slot object. Valid slot objects are either the form object itself or any public member HtmlControlWidget objects. 'this' or the name of a public member variable Y -

<slot> This tag contains the method signature of the slot method that is to be connected. A valid slot method signature Y -

<signal-obj> This tag contains the name of the signal object. Valid signal objects are either the form object itself or any public member objects (subclass of OMSObject). 'this' or the name of a public member variable Y -

<signal> This tag contains the method signature of the signal method that is to be connected. A valid slot method signature Y -

<set-error-handler> This tag contains a boolean value and indicates whether an error handler is to be set for the slot method. The slot object itself is assumed to be ErrorHandler object. true | false N -

Declaring Actions

In this section of the configuration file we can configure the Objective Html actions. Here we'll simply show an example configuration and then we'll outline the use and purpose of each directive.

	<ohtml-actions>

		<ohtml-action>
			<path>/customerlistload</path>
			<create-forms>
				<create-form>
					<name>CustomerListForm</name>
					<session-ref>myapp.customerlist</session-ref>
					<condition>always</condition>
				</create-form>

			</create-forms>

			<invoke-methods>

				<invoke-method>
					<session-ref>myapp.customerlist</session-ref>
					<method-signature>getAllCustomers()</method-signature>
					<method-params>
					</method-params>
				</invoke-method>

				<invoke-method>
					<session-ref>myapp.customerlist</session-ref>
					<method-signature>checkException(javax.servlet.http.HttpServletRequest)</method-signature>
					<method-params>
						<request-obj />
					</method-params>
				</invoke-method>

			</invoke-methods>

			<default-forward>success</default-forward>
		</ohtml-action>

		<ohtml-action>
			<path>/customerload</path>

			<create-forms>
				<create-form>
					<name>CustomerForm</name>
					<session-ref>myapp.customer</session-ref>
					<condition>always</condition>

					<connections>
						<connection>
							<slot-session-ref>myapp.customer</slot-session-ref>
							<slot>populateForm(long)</slot>
							<signal-session-ref>myapp.customerlist</signal-session-ref>
							<signal>customerSelected(long)</signal>
						</connection>

					</connections>

				</create-form>

			</create-forms>

			<update-form>myapp.customerlist</update-form>

			<default-forward>success</default-forward>

		</ohtml-action>

		<ohtml-action>
			<path>/customersave</path>

			<update-form>myapp.customer</update-form>

		</ohtml-action>

	</ohtml-actions>

<ohtml-action>

Element Description Values Mandatory Child Element

<path> This tag contains the path for this action. Each action maps to a request path like Struts. This action directive will be triggered whenever the request path matches the path specified in this tag. A valid URI Y -

<create-forms> This tag lists the create-form directives for this action. A create-form directive is used to create an instance of a form. - N create-form

<invoke-methods> This tag lists the invoke-method directives for this action. A invoke-method directive is used to invoke a method of an object. - N invoke-method

<update-form> This tag contains the session name of the form that is to be updated with the submitted data. The form object bound to this name in the session object will be extracted and will have the updateData(HttpServletRequest) method invoked on it. An attribute name in the session object N -

<default-forward> This tag contains the default forward. If no forward is specified in the EventResult object then this forward will be used. This is useful for forms that only have one forward page regardless of the request outcome. A valid forward name N -

<create-form>

Element Description Values Mandatory Child Element

<name> This tag contains the name of the to be created. The name needs to correspond to a form name declared in the <ohtml-form> directive. The form created with have all the properties of the form specified in the <ohtml-form> directive. A name of a form declared in a <ohtml-form> directive Y -

<session-ref> This tag contains the attribute name that this new form will bound with in the session object. Anything Y -

<condition> This tag contains the condition for when this form is to be created. There are 2 valid values 'always' and 'notexists'. 'always' means this form will always be created each time this action is triggered. 'notexists' means this form will only be created when an object doesn't already exist in the session object. always | notexists Y -

<connections> This tag lists the signal and slot inter-connections of this form with other forms. - N connection

Element Description Values Mandatory Child Element

<slot-session-ref> This tag contains the name of the slot object in the session object. The object needs to be an instance of OMSObject (or subclass of OMSObject). A valid session attribute name Y -

<slot> This tag contains the method signature of the slot method that is to be connected. A valid slot method signature Y -

<signal-session-ref> This tag contains the name of the signal object in the session object. The object needs to be an instance of OMSObject (or subclass of OMSObject). A valid session attribute name Y -

<signal> This tag contains the method signature of the signal method that is to be connected. A valid slot method signature Y -

<set-error-handler> This tag contains a boolean value and indicates whether an error handler is to be set for the slot method. The slot object itself is assumed to be ErrorHandler object. true | false N -

<invoke-method>

Element Description Values Mandatory Child Element

<session-ref> This tag contains the attribute name of the session object. The object bound to this name will have a method invoked on it. Anything Y -

<method-signature> This tag contains the method signature of the method we are to invoke. A valid method signature Y -

<method-params> This tag lists all the method parameters to be passed to the invoked method. - N request-param | session-param | request-obj

<method-params>

Element Description Values Mandatory Child Element

<request-param> This tag contains the name of either a request parameter or attribute. The value/object associated with the name is passed to the invoking method as a parameter. The parameter list is searched first for this name, if no parameter is found then the attribute bound with this name is used. For a request parameter type conversions are done automatically if required for primitive types (and primitive wrappers also). Either a request parameter or attribute N -

<session-param> This tag contains the name of a session attribute. The value/object associated with the name is passed to the invoking method as a parameter. Either a request parameter or attribute N -

<request-obj> This tag specifies that the request object itself is to be passed to the invoking method as a parameter. EMPTY element N -

Element	Description	Values	Mandatory	Child Element
<name>	This tag contains the name for this form. This name will be used to reference this form in other parts of the configuration file. The name should be unique for each form.	Anything	Y	-
<type>	This tag contains the fully qualified Java class name (including package name) of the object that we are configurating properties for.	A fully qualified Java class name	Y	-
<update-orders>	This tag lists the update-orders of all the fields in this form.	-	N	update-order
<connections>	This tag lists the signal and slot intra-connections of this form.	-	N	connection