Building Applications in a Split Development Directory

5 Building Applications in a Split Development Directory

To build WebLogic Server Jakarta EE applications in WebLogic split development directory environment you have to compile applications using wlcompile and build modules and applications using wlappc.

This chapter includes the following sections:

Compiling Applications Using wlcompile
You can use the wlcompile Ant task to invoke the javac compiler to compile your application's Java components in a split development directory structure.
Building Modules and Applications Using wlappc
To reduce deployment time, use the weblogic.appc Java class (or its equivalent Ant task wlappc) to pre-compile a deployable archive file, (WAR, JAR, or EAR). Precompiling with weblogic.appc generates certain helper classes and performs validation checks to ensure your application is compliant with the current Jakarta EE specifications.

Compiling Applications Using wlcompile

You can 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 as of Java EE 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:

wlcompile compiles the Java components into an output directory:
```
ORACLE_HOMEwlserver\samples\server\examples\build\helloWorldEar\APP-INF\classes\
```
where ORACLE_HOME represents the directory in which the WebLogic Server code examples are configured. For more information about the WebLogic Server code examples, see Sample Applications and Code Examples in Understanding Oracle WebLogic Server.
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.
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.

Parent topic: Building Applications in a Split Development Directory

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"/>

Parent topic: Compiling Applications Using wlcompile

wlcompile Ant Task Attributes

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

Table 5-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 Creating Shared Java EE Libraries and Optional Packages.

Parent topic: Compiling Applications Using wlcompile

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>

Parent topic: Compiling Applications Using wlcompile

Setting the Classpath for Compiling Code

Most WebLogic services are based on Jakarta EE standards and are accessed through standard Jakarta EE packages. The WebLogic and other Java classes required to compile programs that use WebLogic services are packaged in the wls-api.jar file in the lib directory of your WebLogic Server installation. In addition to wls-api.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.

Parent topic: Compiling Applications Using wlcompile

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 Jakarta EE library required for building an application, as described in Creating Shared Jakarta 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 5-2.

Table 5-2 Library attributes

Attribute	Description
`file`	Required filename of a Jakarta EE library
`name`	The optional name of a required Jakarta 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 Jakarta 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" />

Parent topic: Compiling Applications Using wlcompile

Building Modules and Applications Using wlappc

To reduce deployment time, use the weblogic.appc Java class (or its equivalent Ant task wlappc) to pre-compile a deployable archive file, (WAR, JAR, or EAR). Precompiling with weblogic.appc generates certain helper classes and performs validation checks to ensure your application is compliant with the current Jakarta EE specifications.

The application-level checks include checks between the application-level deployment descriptors and the individual modules, as well as validation checks across the modules.

Additionally, optional packages are supported as Jakarta 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.

Parent topic: Building Applications in a Split Development Directory

wlappc Ant Task Attributes

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

Note:

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

Table 5-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 Jakarta EE libraries to add to the classpath. See Creating Shared Jakarta 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.

Parent topic: Building Modules and Applications Using wlappc

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 5-3.

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

Parent topic: Building Modules and Applications Using wlappc

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"/>

Parent topic: Building Modules and Applications Using wlappc

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.

Parent topic: Building Modules and Applications Using wlappc

weblogic.appc Syntax

Use the following syntax to run appc:

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

Parent topic: Building Modules and Applications Using wlappc

weblogic.appc Options

The following are the available appc options:

Table 5-4 weblogic.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.

Parent topic: Building Modules and Applications Using wlappc