4 Building Applications in a Split Development Directory

The following sections describe the steps for building WebLogic Server Java EE applications using the WebLogic split development directory environment:

Compiling Applications Using wlcompile

You use the wlcompile Ant task to invoke the javac compiler to compile your application's Java components in a split development directory structure. The basic syntax of wlcompile identifies the source and build directories, as in this command from the helloWorldEar sample:

<wlcompile srcdir="${src.dir}" destdir="${dest.dir}"/>

Note:

Deployment descriptors are no longer mandatory in JEE 5; therefore, exploded module directories must indicate the module type by using the .war or .jar suffix when there is no deployment descriptor in these directories. The suffix is required so that wlcompile can recognize the modules. The .war suffix indicates the module is a Web application module and the .jar suffix indicates the module is an EJB module.

The following is the order in which events occur using this task:

  1. wlcompile compiles the Java components into an output directory:

    WL_HOME\samples\server\examples\build\helloWorldEar\APP-INF\classes\
    

    where WL_HOME is the WebLogic Server installation directory.

  2. wlcompile builds the EJBs and automatically includes the previously built Java modules in the compiler's classpath. This allows the EJBs to call the Java modules without requiring you to manually edit their classpath.

  3. Finally, wlcompile compiles the Java components in the Web application with the EJB and Java modules in the compiler's classpath. This allows the Web applications to refer to the EJB and application Java classes without requiring you to manually edit the classpath.

Using includes and excludes Properties

More complex Enterprise applications may have compilation dependencies that are not automatically handled by the wlcompile task. However, you can use the include and exclude options to wlcompile to enforce your own dependencies. The includes and excludes properties accept the names of Enterprise application modules—the names of subdirectories in the Enterprise application source directory—to include or exclude them from the compile stage.

The following line from the helloWorldEar sample shows the appStartup module being excluded from compilation:

<wlcompile srcdir="${src.dir}" destdir="${dest.dir}"
   excludes="appStartup"/>

wlcompile Ant Task Attributes

Table 4-1 contains Ant task attributes specific to wlcompile.

Table 4-1 wlcompile Ant Task Attributes

Attribute Description
srcdir

The source directory.

destdir

The build/output directory.

classpath

Allows you to change the classpath used by wlcompile.

includes

Allows you to include specific directories from the build.

excludes

Allows you to exclude specific directories from the build.

librarydir

Specifies a directory of shared Java EE libraries to add to the classpath. See Chapter 9, "Creating Shared Java EE Libraries and Optional Packages."


Nested javac Options

The wlcompile Ant task can accept nested javac options to change the compile-time behavior. For example, the following wlcompile command ignores deprecation warnings and enables debugging:

<wlcompile srcdir="${mysrcdir}" destdir="${mybuilddir}">
   <javac deprecation="false" debug="true"
   debuglevel="lines,vars,source"/>
</wlcompile>

Setting the Classpath for Compiling Code

Most WebLogic services are based on Java EE standards and are accessed through standard Java EE packages. The Sun, WebLogic, and other Java classes required to compile programs that use WebLogic services are packaged in the weblogic.jar file in the lib directory of your WebLogic Server installation. In addition to weblogic.jar, include the following in your compiler's CLASSPATH:

  • The lib\tools.jar file in the JDK directory, or other standard Java classes required by the Java Development Kit you use.

  • The examples.property file for Apache Ant (for examples environment). This file is discussed in the WebLogic Server documentation on building examples using Ant located at: samples\server\examples\src\examples\examples.html

  • Classes for third-party Java tools or services your programs import.

  • Other application classes referenced by the programs you are compiling.

Library Element for wlcompile and wlappc

The library element is an optional element used to define the name and optional version information for a module that represents a shared Java EE library required for building an application, as described in Chapter 9, "Creating Shared Java EE Libraries and Optional Packages." The library element can be used with both wlcompile and wlappc, described in Building Modules and Applications Using wlappc.

The name and version information are specified as attributes to the library element, described in Table 4-2.

Table 4-2 Library attributes

Attribute Description
file

Required filename of a Java EE library

name

The optional name of a required Java EE library.

specificationversion

An optional specification version required for the library.

implementationversion

An optional implementation version required for the library.


The format choices for both specificationversion and implementationversion are described in Referencing Shared Java EE Libraries in an Enterprise Application. The following output shows a sample library reference:

<library file="c:\mylibs\lib.jar" name="ReqLib" specificationversion="920" implementationversion="1.1" />

Building Modules and Applications Using wlappc

The weblogic.appc compiler generates JSPs and container-specific EJB classes for deployment, and validates deployment descriptors for compliance with the current Java EE specifications. appc performs validation checks between the application-level deployment descriptors and the individual modules in the application as well as validation checks across the modules.

Additionally, optional packages are supported as Java EE shared libraries in appc, whereby all manifests of an application and its modules are scanned to look for optional package references.

wlappc is the Ant task interface to the weblogic.appc compiler. The following section describe the wlappc options and usage. Both weblogic.appc and the wlappc Ant task compile modules in the order in which they appear in the application.xml deployment descriptor file that describes your Enterprise application.

wlappc Ant Task Attributes

Table 4-3 describes Ant task options specific to wlappc. These options are similar to the weblogic.appc command-line options, but with a few differences.

Notes:

See weblogic.appc Reference for a list of weblogic.appc options.

See also Library Element for wlcompile and wlappc.

Table 4-3 wlappc Ant Task Attributes

Option Description
print

Prints the standard usage message.

version

Prints appc version information.

output <file>

Specifies an alternate output archive or directory. If not set, the output is placed in the source archive or directory.

forceGeneration

