This document explains how to get the ACS Java system running for testing and review purposes. The high level tasks are as follows:
Table of contents:
ACS Java requires that you have version 1.3 or higher of the JDK installed. You can get this by going to Sun's download page and grabbing the right tarballs. When you get done, you should be able to run the Java compiler (javac) and the Java runtime interpreter (java) from the command line.
While you are at Sun, you might also look at the J2EE pages. We make use of some
J2EE libraries, like JDBC, the servlet stuff, and JavaMail. You'll
need to get at least the j2ee.jar file to make ACS
work. You can download this here.
The ACS Java 4.0 distribution includes the Tomcat servlet
engine and the Ant build system, so you don't need to set these up
yourself. Both of these excellent tools are produced by
the Jakarta project. Ant is a
program for managing builds, much like make, but
optimized for Java projects and written in Java. Most projects that use Ant
require you to use Ant directly. The version of Ant that is installed for you
is still capable of being used in this way and for other projects. ACS Java
provides an interface to the build system through the APM utility. APM is invoked by doing the
following in the ACS Java directory:
./run ./apm <arg>If no argument is specified, a full listing of usage information will be printed.
Tomcat is the server we've been using for our development, and by including it in the distribution we were able to make it somewhat easier to try out ACS Java. ACS Java has been tested under BEA Weblogic and Resin. Instructions on configuring ACS Java to work under Resin are available.
Get the latest release of ACS Java 4.0 from the ACS Repository.
The tarball is named acs-java-4.0-install.tar.gz. Run
the following commands to install and configure ACS Java:
gzip -d acs-java-4.0-install.tar.gz tar xf acs-java-4.0-install.tar cd acs-java-4.0-install sh install-acs.sh
The install-acs script will ask you for the directories where you would like Ant and Tomcat to be installed. After installing Tomcat, it will also install acs-java-4 in the Tomcat webapps directory.
The install-acs script will automatically proceed to run another
script called configure.sh. This will ask you to locate
your JDK, J2EE, and Oracle installations, as outlined in the prerequisites. It will then ask you which port
number the ACS Java server should use, and which username and password to
use to connect to the database. Finally you have the opportunity to
specify a JDBC database connection string and the path for the ACS log
file, although the default values for these are usually what you want.
Having obtained this information, the script proceeds to edit several configuration files:
$ACS_JAVA/paths.sh - used to setup a set of path variables
and a CLASSPATH for using ACS Java.
$ACS_JAVA/run - A command-line utility that sets up the
environment for executing the build system, e.g. ./run ./apm <cmd>
$ACS_JAVA/run-server - Used to setup the environment for
executing the servlet engine, e.g. ./run-server $TOMCAT_HOME/bin/startup.sh
$ACS_JAVA/acs.properties - used by the build system
and all ACS Java code to obtain configuration settings.
$ACS_JAVA/WEB-INF/web.xml - used by Tomcat to
initialize the ACS Java webapp.
$TOMCAT_HOME/conf/server.xml - a Tomcat startup
file in which we map all requests to the ACS Java Request Processor.
Before you can install the ACS data model, you need to create a new Oracle tablespace and user. For example, you could enter the following in SQL*Plus:
create tablespace frosty datafile '/ora8/m02/oradata/ora8/frosty01.dbf' size 50m autoextend on default storage (pctincrease 1); create user frosty identified by snowman default tablespace frosty temporary tablespace temp quota unlimited on frosty; grant connect, resource, ctxapp, javasyspriv to frosty;
For more information about Oracle setup, refer to the ACS Install Guide
At this point, we'll assume that you have set ACS_JAVA to
be equal to $TOMCAT_HOME/webapps/acs-java-4. Use
setenv (tcsh), or export (bash) to set this up.
From the $ACS_JAVA directory, type the following command:
./run ./apm install-acs
This will build ACS Java from the source code, and if all goes well, will proceed to install the ACS data model. If you've already loaded the data model, you can just rebuild the project with the command
./run ./apm build
To start tomcat in standalone mode, go to the $ACS_JAVA
directory and type the following command:
./run tomcat.sh start
You can now access your server over HTTP. You can login as
system@localhost, password: changeme.
/tomcat/webapps/acs-java-4 >./run java com.arsdigita.apm.JdbcCheckupIf this test fails, you will need to debug your Oracle and JDBC configuration. A common way to prevent this from working is if your Oracle home is not set correctly. Read over the paths.sh file and make sure everything is correctly set.
|
Notes on configuring Tomcat
Configuration files for Tomcat are in the $TOMCAT_HOME/conf directory. Files of interest are server.xml and web.xml. You do not need to touch web.xml. You must edit server.xml to reflect your configuration. This is where you set up ports, IP addresses to listen on, etc. Regardless of whether you're running in standalone mode or with Apache, you have to edit this file because apache also communicates with tomcat over TCP/IP. Each listener for Tomcat is called a "Connector." Connectors have Handlers associated with them, and there are two you need to care about: HTTP handlers and AJP hndlers. The HTTP handler is the one that handles incoming HTTP requests from the web. The AJP (Apache/Jserv Protocol) handler is used to signal Tomcat to shut down in standalone mode, and for Apache to communicate with Tomcat with mod_jserv. A HTTP handler section looks like this: <Connector className="org.apache.tomcat.service.SimpleTcpConnector"> <Parameter name="handler" value="org.apache.tomcat.service.http.HttpConnectionHandler"/> <Parameter name="inet" value="216.251.19.135"/> <Parameter name="port" value="8001"/> </Connector> There is probably already a section that looks like this in your server.xml file. You only need to change the port setting. The inet setting is optional; if you don't supply an address, though, your Tomcat server will listen on *ALL* of your available interfaces! (this is generally bad!) An AJP section looks like this: <Connector className="org.apache.tomcat.service.SimpleTcpConnector"> <Parameter name="handler" value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/> <Parameter name="port" value="8007"/> <Parameter name="inet" value="localhost"/> </Connector> Again, only thing you need to touch is the port setting. 8007 is the default port. If you're having trouble shutting down Tomcat or starting Tomcat, you probably have a port conflict. Notes about the ACS 4 Java "Web Application"In Tomcat (and J2EE in general), servlets, JSPs, HTML files, and support classes are bundled into "web applications" or "webapps" for short. An installation of ACS Java is a webapp. Note that each ACS application is still part of the same webapp. But if you are running on a machine with several different instances of ACS Java installations (e.g., different developers, or different client projects) then each ACS Java install is its own webapp. Each webapp in tomcat resides in a directory under $TOMCAT_HOME/webapps. So, if you run "cvs checkout acs-java-4" in the $TOMCAT_HOME/webapps directory, you'll have an acs-java-4 webapp installed and ready to run. Although Tomcat will detect the ACS 4 Java web application on startup, it should be configured so that the context path is set to "/" (root). This way, an URL request for "/index.jsp" will serve $TOMCAT_HOME/webapps/acs-java-4/index.jsp. Otherwise, redirects and links won't work. The context section in server.xml looks like this: <Context path="/" docBase="webapps/acs-java-4" debug="1" reloadable="true"> </Context>
The actual setup of the ACS Java web application is done in
|
Last Modified: index.html,v 1.2.8.2 2001/03/26 20:39:11 bquinn Exp