Expresso Installation Instructions

This document describes how to install Expresso and get it running on your system. These instructions refer to installation of Expresso as a web-application archive (e.g. the expressoXX-X-src.zip or -bin.war downloads of Expresso). We recommend you refer to the "Setup" page on the Expresso Demo Menu for additional detailed instructions on how to download Expresso, and how to configure it for your own server once you've completed this installation procedure.

Version:

Expresso 5.5

Maintainer:

Geeta Ramani

Introduction

These instructions refer to installation of Expresso as a web-application archive (e.g. the expressoXX-X-src.zip or -bin.war downloads of Expresso).

We recommend using the Expresso Complete bundle, which has the Tomcat servlet container already bundled and configured with Expresso, and is therefore much easier to install.

Use the Expresso Complete Installation Instructions for the "-complete.jar" download file instead of this document.

This document provides an overview, but be sure to see the detailed step-by-step setup and installation instructions on Setup page within the Expresso application onsite.

Before starting with the instructions below please be sure to read the following:

System Requirements
Before starting, please review the System Requirements to ensure your system is able to run Expresso.
Download
The first step is to download Expresso's source code and supporting files. These instructions refer to installation of Expresso as a web-application archive (e.g. the expressoXX-X-src.zip or -bin.war downloads of Expresso). Expresso can be freely downloaded from here. Early access releases are also available to registered users. A new dev snapshot version is also available onsite each day; and the source for the .jar files included is available separately via the CVS archive, but is not normally required for using Expresso.
System Prerequisites
Before starting the install process, please review the System Pre-Requisites to ensure you are ready. You can simplify the server and database steps by using the Expresso Complete bundle, which has the Tomcat servlet container already bundled and configured with Expresso. Without Expresso complete there is addition steps that make it straightforward ONLY IF, you have all the pre-requisites in place. It is suggested that this be attacked as a completely separate project, and completed before any attempt at installing Expresso is made.

Please see the LICENSE file for details about the license under which Expresso is available.

Web Application Installation

This installation procedure is intended for environments that support the Servlet API 2.2 or higher standard (e.g. web-applications). It is highly recommended that this procedure be used if possible. The older method listed below is also still available, and should be referred to for pre-2.2 environments.

Before You Start

Please review the requirements and pre-requisites document referred to above before you begin installation - it is important to verify that your environment is ready before beginning.

You should have one .war file (expressoXXXX.war, where XXXX is the version number of the current version of Expresso), and one or more Jar files if you are installing component applications (like eForum, ePoll, etc).

If you have already installed Expresso and have verified that it is operational, and want to install a component application, see the component application installation documentation.

Installation Procedure

Choose a Web-app directory - Select a directory into which you will install Expresso. This directory will be known as Expresso's "web-app" directory, and should *not* be within your application server's document root. For example d:/expresso or /usr/expresso.
Expand the .WAR file - Copy the War file containing Expresso into the web-app directory you have chosen (you must create the directory if it does not exist). In the directory, execute the following command:
```
jar xvf expresso-4-1-bin.war
```
Replace the "expresso-4-1-bin.war" with the appropriate name of the current .WAR file distribution of Expresso. Note: Some application server's will expand War files for you automatically if they are placed in the correct deployment directory. Refer to your application server's documentation for the specifics.
Remove the .WAR file - Move the original War file to another directory or delete it. (Some application servers do not require this)
Register the application with your Application Server - The procedure to register the application with your application server varies. Here are notes for some of the popular application servers:
Restart your Application server - Stop and re-start the application server if necessary to cause it to recognize the new application
Adjust for an old Tomcat XML library if necessary - if you are running Tomcat, it may come with an OLDER "xerces" XML parser than Expresso uses. You must replace the old parser jars with the newer ones that come with Expresso. If you fail to replace them, you'll get an error like
```
			javax.servlet.ServletException: Cannot inherit from final class
			...
			at org.apache.xerces.impl.XMLNSDocumentScannerImpl.createContentDispatcher(Unknown Source)

			...
			
```
Do the equivalent of the following unix commands:

  rm $catalina_home/common/lib/xerces*
  rm $catalina_home/common/lib/xml-apis*
  cp $expresso/WEB-INF/lib/xercesImpl.jar   $catalina_home/common/endorsed/
  cp $expresso/WEB-INF/lib/xml-apis.jar      $catalina_home/common/endorsed/

