Installation Guide

Getting Arch4J

Please see the download guide.

System Requirements

Please see below for more information on the required libraries, versions, and how they pertain to each of the modules available within Arch4J.

For the current version of Arch4J, you will also need JDK version 1.2 or later installed on your system.

Installing Arch4J

The binary distribution of Arch4J consists of two directories: lib and examples.

The lib directory holds a jar containing the complete build of the code (arch4j) and individual jars for each module. The examples directory holds example property files used to configure the various modules contained within Arch4J. Simply add the desired jar or jars to your CLASSPATH.

In order to use some of the features, you may need to download one or more of the required library files. Then add the additional jars to your CLASSPATH.

Building Arch4J

Arch4J uses Ant to perform the build. Most of the 3rd party libraries required to build Arch4J are included in the source distribution, since they are allowed to be distributed along with Arch4J. Some libraries are not, though; you will have to download and install these separately before building Arch4J. They are listed below in the Required Libraries section.

To build Arch4J from source, unpack the Arch4J source distribution. At one time, a script named build was used to build Arch4J. You were required to store the extra required libraries into a reqlibs directory at the top of the distribution tree. This is no longer the case, although the script has been retained for backward compatibility.

The preferred way to build now is to use the script included in the Ant distribution, which is named ant. To use it, the JAVA_HOME environment variable must be set to where your JDK is installed, the ANT_HOME environment variable must be set to where Ant is installed, and the Path environment variable must include the <JAVA_HOME>/bin and <ANT_HOME>/bin directories.

Instead of the reqlibs directory, you can tell the Ant build script where your required libraries are installed by using a property file named build.properties. To create one, change to the installation directory and open a command window. Then use the following Ant target:

This will create a sample file that you can edit to specify where the required libraries live on your system.

To see all of the targets available, type:

To build the all-in-one jar containing all of the classes, simply type:

This executes the default target (main). Each module can be built separately, either with or without building dependent modules. For instance, to build the data access module, and the required base module:

From then on, you only need to rebuild the data access module:

There are also targets to clean up and targets to build the various distributions.

Ant has additional options that can be set:

Setting Up

Once Arch4J is installed, you'll need to decide which modules you're interested in, configure some property files, and possibly code and configure adapters to any third party products you're using.

Choosing Modules

Arch4J was designed to be highly modular. If you plan on using most or all of the modules, simply add the arch4j.jar file in the lib directory to your CLASSPATH. This file contains the complete build of all the code.

If you plan on using only one or a few of the modules, just add their respective jar files to your CLASSPATH. Some of the modules require other modules or third-party libraries. Consult the Feature List for more information.

Setting Up Property Files

Many of the modules utilize a property file for configuration information or for identifying classes that implement a particular interface defined within the module. For example, the database connection information, identifying the driver, url, and authentication information is stored in a property file named dataaccess.properties.

All of the modules that use property files access them via a property file service provider supplied by the Base module. The property files for all modules are stored in a single directory, and that directory can exist anywhere on the system. The property file service provider needs to know where this directory is, so that location must be set when the Java VM starts up.

The easiest way to do this is to set a system property on the command line that starts the VM. The property name is arch4j.property.directory and can be set using the -D command line argument.

For example:

A set of example property files come with Arch4J and can be found in the examples directory. More information on specific property keys and values is included in the documentation for each module.

Service Providers

Many of the modules contain a service provider class, implemented as a singleton factory, which can be used as the starting point for accessing the services provided by that module. For example, the provider in the Data Access module has a method to get a connection to a database via a simple logical name so that you can query data.

Third Party Adapters

Some of the modules use an adapter class to access third party software. For example, the messaging module may need to access JMS message queues through the WebLogic JMS server. In order to avoid direct dependencies, an adapter specific to the third party software must be coded. This adapter class is then referenced by a property file and loaded by the module's service provider. We intend to provide adapters to the most common products for each module.

Module Dependencies

The following section lists the modules included with Arch4J and the dependencies they have, either on each other or on third-party libraries (from the list above). Therefore, if you decide to only use one or two modules and put them in your CLASSPATH, you also need add the dependents to your CLASSPATH.

* NOTE: The WebLogic application server needs to be installed separately, and any jars or classes made available on the CLASSPATH. If you are using a different application server, such as JBoss follow the Weblogic adapter example to create an adapter for your application server. The adapter is the only place that application-server- specific classes are imported, so there is no dependency within Arch4J on a particular application server. That was sort of the point, after all.