OpenCms-Struts Alpha Release Notes.

This document describes what features have been implemented in this Alpha release and how to use them. Please note that this is an Alpha release in every sense of the word, expect things to not work correctly. This means do not use in a production environment, if you do you will be disappointed. If you have any questions or suggestion please address them to klewelling@curoalemanz.com or post them to the forum.

What you will need

(Required) The OpenCms-Struts binary distribution (or the sources if you would like to compile it).
(Required) The Struts example application module.
(Recomended) The Struts v1.1 documentation war (just place in the webapps directory of Tomcat).

What (mostly) works

The core Struts distribution works, which means requests to Actions in the VFS are forwarded to the Struts servlet for Struts to process.

Support for multiple Struts applications as well as reparsing configuration files without restarting the servlet container.

Syncronization of action elements in the Struts configuration files with action resources in the VFS.

Parsing and validation of the Struts configuration file (if the validation fails there is no indication why, this will be resolved in the next release).

Importing and exporting of Struts applications as OpenCms Modules (there are a few problems with this process which are detailed below).

What does not work

Importing and exporting of Struts applications as WAR files.

The default Struts applications is located in the WEB-INF directory and not the VFS.

Creating an action resource in the VFS does not add an action element in a Struts configuration file.

What has not be tested

Validator Plugin (although the example Struts application uses it)

Tiles Plugin

Where do I start?

First install OpenCms-Struts just like a normal OpenCms distribution. Once you have logged in go to the Administration view and select "Module management". Then select the upload module botton and "Local computer". Navigate to the Struts sample application module(Struts-example.zip) in your filesystem and import it. You will probably notice some exceptions being thrown, don't worry about these as they are not important right now. Once the import is complete you will notice the Struts Status is "Invalid". This message is refering to the Struts configuration file. The reason the status is Invalid is listed at the bottom of this document, however this problem does give us the opportunity to show how to edit a Struts configuration file in OpenCms. Go back to the Explorer view and navigate to "/system/modules/org.apache.struts.webapp.example/struts/". Within this directory are two files, struts-config.xml and struts-config.bkup. Switch to the Offline project and lock the struts-config.xml file. Next select "Edit sourcecode" from the struts-config.xml context menu. Once the file has loaded select the save and exit button. Now go back to the Administration view and back to Module management and the Struts Status should now be Valid.

Select the E xplorer view and you will notice an additional resource in the root directory called "toModule.do". This is an action resource that belongs to the default Struts application. This action resource is needed to "switch" to other Struts applications. Within the root directory you should also notice a new folder called "com.apache.struts.webapp.example" (note that this is the also the name of the OpenCms module the Struts application belongs to. In the next release there will be an option to name this folder). Within the folder you will notice a mix of jsp resources, action resources, and a text resource. These resources are the Struts example application, shipped with the Struts distribution.To view the Struts example application point your webbrowser to http://localhost:8080/opencms/opencms/toModule.do?prefix=/opencms/org.apache.struts.webapp.example & page=/index.jsp Depending on your configuration, you have to replace localhost with your servername. The port 8080 is only used if you start Tomcat in standalone mode. To understand why this is necessary go to the section 5.3 in the Struts Developer documentation.

How it works

OpenCms-Struts relies heavily on Struts v1.1's modules feature. Each Struts application in OpenCms has its own Struts configuration file and is contained in its own folder off the root directory. The independent nature of the Struts modules is helpful for a variety of reasons. One is it integrates very well with OpenCms's concept of Modules. OpenCms Modules are where Struts is integrated with OpenCms. Just as a Module may be enabled to create an Administrative Icon in the Administrative View, a Module can be enabled to support Struts. Once Struts support for a Module is enabled a new folder within t he Module folder is created called struts(system/modules/ < modulename > /struts) as well as a folder off the root directory with the class name of the module. Within the new folder in the modules directory is the Struts configuration file (system/modules/ < modulename > /struts/struts-config.xml). The folder off the root directory is where any action elements added to the Struts configuration file will apear. This folder is also where any files belonging to the Struts application should be kept.

Now for a little fun

Now for a demonstration of the action resource syncronization and how it affects a Struts application. First make sure you are in the offline projet and look in the folder /org.apache.struts.webapp.example/ and notice a file named "tour.do". Now go to the directory /system/modules/org.apache.struts.webapp.example/struts/ and selecte Edit sourcecode for the file named struts-config.xml. Look for an action element that looks like this: 


        <!-- Display the "walking tour" documentation -->
        <action path="/tour"
                forward="/tour.htm">
        </action>

