Lance JSP Stuff Bill Theseus

Theseus .4 beta

Theseus version 0.4 is ready for download and use. For those of you who have downloaded the KDF (an older MVC framework), Theseus contains several upgrades and added features, including the addition of multiple .xml config files for the mappings of action classes. You will have to change the package names in your code, but this can be done by replacing com.mvc. with org.theseus. on all files. Sorry for this inconvenience.

There are 4 folders in the .zip file. The /bin folder is the already-compiled version. Of course, you'll most likely want to use the theseus.jar file instead. The /docs folder is where api documentation will go, as well as other related documentation. The /examples folder is where examples will be placed. These will most likely be .war files, containing complete web applications to be deployed into a Servlet 2.2 container. The /src dir is the source code to Theseus. We suggest creating a /projects/theseus dir, then unzipping this .zip file into that dir. Also, you will need the latest version of xerces.jar and saxon.jar. When compiling the source, you will need to make sure you have the Servlet 2.2 library, xerces.jar and saxon.jar in your classpath or compile path.

Be sure to read the /examples/examples.txt and /doc/whats_new.txt each time you download a version, there will be updates in these files when appropriate. For this version, we added a new config attribute, PopulateNestedAttribute. Normally, the nested auto-population uses the '_' character to figure out the separate nested objects in a submitted form element. With this feature, you can change how Theseus figures out the separated parts in an element. Thus, <input type="text" name="Address_FirstName"> can become <input type="text" name="Address-_-FirstName"> or the more common <input type="text" name="Address.FirstName">. The reason we use '_' as a default is that the '.' can cause problems with javascript code during client-side dynamic use of element names.

We will provide an Ant 1.3 build script soon that can be used as a template to build the project (you'll have to change the paths to the J2EE or servlet2.2 jar file, xerces.jar, and saxon.jar manually as each person may have these in different locations).

As for changes, we have made it possible to work with not one, but any number of .xml mapping config files. In the old version this was called mvc.xml and was placed in the WEB-INF/ folder. It still goes there, but now you can name one or more files whatever you like (the example uses theseus-config.xml) and simply add it to the web.xml. Listed below is a web.xml file example you can use for Theseus. Of course, you may have to merge this in with an existing web.xml for it to work.

---------
 web.xml
---------
<?xml version="1.0"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application
2.3//EN" "http://java.sun.com/j2ee/dtds/web-app_2_3.dtd">

<web-app>
    <servlet>
        <servlet-name>Controller</servlet-name>
        <display-name>Controller</display-name>
        <servlet-class>org.theseus.servlets.ControllerServlet</servlet-class>
        <init-param>
            <param-name>PopulateAttributeName</param-name>
            <param-value>auto-populate</param-value>
        </init-param>
        <init-param>
            <param-name>ActionConfig</param-name>
            <param-value>theseus-config.xml,theseus2.xml</param-value>
        </init-param>
        <init-param>
            <param-name>UseXSLCache</param-name>
            <param-value>false</param-value>
        </init-param>
        <init-param>
            <param-name>PopulateClassName</param-name>
            <param-value>org.theseus.beans.BeanUtils</param-value>
        </init-param>
        <init-param>
            <param-name>Hook</param-name>
            <param-value>org.theseus.servlets.ControllerServlet</param-value>
        </init-param>
        <init-param>
            <param-name>Debug</param-name>
            <param-value>0</param-value>
        </init-param>
        <init-param>
            <param-name>PreloadXSL</param-name>
            <param-value>false</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>
    
    <servlet-mapping>
        <servlet-name>Controller</servlet-name>
        <url-pattern>*.do</url-pattern>
    </servlet-mapping>
    
    <session-config>
        <session-timeout>30</session-timeout>
    </session-config>
    
    <welcome-file-list>
        <welcome-file>index.html, index.jsp</welcome-file>
    </welcome-file-list>
</web-app>

-----------------

There are a couple of things to mention here. First, the new init parameter is:

<init-param>
    <param-name>ActionConfig</param-name>
    <param-value>theseus-config.xml,theseus2.xml</param-value>
</init-param>

This is a comma seperated list of files to use, each being able to contain one or more mappings. Each mapping file has the syntax shown below. You can now place mappings into seperate files, thus making it more maintainable for larger applications. One way of using this feature is in the case where by you have two or more web-apps deployed in the same one servlet container. Using this allows you to break each application into its own config file for mappings. You may also have just one application deployed, but has many actions and many resources per action. The config file can grow quite large, so it is easier to maintain by breaking it into smaller chunks, preferrably by each module of the site. The syntax below shows how a config file should be written.

<mvc-app>
    <!--
      Comment
    -->
    <action name="ActionName"class="com.package.presentation.actions.ActionName">
    <bean name="ActionBean" class="com.package.presentation.beans.ActionBean"/>
    <forward name="ActionOK" resource="/path/page.jsp"/>
    <forward name="ActionError" resource="/path/error.jsp" xsl="/path/error.xsl"/>
  </action>

</mvc-app>

What you see above is a single action 'ActionName' being mapped to the class 'com.package.presentation.actions.ActionName' A javabean is used to handle any auto-population of forms (if its written in this manner) by the name of 'ActionBean' which uses the class 'com.package.presentation.beans.ActionBean'. There are two resources available to forward to. The first forwards to the jsp page /path/page.jsp if the return result is ActionOK. The second uses XSL to transform the output of /path/error.jsp into html using /path/error.xsl (an example of how easy it is to get xsl transformations to work using Theseus).

In the event a form is submitted to this action and the 'auto-population=true' request parameter is submitted with the link, Theseus will attempt to get (or create) the bean object at the HttpSession scope level (sorry, request scope of beans is not yet supported), then populate it using java reflection to match form element names to setter methods in the bean.

As always, feedback and contributions are more than welcome. We have set up a mailing list so that all who are interested can now participate in discussion of Theseus. To subscribe, send email to theseus-user-subscribe@yahoogroups.com. Please send all email concerning the project to this list so others can contribute in helping out, as well as we can all learn from reading what others are using. We will also try to set up a page that lists the statistics of Theseus use, as well as if anyone is able to send an email with a site that is in production with its use we'll list those. The reason for this latter one is simple, many companies are unwilling to invest in using free or open source software because of lack of use, support, etc. By showing a list of sites that use the framework in production, it makes it simpler for those of us trying to promote a good product for our boss's approval.

Once again, thanks to all for support and contributions. We look forward to discussion on the list and more features that all of us want added to the framework. To participate in discussion of Theseus, send email to theseus-user-subscribe@yahoogroups.com.

---