Forces generation of EJB and JSP classes. Without this flag, the classes may not be regenerated (if determined to be unnecessary).

lineNumbers

Adds line numbers to generated class files to aid in debugging.

writeInferredDescriptors

Specifies that the application or module contains deployment descriptors with annotation information.

basicClientJar

Does not include deployment descriptors in client JARs generated for EJBs.

idl

Generates IDL for EJB remote interfaces.

idlOverwrite

Always overwrites existing IDL files.

idlVerbose

Displays verbose information for IDL generation.

idlNoValueTypes

Does not generate valuetypes and the methods/attributes that contain them.

idlNoAbstractInterfaces 

Does not generate abstract interfaces and methods/attributes that contain them.

idlFactories

Generates factory methods for valuetypes.

idlVisibroker

Generates IDL somewhat compatible with Visibroker 4.5 C++.

idlOrbix

Generates IDL somewhat compatible with Orbix 2000 2.0 C++.

idlDirectory <dir>

Specifies the directory where IDL files will be created (default: target directory or JAR)

idlMethodSignatures <>

Specifies the method signatures used to trigger IDL code generation.

iiop

Generates CORBA stubs for EJBs.

iiopDirectory <dir>

Specifies the directory where IIOP stub files will be written (default: target directory or JAR)

keepgenerated

Keeps the generated .java files.

librarydir

Specifies a directory of shared Java EE libraries to add to the classpath. See Chapter 9, "Creating Shared Java EE Libraries and Optional Packages."

compiler <java.jdt>

Selects the Java compiler to use. Defaults to JDT.

debug

Compiles debugging information into a class file.

optimize

Compiles with optimization on.

nowarn

Compiles without warnings.

verbose

Compiles with verbose output.

deprecation

Warns about deprecated calls.

normi

Passes flags through to Symantec's sj.

runtimeflags

Passes flags through to Java runtime

classpath <path>

Selects the classpath to use during compilation.

clientJarOutputDir <dir>

Specifies a directory to place generated client jar files. If not set, generated jar files are placed into the same directory location where the JVM is running.

advanced

Prints advanced usage options.


wlappc Ant Task Syntax

The basic syntax for using the wlappc Ant task determines the destination source directory location. This directory contains the files to be compiled by wlappc.

<wlappc source="${dest.dir}" />

The following is an example of a wlappc Ant task command that invokes two options (idl and idlOrverWrite) from Table 4-3.

<wlappc source="${dest.dir}"idl="true" idlOrverWrite="true" />

Syntax Differences between appc and wlappc

There are some syntax differences between appc and wlappc. For appc, the presence of a flag in the command is a boolean. For wlappc, the presence of a flag in the command means that the argument is required.

To illustrate, the following are examples of the same command, the first being an appc command and the second being a wlappc command:

java weblogic.appc -idl foo.ear
<wlappc source="${dest.dir} idl="true"/>

weblogic.appc Reference

The following sections describe how to use the command-line version of the appc compiler. The weblogic.appc command-line compiler reports any warnings or errors encountered in the descriptors and compiles all of the relevant modules into an EAR file, which can be deployed to WebLogic Server.

weblogic.appc Syntax

Use the following syntax to run appc:

prompt>java weblogic.appc [options] <ear, jar, or war file or directory>

weblogic.appc Options

The following are the available appc options:

Option Description
-print
Prints the standard usage message.
-version
Prints appc version information.
-output <file>
Specifies an alternate output archive or directory. If not set, the output is placed in the source archive or directory.
-forceGeneration
Forces generation of EJB and JSP classes. Without this flag, the classes may not be regenerated (if determined to be unnecessary).
-library <file[[@name=<string>][@libspecver=<version>][@libimplver=<version|string>]]>
A comma-separated list of shared Java EE libraries. Optional name and version string information must be specified in the format described in Referencing Shared Java EE Libraries in an Enterprise Application.
-writeInferredDescriptors
Specifies that the application or module contains deployment descriptors with annotation information.
-lineNumbers
Adds line numbers to generated class files to aid in debugging.
-basicClientJar
Does not include deployment descriptors in client JARs generated for EJBs.
-idl
Generates IDL for EJB remote interfaces.
-idlOverwrite
Always overwrites existing IDL files.
-idlVerbose
Displays verbose information for IDL generation.
-idlNoValueTypes
Does not generate valuetypes and the methods/attributes that contain them.
-idlNoAbstractInterfaces 
Does not generate abstract interfaces and methods/attributes that contain them.
-idlFactories
Generates factory methods for valuetypes.
-idlVisibroker
Generates IDL somewhat compatible with Visibroker 4.5 C++.
-idlOrbix
Generates IDL somewhat compatible with Orbix 2000 2.0 C++.
-idlDirectory <dir>
Specifies the directory where IDL files will be created (default: target directory or JAR)
-idlMethodSignatures <>
Specifies the method signatures used to trigger IDL code generation.
-iiop
Generates CORBA stubs for EJBs.
-iiopDirectory <dir>
Specifies the directory where IIOP stub files will be written (default: target directory or JAR)
-keepgenerated
Keeps the generated .java files.
-compiler <javac>
Selects the Java compiler to use.
-g
Compiles debugging information into a class file.
-O
Compiles with optimization on.
-nowarn
Compiles without warnings.
-verbose
Compiles with verbose output.
-deprecation
Warns about deprecated calls.
-normi
Passes flags through to Symantec's sj.
-J<option>
Passes flags through to Java runtime.
-classpath <path>
Selects the classpath to use during compilation.
-clientJarOutputDir <dir>
Specifies a directory to place generated client jar files. If not set, generated jar files are placed into the same directory location where the JVM is running.
-advanced
Prints advanced usage options.