and change it to: 


        <!-- Display the "walking tour" documentation -->
        <!-- action path="/tour"
                forward="/tour.htm">
        </action -->

Now click the Save and Exit button and go back to the folder /org.apache.struts.webapp.example/. You should notice that the file "tour.do" has been deleted. Now in another browser window go back to http://localhost:8080/opencms/opencms/toModule.do?prefix=/opencms/org.apache.struts.webapp.example & page=/index.jsp and select "A Wal king Tour of the Example Application". You should see a Resource Deleted exception or a page not found error. Now go back to /system/modules/org.apache.struts.webapp.example/struts/struts-config.xml and change the lines back to: 

        
        <!-- Display the "walking tour" documentation -->
        <action path="/tour"
                forward="/tour.htm">
        </action>

Save and exit and try the link "A Walking Tour of the Example Application" again.

How to add support for Struts to an OpenCms module

Adding support for Struts to an OpenCms module can be done when the module is first created or added latter through the Administer interface. When you select the create module button you are presented with a form asking for the Module name and other information. You should notice a checkbox labeled Struts Support, simply check the box. When a project is created with Struts support two addition folders are created, one in the root directory with the name of the module's classname, and a second in the module's system directory, called struts. A default struts-config.xml file is copied from the workplace template directory into the struts directory. To add support to a module that has already been created all you have to do is select "Administer" from the module's context menu and check the Struts support checkbox. The same actions are performed as for a new module with Struts support.

To remove Struts support from a module all you have to do is select "Administer" from the module's context menu and uncheck the Struts support checkbox. This will remove the struts directory from the module's system folder, as well as any action resources associated with that module from the VFS. The folder created in the root directory with the module's classname will not be removed, only action resou rces within it.

Odds and Ends

Struts example application

If you study the Struts example application carefully you will notice it is not identical with the example application distributed with Struts. The example application was written assuming it would be the default application and therefore there were a couple changes that needed to be made so it could be a Struts module. The changes must be made because Struts must be told when a non-default module is being used or else it assumes it is in the default module and uses its configuration file. You only need to tell Struts once that it should use a non-default module, and as long as the application navigate via Struts actions all is well. However if a non-default application links directly to a JSP file Struts will try to use the default configuration which will cause problems. This is exactly what the Struts example application did. In the original index.jsp file the link to "Log on to the MailReader Demonstration Application" used a direct link to the logon.jsp page. Struts then tried to lookup the message resources used in the logon.jsp page in the default Struts configuration file, which it could not find and threw an exception. To get around this problem is rather trivial, all I did was add a new action element called logonPage to the struts-config.xml file (/system/modules/org.apache.struts.webapp.example/struts/struts-config.xml): 


                <!-- Forward to the logon page -->
                <action  path="/logonPage"
                        forward="/logon.jsp">
                </action>

Then I changed the link in index.jsp to: 


                <li><html:link page="/logonPage.do"><bean:message key="index.logon"/></html:link></li>

Please note that the above is not all that needs to be changed in the example application for the port to OpenCms to be called compelete. For example it uses an xml file called database.xml, which is located in WEB-INF folder, to save its logon information. Some more extensive changes will have to be made to the code to get it to read the file from the VFS. Before a final release I will make this change and probably write a porting guide to let developers know what needs to change to get an application to work in OpenCms. The largest challenge to porting to OpenCms will be if an application reads and writes directly to a file in the filesystem. If an application does this it will need to be changed so it can read and write to the VFS.

Here is a list of some changes that will be made for the next release

The default Struts application will be moved into the VFS (probably in /system/workplace/administration/struts).
The backup Struts configuration file will be removed. Currently it is used to figure out what has changed when a configuration file is changed, but this information can be retrieved from the VFS. There is also a problem with the backup configuration file. OpenCms throws an exception when an attempt to delete the backup file is made durring an import (this is the problem I refered to above in the "What (mostly) works" section).
When a Struts application is edited and has errors the Status is changed to Invalid, but the error is not given. The idea is to provide the error in the Module section of the Administrative View. The Struts module status is given and i f it is invalid it will have a link that provdes the error message.
The ability to have Administrative Views use Struts.