ITC382 11255412 A1B

From PeacockWiki

Technical Report

Brief installation overview

1. Acquire Java JDK, Apache Ant, Eclipse 3.1.x, Tomcat 4.1.30 (Newer versions should work fine), Tapestry 3.0.3, and optionally the Spindle 3.2.0 update site zip (or download directly using eclipse).
   Links
   • JDK 5.0 Update 4
   • Apache-ant-1.6.5-bin.* (multi-platform distribution)
   • Eclipse 3.1
   • Tomcat 4.1.30
   • Tapestry 3.0.3
   • Spindle 3.2.0 update site zip
     or
   • "http://spindle.sourceforge.net/updates" site update in eclipse "Find and Install" (after eclipse is installed)
2. Install Java, Apache Ant, and Tomcat. Use Ant to deploy Tapestry to the tomcat install.
   • Execute the Java download file, and follow wizard.
   • Extract the ant archive to a permanent location, and add the bin directory to the your path.
   • Extract the tomcat archive. Either add JAVA_HOME to your environment variables, or set the variable in the startup and shutdown scripts in the bin directory. JAVA_HOME points to the installation point of the JDK, the directory above the bin directory containing java.exe and javaw.exe.
   • Extract the tapestry archive to a temporary location, and follow the instructions in Readme.html under "Configuring Tomcat"
     I found the the install failed on downloading Javassist, if you have this problem, try editing the javassist.loc property in config/common.properties, replacing the server telia.dl.sourceforge.net with your own choice of sourceforge mirror, or simply replace the entire link with a selection from http://prdownloads.sourceforge.net/jboss/javassist-2.5.1.zip?download
3. Copy tapestry libs into tomcat lib folder
   • Copy all files from webapps/workbench/WEB-INF/lib to shared/lib. Alternatively, ensure these files are copied into webapps/project-name/WEB-INF/lib for every tapestry webapp.
4. Install Eclipse and Spindle
   • Extract the eclipse archive to a permanent location, and run the executable.
   • Select Help → Software Updates → Find and Install, choose Select new features to install.
   • Proceed with one of the following
     • Choose New Remote Site, and enter the name Spindle, and the UpdateSite URL (http://spindle.sourceforge.net/updates)
     • Extract the UdateSite Zip, choose New Local Site, and select the location of the extracted files.
   • Click Finish
   • Explore the tree and select "Spindle 3, and Eclipse Plugin for Tapestry 3.2.0"
   • Proceed through the wizard to install spindle
   • Restart the workbench when prompted

Sample project

This section will detail the construction of my sample project, how it works, and problems and solutions encountered in its development.

Creating the project

File → New → Project (or first icon on toolbar)

Name the project ("lists")

Continue Next, and Finish (leave all options default).

Set project compiler options, right click on the project, and choose Properties. Select Java Compiler, and select Enable Project Specific Settings. Choose a Compiler Compliance Level of 5.0. (alternatively this can be done through Window → Preferences → Java → Compiler, to set this property for all projects)

Open web.xml, and add the following lines

    <filter>
        <filter-name>redirect</filter-name>
        <filter-class>org.apache.tapestry.RedirectFilter</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>redirect</filter-name>
        <url-pattern>/</url-pattern>
    </filter-mapping>

The default path of a Tapestry app is /app-name/app . If you visit /app-name/ you will recieve an error. These lines will instruct the servlet container (tomcat) to redirect the client to the application.

Open Home.html and place some text between the body tags. Save the file.

Download tomcat-local-deploy.xml and import it in the root directory of the project. Open the file in eclipse, and check the properties match your local configuration, then choose Run → External Tools → Run As → Ant Build. This should install the test app into your tomcat installation, which should be visible by point a browser to http://localhost:8080/lists/ .

The Scenario

This app is designed to allow a user to browse mailing list archives. My mail server runs Apache James, and it is set to save mailing list emails in a designated directory. For the purposes of this test i am using a sample arvhive. The arcive may be extracted to C: root (C:\), it will create a TEMP directory with the following structure

C:\
  TEMP
    lists
      lists
        4D61696C313131303238393436363630312D30.Repository.FileStreamStore.txt
        4D61696C313131303436313636363131392D3932.Repository.FileStreamStore.txt
      test
        4D61696C313131303238393436363630312D30.Repository.FileStreamStore.txt
        4D61696C313131303436313636363131392D3932.Repository.FileStreamStore.txt
        public

This application has no security built into it, apart from the fact you cant access a private group unless you know its name. Public archives are marked by an empty file named public in that archives directory, and are listed by the app for all to see.

Download the archive, and extract it to C:\ . If you do choose another application, be sure you change the path in the java code later on (for this demo the path is hard-coded in the app).

Page Layout

First thing to do is to create a page template that can be used by all pages in the app. To do this create a new component in Eclipse (File → New → other → Tapestry → Tapestry Component). Name the component "Page", and leave all options as default. Page.jwc is fine as default. Page.html should contain the following

<html jwcid="@Shell" title="Mail Lists">
  <body jwcid="@Body">
    <span jwcid="@PageLink" page="Home">Home</span><br />
    <span jwcid="@RenderBody">Page content goes here.</span>
  </body>
</html>

Tapestry components are called by the inclusion of a jwcid attribute in a html tag. The original tag is ignored by tapestry, but is included so normal WYSIWYG editors can sucessfully edit the file, and the tag is normally made to be the same as the tapestry component used will generate. Span tags are typicaly used when the coponent will not return a html tag (for eg. if it just returns a line of text). Additional parameters may be sent to the tapestry component simply by adding them as normal parameters in the HTML tag.

Shell and Body construct the HTML and BODY tags, and are not absolutely necessary, as these tags could be entered manually. Shell and body simply save a bit of time.

PageLink creates a link to the specified page, in this instance "Home". So every page using this template will have a link to the main page of the app.

Now open Home.html, and replace any content with the following.

<span jwcid="@Page">
   Select a List to view:<br/>
</span>

As you can see, this template calls the Page component defined above.

The RenderBody tag in the Page.html takes the content of the calling template (in this case "Select a List to view:<br/>"), and passes it through the tapestry engine to be processed and outputted to the browser.

The ant build script should be able to be run now, and by refreshing the browser you should see a page with a link and a line of text.

Selector Component