Using Struts Scripting with the Mini HR Application

Using Struts Scripting

Using Struts Scripting involves these three steps:

1. Add the Struts Scripting .jar files and properties file to the application.

2. Create script-based actions.

3. Configure script-based actions in the application's Struts configuration file.

The following sections describe these steps in detail.

Adding the Struts Scripting .jar Files and Properties File to the Application

A few .jar files must be added to the application in order to use Struts Scripting functionality. Each required .jar file should be copied to the application's WEB-INF\lib directory (or added to the classpath of the server[s] on which the application runs). First, add the Struts Scripting .jar file (e.g., c:\java\struts-1.3.5\lib\struts-scripting-1.3.5.jar) from the Struts distribution to the application if it is not already present. Next, add the BSF .jar file (e.g., c:\ java\struts-1.3.5\lib\bsf-2.3.0.jar) from the Struts distribution to the application if it is not already present. Finally, scripting language .jar files must be added to the application.

Each scripting language has a set of .jar files that it needs in order to run. For detailed instructions on which .jar files are required for a given scripting language, visit that language's Web site. To give an example of what is involved in adding required scripting language .jar files to an application, take Groovy (http://groovy.codehaus.org/). First, download Groovy. Next, copy the Groovy .jar file (e.g., c:\java\groovy-1.0-JSR-06\embeddable\groovy-all-1.0-JSR-06.jar) to the application's WEB-INF\lib directory. That's it.

After adding the required .jar files to the application, a Struts Scripting properties file must be added to the application for BSF non-default scripting languages. As stated earlier, BSF supports many languages by default without any special configuration; however, any language not supported by default by BSF must be configured in a Struts Scripting properties file. The Struts Scripting properties file specifies the BSF non-default scripting languages being used and their associated script file extensions (e.g., .groovy for Groovy scripts, .jruby for JRuby scripts, and so on). This file must be named struts-scripting.properties and be accessible from the application's classloader (i.e., be placed on the classpath of the server[s] the application runs on). Typically the file is placed in the application's WEB-INF\classes directory. The following code shows an example properties file's content:

struts-scripting.engine.groovy.class=org.codehaus.groovy.bsf.GroovyEngine struts-scripting.engine.groovy.extensions=gv,groovy struts-scripting.engine.jruby.class=org.jruby.javasupport.bsf.JRubyEngine struts-scripting.engine.jruby.extensions=rb,jruby

There is no limit to the number of scripting languages that can be in use at one time. The preceding example properties file shows how to enable two scripting languages at once: Groovy and JRuby.

Each BSF non-default scripting language is defined using two properties: struts-scripting.engine.LANGUAGE_NAME.class and struts-scripting.engine.LANGUAGE_ NAME.extensions, where LANGUAGE_NAME is an arbitrary name assigned to the scripting language. The struts-scripting.engine.LANGUAGE_NAME.class property specifies the fully qualified class name of the language's BSF engine. The struts-scripting.engine.LANGUAGE_NAME.extensions property specifies the file extensions that will be mapped to the language. Any number of file extensions can be specified using commas to delimit them.

Creating Script-Based Actions

Creating a script-based action is very similar to creating a standard Java-based action; however, instead of writing the action in Java, you write it in the scripting language of your choice. The scripting language being used determines the specific details of how the action is written, but all script-based actions follow the same general pattern and have the same general operating facilities as Java-based actions. Like Java-based actions, script-based actions can access details of the action mapping, the Form Bean, the HTTP request object, and the HTTP response object. Also like Java-based actions, script-based actions typically specify a forward to inform Struts of how to proceed with navigation at the end of executing the action.

Unlike Java-based actions, script-based actions do not extend org.apache.struts.action.Action and do not operate inside of an execute( ) method. Instead, script-based actions are written like a basic linear script. Script-based actions access the action mapping, the Form Bean, the HTTP request object, and the HTTP response object via implicit predefined variables. Forwards are specified using the predefined struts variable and setting either struts.forwardName to the logical name of a forward or struts.forward to an actual org.apache.struts.action.ActionForward object. Following is an example Groovy script–based action that illustrates the basic concepts of creating a script-based action:

// Access the Form Bean associated with this Action. loginForm = struts.form;     // Access Form Bean fields. username = loginForm.username; password = loginForm.password;     // Perform processing of data here. // ...     // Forward to a Forward named "success". struts.setForwardName("success");

As stated, each scripting language has its particular nuances, but in general this is how script-based actions are written. Changes can be quickly made to script-based actions without the need for recompilation or servlet container restarts-simply reload the page that executes the action. For more information on the implicit predefined variables made available to script-based actions, see the section "Predefined Scripting Variables."

Configuring Script-Based Actions in the Application's Struts Configuration File

After creating script-based actions, they must be configured in your application's Struts configuration file. Script-based actions are configured differently than standard Struts actions that subclass Action. Instead of specifying the fully qualified class name of an action with the action tag's type attribute, the type attribute is set to the standard Struts Scripting action: org.apache.struts.scripting.ScriptAction. ScriptAction will execute the script-based action specified with the action tag's parameter attribute. Following is an example of how to configure a script-based action in the Struts configuration file:

<!-- Action Mappings Configuration --> <action-mappings>   <action path="/search"           type="org.apache.struts.scripting.ScriptAction"           parameter="/WEB-INF/scripts/Search.groovy"           name="searchForm"           scope="request"           validate="true"           input="/search.jsp">   </action> </action-mappings>