The reason is that Tomcat doesn't need the updated Xerces, so they ship with the old one that works for them. But Expresso needs the bug fixes. All of this can be avoided if you use the "complete" download which includes Tomcat (already updated), or if you use a different servlet engine like Resin.
Test the Installation - Execute the following URL in your browser: http://yourserver/expresso
An example of this which would be used for a Tomcat installation is: http://localhost:8080/expresso
You should substitute the name of your web application server for "yourserver", and add the appropriate port number if it is not port number 80.

You should see the administrative page for Expresso appear in a few seconds (there is a pause while the application initializes - subsequent pages will appear faster, particularly after their first use).

You may Login (the initial "Admin" user is set up and initially has no password) and begin using Expresso. User names are case sensitive

If you have problems accessing the main expresso page, try the URL :http://yourserver/expresso/frame.jsp

If this works, your application server might not be recognizing the < welcome-files > tag in the web.xml file. If this doesn't work either, try: http://yourserver/expresso/index.html which should display a simple HTML page - this lets you know that "expresso" (in this example) is the correct web-app prefix for Expresso.

You can also try: http://yourserver/expresso/test.jsp to execute a very simple JSP page to ensure JSP's are working correctly for your installation.

Customize your Installation

Expresso is initially configured to use the default.properties file found in the "config" directory inside your web-app directory. You can modify the WEB-INF/web.xml file to point to a different directory with your own custom default.properties to enable Expresso to use your own database and other configuration values. This is recommended, as the included Hypersonic SQL database and properties are not configured suitably for production use of Expresso. You can also add additional properties files to the existing "config" directory to work with multiple contexts.

This concludes the installation process.

Installation Procedure when not using Web Application Support (e.g. Servlet API prior to 2.2)

Installing the Files

Note: These installation instructions are for non-servlet API 2.2 environments. The updated installation method above is recommended where possible.

You should have downloaded 1 file, the Expresso web application archive (War) file. The War file archive is usable with the standard "jar" utility included with your Java runtime.

To uncompress the War file into separate files and directories, the command is jar xvf expresso-4-1-bin.war. (replace the 4-1 with the appropriate version string as required)

The War file archive is organized in a specific directory structure - it contains the following directories:

Root Directory (e.g. the top-level directory when the War file is un-jared) - This directory contains the top-level JSP files for Expresso as well as the LICENSE file, giving details of the license Expresso is released under, and SUPPORT, which discusses the premium support options for Expresso.
WEB-INF -This directory contains the web.xml file, used to define to Servlet 2.2-compliant containers the servlet mappings used by Expresso. It can be used as a guide to the definitions required for other servlet containers as well.
WEB-INF/classes - This directory contains the sub-directory com and it's subdirectories, which contain the .class (and .java) files for Expresso. Within the com/javacorporate directory you will find directories db, dbobj and common. When installing in a non-2.2 environment, the "classes" directory should be added to your classpath. You will also need to add "classes" to your classpath to run the Expresso command-line tools, such as DBTool.
doc - This sub-directory contains the documentation for the Expresso Framework, including this file and an index.html file in this directory.
jsp - This directory contains common jsp files used by both Expresso and applications built using Expresso, such as login.jsp.
style - This directory contains the cascading stylesheet files used by Expresso (and, optionally, Expresso applications) to provide a consistent look & feel to HTML and JSP pages. You can change the look of all Expresso pages at once by modifying the files here.
help- This directory contains the "help" files used to provide a brief description of each function in Expresso.

