Sample Application Build Facility
iPlanet^TM Application Server Samples

This product includes software developed by the Apache Software Foundation (http://www.apache.org). Specifically, the Ant Java based build tool is included as part of iPlanet Application Server.

If you are either using Deployment Tool to assemble and deploy the application or modifying the sample application source code to experiment with J2EE, then you will need to recompile the source code and rebuild the J2EE applications. To help you easily compile the sample applications and to rebuild the EJB JAR, WAR and EAR files, a compilation environment has been created based on the Ant technology from the Apache organization. Ant is a platform independent Java-based build tool that offers make-like features. Ant version 1.2 is bundled as part of iPlanet Application Server.

• Benefits of Using Ant
• Ant Environment in iPlanet
• Using the Build Facility
  
• Install Client Target for RMI/IIOP Samples
• Build Examples

Benefits of Using Ant

Many server side Java developers have found Ant to be an extremely useful tool for accelerating the development cycle associated with J2EE applications. Ant contains many built-in functions that relieve the burden of repetitive development tasks. As described in the Ant documentation, "In theory it is kind of like make without make's wrinkles". For more information about Ant, see http://jakarta.apache.org/ant/index.html.

Ant Environment in iPlanet

The following build targets are represented in the build.xml files accompanying the sample applications. Presence of a target depends on the type of J2EE application. For example, an application that does not contain EJBs will not support the stubs and ejbjar targets. Since the Java Pet Store application from Sun Microsystems already includes build.xml files, you might notice that not all of the following targets are represented in the Java Pet Store sample application bundled with the application server.

Target	Function
compile	compiles all Java source code.
stubs	executes iPlanet's EJB compile, ejbc, to build iPlanet-specific EJB stub and skeleton classes.
ejbjar	assembles the EJB JAR file in <appname>/assemble/jar/.
war	assembles the WAR file in <appname>/assemble/war/.
ear	assembles the EAR file in <appname>/assemble/ear/.
core (default)	compiles all sources, builds stubs/skeletons and assembles EJB JAR, WAR and EAR files. This is the default target for all build.xml files shipped in iPlanet Application Server.
javadocs	creates Java docs.
all	builds both core and javadocs.
install	installs Java docs in <appname>/docs/api/ and deploys the application to the local application server.
install_ear	deploys app, automatically expands EJB JAR, but does not install Javadocs.
deploy	same as "install_ear".
install_client	deploys client classes to ias/rmi-client/.
clean	removes <appname>/build/ and <appname>/assemble/ content.
fixforunix	removes DOS carriage returns and EOF characters from *.jsp, *.java, *.sh, *.xml , *.html and *.sql text files.

Using the Build Facility

1. Set Your Environment

In order to use the Jakarta Ant tool to compile and reassemble the sample applications, you will need to ensure that the application server's bin/ directory is in your environment's path. On NT, since during installation of the application server, the System PATH variable is automatically set to include install_dir\ias\bin, you will not need to manually set the PATH.

On UNIX, you will need to add the install_dir/ias/bin directory to your PATH environment variable.

2. Compile and Assemble a Sample Application

Using the simple HelloWorld sample as basis, execute several of the build targets.

Change to the HelloWorld sample directory:

cd install_dir/ias/ias-samples/helloworld/src

Execute the compile target to compile the Java sources:

build compile

Execute the stubs target to execute the EJB compiler (ejbc):

build stubs

Execute the war, ejbjar and ear targets to assemble the J2EE module files and the EAR file:

build ejbjar
build war
build ear

Alternatively, you could accomplish all of these tasks by simply executing the core or all targets:

build core

Since the dafult build target is core, you could execute build without arguments to rebuild the entire application:

build

Install Client Target for RMI/IIOP Samples

If you are experimenting with accessing EJBs using RMI/IIOP clients on the same system as the application server, the install_client target will help you quickly redeploy a client. This target copies the necessary client classes to the install_dir/ias/rmi-client/ directory. If, as a convention, you run your RMI/IIOP clients from this directory, you can use the install_client target to quickly deploy a client after you've updated either the client or the EJB interfaces.

Refer to the J2EE Developer's Guide samples for examples of the install_client target. These examples can be found under the install_dir/ias/ias-samples/j2eeguide/ directory.

Build Examples

• Web-based Applications
• RMI/IIOP Applications

Web-based Applications

Since these samples do not include RMI/IIOP client setup instructions, the build steps are very straightforward.

Build Everything (including Javadocs), Install Javadocs and Deploy Application

build all

build install

Build Everything (except for Javadocs), Deploy Application (most frequently used approach)

build core or simply build

build install_ear

Rebuild EAR After Modifying Deployment Descriptors (no recompile, no ejbc)

build ear

build install_ear

Rerun EJB Compiler Without Recompiling EJBs

build stubs

Here's an example of the series of build commands for the Converter sample. The Converter EJB may be accessed by either an RMI/IIOP client or a servlet client.

build core

build install_ear (or "build install" to include Javadoc and client classes installation)

build install_client (or skip this step if you performed a "build install")

Copyright(c) 2001 Sun Microsystems, Inc. All rights reserved.