As stated, the type attribute of the action tag must specify that org.apache.struts.scripting. ScriptAction. ScriptAction executes the script at the location specified by the parameter attribute. The remaining action tag attributes are the same as would be used with any other action definition.

Predefined Scripting Variables

Struts Scripting makes a set of predefined variables available to scripts. The predefined variables can be used without any special setup or definition; they are simply available. The following table lists the name, type, and description of each predefined variable.

Name	Type	Description
application	javax.servlet.ServletContext	The servlet context object for the Web application.
log	org.apache.commons.logging.Log	A Commons Logging log object for logging.
request	javax.servlet.http.HttpServletRequest	The HTTP request object.
response	javax.servlet.http.HttpServletResponse	The HTTP response object.
session	javax.servlet.http.HttpSession	The HTTP session object.
struts	org.apache.struts.scripting.StrutsInfo	The Struts information container object for accessing Struts objects.

Predefined variables are accessed by name as shown next in the example Groovy script snippet:

// Retrieve User object from session using pre-defined "session" variable. user = session.getAttribute("user");

As stated, no setup is required to use the predefined variables.

In addition to the predefined variables provided by Struts Scripting, custom predefined variables can be configured that will be made available to scripts. There are two ways to configure predefined variables: by specifying them in script-based action definitions in the Struts configuration file and/or by creating a BSFManagerFilter implementation. The two approaches have one major distinction: Struts configuration file–based custom variables are specific to an action definition, and BSFManagerFilter implementation–based custom variables are made available to all scripts. Each of these methods is described in detail in the following sections.

Struts Configuration File-Based Custom Variables

Custom predefined variables can be configured that will be made available only to specific actions by specifying them in the script-based action definitions in the Struts configuration file. This technique for defining custom variables is useful for creating DispatchAction-like script-based actions. The following code shows an example of two action-specific custom predefined variables:

<!-- Action Mappings Configuration --> <action-mappings>   <action path="/search"           type="org.apache.struts.scripting.ScriptAction"           parameter="/WEB-INF/scripts/Search.groovy?prop1=val1&amp;prop2=val2"           name="searchForm"           scope="request"           validate="true"           input="/search.jsp">   </action> </action-mappings>

The custom variables are specified by appending name-value pairs to the script path specified with the action tag's parameter attribute using URL query string-style syntax. The syntax for specifying custom variables is shown next:

 ?PARAM_NAME=PARAM_VALUE&PARAM_NAME=PARAM_VALUE 

Like URL query strings, the custom variables are prefixed with a question mark (?) and then each variable is specified as PARAM_NAME=PARAM_VALUE, where PARAM_NAME is the name of the custom variable and PARAM_VALUE is the custom variable value. Multiple custom variables are separated by "&".

Note that as of Struts 1.3, action-specific custom variables can be specified using nested set-property tags inside script-based action definitions instead of using the query string–style syntax with the parameter attribute. The following example illustrates this technique:

<!-- Action Mappings Configuration --> <action-mappings>   <action path="/search"           type="org.apache.struts.scripting.ScriptAction"           parameter="/WEB-INF/scripts/Search.groovy"           name="searchForm"           scope="request"           validate="true"           input="/search.jsp">     <set-property key="prop1" value="val1"/>     <set-property key="prop2" value="val2"/>   </action> </action-mappings>

BSFManagerFilter Implementation-Based Custom Variables

Custom predefined variables can be configured that will be made available to all scripts by creating an implementation of org.apache.struts.scripting.BSFManagerFilter and configuring it in the struts-scripting.properties file. The following code shows an example BSFManagerFilter instance:

import java.util.Properties;     import org.apache.bsf.BSFException; import org.apache.bsf.BSFManager; import org.apache.struts.scripting.BSFManagerFilter;     public class ExampleScriptingFilter implements BSFManagerFilter {   private String prop1;   private String prop2;       public void init(String name, Properties props) {     // Utilize initialization parameters here.     prop1 = props.getProperty("prop1");     prop2 = props.getProperty("prop2");   }       public BSFManager apply(BSFManager mgr) {     try {       mgr.declareBean("prop1", prop1, String.class);       mgr.declareBean("prop2", prop2, String.class);     } catch (BSFException e) {       // Handle exception here.     }         return mgr;   } }

Inside the filter instance custom variables are registered with calls to the declareBean( ) method of BSF's org.apache.bsf.BSFManager class.

After creating the BSFManagerFilter instance, it must be configured in the struts-scripting. properties file as shown next in bold:

struts-scripting.engine.groovy.class=org.codehaus.groovy.bsf.GroovyEngine struts-scripting.engine.groovy.extensions=gv,groovy struts-scripting.filters.example.class=com.jamesholmes.minihr.ExampleScriptingFilter struts-scripting.filters.example.prop1=val1 struts-scripting.filters.example.prop2=val2 

The filter instance is specified using a property named struts-scripting.filters.FILTER_ NAME.class, where FILTER_NAME is an arbitrary name assigned to the filter. The value specified for the property is the fully qualified class name for the filter instance. In addition to specifying the class name of the filter instance, filter initialization parameters can be specified using properties named struts-scripting.filters.FILTER_NAME.PARAM_NAME=PARAM_VALUE, where FILTER_NAME is the name of the instance, PARAM_NAME is the name of the initialization parameter, and PARAM_VALUE is the initialization parameter value. Initialization parameters are packaged in a java.util.Properties instance and passed to the filter instance's init( ) method.