As an example, let's say the "root document" directory of your web server is /usr/web. If you then create a directory /usr/web/components/expresso directory, then UN-jar the War file in this directory, then the URL for Expresso's main page would be http://yourserver/components/expresso/frame.jsp. The documentation for Expresso would be accessible from http://yourserver/components/expresso/doc/index.html.

NOTE: If you are using a 2.2 servlet API compatible container (including any J2EE compliant application server, see the J2EE installation notes.

If you are not using a 2.2 servlet API compatible container, you would probably want to move the WEB-INF/classes directory to somewhere other than under the root directory of your web server - otherwise users might be able to browse directly to your Class and Java files, which you probably don't want. The classes directory can be located anywhere, as long as it's included in your servlet container's classpath.

While the HTML and JSP files that are included with Expresso allow you access to all of it's functions, they may not of course be ideal for your use of Expresso. You will probably wish, for example to change the "Home" link in the toc.jsp file to point to the appropriate place for your web site.

Note that you must use the Expresso HTML/JSP files in conjunction with a web server - they will not operate correctly if you access the files directly from your file system (e.g. without the http: prefix).

Installing the Javadoc

The Javadoc download for Expresso can be installed in any directory under your root web directory. It will also create a number of subdirectories, all within a parent directory called "javadoc". You should start with the "index.html" file in this Javadoc directory in order to browse the Javadoc properly.

Compiling Expresso

Expresso is supplied as source code and object code, and need not be compiled before use.

NOTE: For information on setting up an automated build process for Expresso using the Apache "Ant" tool.

To compile the files:

Set your CLASSPATH to include the directory where you unpacked this release. It should contain the top-level directory 'com', \ which has in it 'javacorporate', etc. The CLASSPATH should also include EVERY jar file located in the WEB-INF/lib file.
Make sure that your PATH includes the 'javac' Java compiler or other compiler of your choice. ( For Linux users, try IBM's Jikes compiler - very fast. )
cd to the com/javacorporate/dB directory and issue: javac *Java
CD to the com/javacorporate/dbobj directory and issue: javac *Java again
continue to perform this compile in each source directory (including com/javacorporate/common and all sub-directories).

For those of you using Windows NT, the following command might be useful:

for /r %d in (.) do javac %d\*Java

That will recursively walk the tree and compile all the Java files. Do not be alarmed if you get some errors when the com/javacorporate/common/jsdkapi stuff compiles (one of the files there is only required if you need Servlet API 2.0 support).

You may of course wish to register these files with your IDE of choice, such as Elixir, VisualAge, Java Workshop, etc. It is also possible to create Makefiles to automate the compile process.

Servlet Servers

Once you have compiled all of the files, you need to set up your servlet runtime engine to recognize the Expresso servlets. The way this is done differs from one servlet engine to another. There are links for details on some of the more common servlet engines below, but Expresso should be able to be configured with literally any servlet engine that supports at least the required level of the Servlet API.

All servlet engines will require each of the servlets in Expresso to be registered, and will provide some way for arguments or parameters to be supplied to the servlets. If you are using a servlet 2.2-API compatible container, or any J2EE application server, the supplied web.xml file can be used for this purpose. The servlets that need to be registered are as follows:

Note: The object name for every servlet is comprised of "com.javacorporate.common.servlet." followed by the servlet name itself.

Servlet	Description
DefaultInit	Read the configuration properties file on servlet engine startup. This servlet takes a single argument, "configDir". This argument should refer to a directory in which one or more properties files are found. This servlet should be set to run when the servlet engine starts (often called "autoLoad" or "preLoad").
DefaultViewHandler	Automatic GUI rendering system
XMLViewHandler	XML Rendering System
PathHandler	Servlet to allow automatic 'non-?' URLs to reach various controllers' resources.
ExcelViewHandler	Microsoft Excel Rendering System
DBCreate	Initialize database, providing options for creating default security access.
Action	Struts Action Servlet to provide Servlet to Expresso Controller Mapping.

None of the servlets except DefaultInit require any argument to be supplied by the servlet engine. Many of them take arguments when they are called, which are discussed separately.

The DefaultInit servlet reads a property file, which should contain name=value pairs, one per line, for at least the following properties. The name of this properties file is not important, as all files in the specified directories are read. Be sure not to store other files in this directory, or they will be read as properties files as well - particularly important is not to store old properties files, as this will result in both files being read.

Additional Notes for Specific Servlet Engines

You'll find notes specific to installing Expresso on certain servlet engines under the Expresso documentation link.

If anyone has specific notes about installing Expresso with other servlet engines, we would appreciate input so that we can include more details in this section, thanks.

Servlet Engine CLASSPATH's

Many servlet engines have a special directory (often called "servlets") where servlets that you develop can be deployed, without having to add to the servlet engine's CLASSPATH. This ordinarily will NOT work with Expresso - you have to actually specify a CLASSPATH that points to the location where the com/jcorporate/ directories can be found.

Once you have completed basic installation, you should continue with the Setup page with the Configuration step.

Administrative Login Password

Now you have completed the installation. :) Now you are ready to Login and begin using Expresso.

Login as "Admin" and leave Password blank

Example Applications

To make it easier to get rolling with Expresso, there are some "Example" applications available. Example documentation explains how to access the demo applications and how to use them as a basis for developing your own applications with Expresso. You might begin with a sample application such as:

Expresso Examples Project for several examples including an Expresso Tutorial.
Orange Trader Example Web Application and related article.

Also under the Examples project there is also an effort community underway onsite to develop an Expresso J2EE Pet Shop example application. This example will illustrate Sun's Java BluePrints guidelines and patterns implemented using the Expresso Framework. This sample application will shows how to use the capabilities of the J2EE 1.3 platform to develop flexible, scalable, cross-platform enterprise applications based on the Expresso Framework.

After working with Example applications, the next step will be to install other applications, such as eForum or begin development. Here are some references for beginning to develop your own application.

Conclusion

So what is the next step you might be asking? Expresso has some optional features that you may want to download the appropriate 3rd party jars to take advantage of those features.

Bouncycastle: The Bouncycastle jar file does not get distributed with Expresso right now due to export restrictions. Download the jar that contains the files called: jce-jdk13-123.jar which works in both JDK 1.3 and JDK 1.4 fine. The crypto is used by Expresso itself... So you'll need it in your WEB-INF/lib directory. The ant build file can get it for you.... just run the get-crypto target and it will automatically deposit the appropriate bouncy castle JCE provider in the lib module's WEB-INF/lib directory where the rest of the build system will pick it up.

If you get a bug that has you hung up, it will likely get fixed very quickly with the community collaboration in which case you will want to download the daily -dev download.

In closing here are some additional Reference Material resources:

Getting Started Users Guide: Some commonly asked questions about next steps including setting up Different Database and/or Servlet Engine, and an introduction to developing with Expresso.
How To Users Guide: An excellent reference when you are first starting with Expresso.
Expresso Developer's Guide: to provide the Java developer with the information needed to develop with the Expresso Web Application Development Framework/Component Library.
Model-View-Controller Architecture Explained by Sun: By applying you separate core data access functionality from the presentation and control logic that uses this functionality. Such separation allows multiple views to share the same enterprise data model, which makes supporting multiple clients easier to implement, test, and maintain.
Struts Users Guide: This project which is integrated into Expresso, encourages application architectures based on the Model-View-Controller (MVC) design paradigm, colloquially known as Model 2 in discussions on various servlet and JSP related mailing lists.
DBMaint: A Step-by-Step Example: Address both an introduction to the directory structure as well as walks the user through a step-by-step example.
Best Practice with Expresso Framework with Struts
For Expresso tag library examples to demonstrate best practices please see dbmaint, Login and Registration jsps as examples.
Books: Hans Bergsten 'Java Server Programming' book or 'Professional JSP' published by Wrox.

Contributors

Contributors to this document include: Sandra Cann, Geeta Ramani, and Larry Hamel

If you find any trouble spots with this document, or something you'd like to see clarified please contact the maintainer of this document.