$Id: install.xml,v 1.24 2012/09/04 10:17:07 hannes Exp $
Copyright © 2006 - 2012 Hannes Holtzhausen
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Table of Contents
Java 2 Standard Edition 1.4.2 or later (http://java.sun.com/)
NOTE: Some of the optional software requirements require Java 6 or later.
Apache Ant 1.6.5 or later configured with Apache XML Commons Resolver. (http://ant.apache.org/ and http://xml.apache.org/commons/)
FreeMarker Template Engine 2.3.x ( http://freemarker.sourceforge.net/)
J2EE Servlet Container (Servlet 2.3 or later) or at least the Servlet 2.3 API's to perform builds.
The following list provides the optional software packages to enable additional functionality provided by the framework:
XMLBeans 2.4.0: Required when the servicegen tool is used to genarate service implementations. XMLBeans is also required when making use of the wsdesign skeleton project.
Apache Commons Net 2.0: Required when using toolbox.ftp and toolbox.services.ftp packages. genarate service implementations.
Version 2.0 can be downloaded from: http://archive.apache.org/dist/commons/net/binaries/.
Apache Commons Logging 1.1.1: Required when using toolbox.services.util.logging.* packages.
Apache Commons HttpClient 3.1: Required when using toolbox.services.util.logging.* packages.
Version 3.1 can be downloaded from: http://archive.apache.org/dist/httpcomponents/commons-httpclient/binary/.
Apache Commons Codec 1.3: Required when using toolbox.services.util.logging.* packages.
Version 1.3 can be downloaded from: http://archive.apache.org/dist/commons/codec/binaries/.
Apache CXF 2.7.x: Required by the wsdesign skeleton project. CXF is also required by various Toolbox API's that expose web services interfaces.
Apache Xalan-j 2.7.0: Required by the wsdesign skeleton project and simplexslt command line tool.
JExcelAPI: Required by the toolbox.file.Excel2CSVUtil class to read Microsoft .xls files.
JAMon: Required by the toolbox.object.JAMonToolboxObjectFactory and the toolbox.services.JAMonInterceptor classes. These two classes provide instrumentation for the framework to enable developers and users to monitor the internals of framework applications.
The lib directory of the framework contains a modified version of the Apache Commons IO jar file that facilitates the use of GZIP in copy operations using the FileUtils class of Commons IO. The jar is required when using the toolbox.file.File* utility classes.
Unix
Extract the distribution archive, toolbox_dist_b<x>.tar.gz, in a directory of your choice. After extracting the distribution archive, add execute permissions to the script files located in the toolbox/bin directory.
Windows
Extract the distribution archive, toolbox_dist_b<x>.tar.gz, in a directory of your choice.
Configuration
The framework requires the following environment variables to be set:
TOOLBOX_HOME: Must be set to the directory where the framework was installed. For example: /opt/toolbox
TOOLBOX_FM_HOME: Must be set to the directory where the FreeMarker Template Engine was installed. For example: /opt/java/freemarker
TOOLBOX_SERVLET_API: Must be set to the location of a jar file containing the Java Servlet API's (version 2.3 or later). For example: /opt/tomcat/common/lib/servlet.jar
TOOLBOX_CXF_HOME: Must be set to the directory where the Apache CXF version 2.6 service framework is installed. For example: /opt/asf/cxf
TOOLBOX_XMLBEANS_HOME: Must be set to the directory where Apache XMLBeans version 2.4 or later is installed. For example: /opt/asf/xmlbeans
TOOLBOX_XALAN_HOME: Must be set to the directory where Apache Xalan-j version 2.7.0 or later is installed. For example: /opt/asf/xalan-j
TOOLBOX_COMMONS_NET_HOME: Must be set to the directory where Apache Commons Net version 2.0 is installed. For example: /opt/asf/commons-net
TOOLBOX_COMMONS_LOGGING_HOME: Must be set to the directory where Apache Commons Logging version 1.1.1 is installed. For example: /opt/asf/commons-logging
TOOLBOX_COMMONS_HTTPCLIENT_HOME: Must be set to the directory where Apache Commons HttpClient version 3.1 is installed. For example: /opt/asf/commons-httpclient
TOOLBOX_COMMONS_CODEC_HOME: Must be set to the directory where Apache Commons Codec version 1.3 is installed. For example: /opt/asf/commons-codec
Add the toolbox_core.jar file, located in the lib directory of the toolbox installation, and the freemarker.jar located in the lib directory of the FreeMarker installation to the CLASSPATH of your J2EE Servlet Container.
The toolbox distribution contains a very simple web application that can be deployed to a J2EE Servlet Container supporting Servlet specification 2.3 or higher. The war file is named:
doc/sample/web/simple/simple.war
Deploy the war file to your servlet container and verify that the deployment was successful by accessing the application with the following URL from a web browser:
http://yourserver/simple/controller?template=/htdocs/main.html
If successful, the browser will present an HTML form containing two inputs:
Message Page (success|failure)
The Toolbox Application Development Guide provides a step by step guide to developing your first framework application.