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.

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 optional for applications whose metadata can be supplied by annotations or defaults. For wlcompile, a Web module is recognized by its WEB-INF directory or by Web-archive recognition, including a .war directory suffix. An EJB module is recognized from its EJB descriptor or annotated Java sources; a .jar directory suffix also identifies an EJB module. Use a .war or .jar suffix when the directory’s contents do not otherwise identify its module type. These suffixes identify exploded module directories; they do not turn utility-source directories into deployable modules.

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

First, wlcompile compiles shared Java utility sources into APP-INF/classes under the build directory selected by destdir. In the preceding task fragment, that output is ${dest.dir}/APP-INF/classes. The helloWorldEar sample defines dest.dir from its examples build settings; it is not a fixed installation path. For the installed sample’s locations and configuration, see Sample Applications and Code Examples in Understanding Oracle WebLogic Server. Sample Applications and Code Examples
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.

Using includes and excludes Properties

Use the includes and excludes attributes to select which immediate subdirectories of the enterprise application source root participate in a wlcompile invocation. Values are Ant include/exclude patterns relative to srcdir. These attributes select directories; they do not establish an arbitrary dependency order. For dependencies that need separate compilation stages, invoke wlcompile separately with the appropriate directory selections in the required order.

The following line from the helloWorldEar sample excludes the appStartup utility-source directory from this compilation invocation:

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

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`	Appends entries to the compilation classpath initialized from the Ant process/task environment; does not replace that existing classpath.
`includes`	Ant patterns selecting immediate source-root directories to compile.
`excludes`	Ant patterns excluding immediate source-root directories from this invocation.
`librarydir`	Specifies a directory of shared Java EE libraries to add to the classpath. See 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

Run the WebLogic split-directory Ant tasks after setting the WebLogic environment as described in Chapter 4. The tasks require the matching WebLogic distribution classes; wlcompile adds the module and shared-class paths described above. For application code that uses WebLogic public APIs, the distribution provides WL_HOME/server/lib/wls-api.jar, where WL_HOME is the WebLogic Server installation directory. Add any third-party libraries and other application classes required by your source. Applications using only standard Jakarta EE APIs can instead use the corresponding standard API dependencies, as described in Chapter 3 and the Chapter 4 compilation guidance. Do not add a JDK lib/tools.jar: that file was removed with the modular JDK layout. For installed samples, load examples.properties through the sample build script’s property task; do not add the properties file itself to the compiler classpath. Follow the installed sample’s instructions for its locations and build properties.

Related build workflows:

Using the WebLogic Maven Plug-In

;

Creating a Split Development Directory Environment

Library Element for wlcompile and wlappc

Use an optional nested library element in wlcompile or wlappc to supply an individual shared-library file to the build tool. The file attribute is required. The optional name, specificationversion and implementationversion attributes identify the supplied library’s registration metadata; they do not themselves declare an application dependency or a minimum required version. Declare application library references in the appropriate deployment descriptor, or optional-package references in the manifest, as described in Creating Shared Jakarta EE Libraries and Optional Packages.

Table 5-2 Library attributes

Attribute	Description
`file`	Path to the supplied library archive or exploded library directory; required and must exist.
`name`	Optional registration name of the supplied library.
`specificationversion`	Optional specification version of the supplied library.
`implementationversion`	Optional implementation version of the supplied library.

The format choices for both specificationversion and implementationversion are described in Referencing Shared Jakarta EE Libraries in an Enterprise Application. The following configuration fragment supplies a library file with registration metadata; use values appropriate to that library:

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

Building Modules and Applications Using wlappc

Use weblogic.appc, or the wlappc Ant task, to precompile JSPs, generate required EJB support classes and perform deployment-descriptor and cross-module validation. The input can be a supported application/module archive or exploded directory. These build-time checks do not establish every aspect of Jakarta EE application compliance or replace deployment and runtime testing.

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 sections describe the wlappc options and usage. For an EAR with application.xml, appc processes its standard modules in descriptor order. For a descriptor-free EAR, module discovery supplies the application descriptor model used by the compiler. This ordering statement concerns appc; wlcompile uses the utility/EJB/Web compilation order described earlier.

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
version <level>	Sets the Java source and target levels passed for generated Java compilation, for example version="21". This is not the WebLogic product version. Use levels supported by the selected compiler and deployment runtime.
`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.
`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 <signature>	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 <name>	Selects the Java compiler mode. Accepted values are javac, jdt and none. The default generated-EJB compiler mode is 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`	Legacy compiler pass-through switch retained by the parser. It does not select a compiler; current appc compiler values are javac, jdt and none.
`runtimeflags`	Compiler-runtime pass-through arguments, where supported by the selected external Java compiler. This value is passed to appc’s compiler argument parser; it does not configure the JVM running Ant or appc.
`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.
source <path>	Required path to the application/module archive or exploded directory to process.
plan <file>	Optional deployment-plan XML file applied during compilation.
continueCompilation	Boolean; when true, continues JSP compilation after individual JSP errors. Default: false.

To configure Ant’s JVM heap, use ANT_OPTS as described in Changing the Ant Heap Size. For the appc JVM launched directly with java, put JVM options before the weblogic.appc class name. Changing the Ant Heap Size

Command-line help, product-version output and inferred-descriptor writing are not exposed by these Ant attributes. Use the command-line options described in weblogic.appc Reference for those operations.

wlappc Ant Task Syntax

Set the required source attribute to the application or module archive/directory to process. In a split-directory build, ${dest.dir} is the build tree produced by wlcompile. If output is omitted, appc writes its output back to the input archive or directory.

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

The following task enables IDL generation and permits existing IDL output to be overwritten:

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

Syntax Differences between appc and wlappc

The command-line tool uses standalone switches for Boolean options, such as -idl. Ant expresses the corresponding option as an XML attribute with an explicit Boolean value, such as idl="true". Options that take paths or other values use -option value on the command line and option="value" in Ant. The following examples select the same existing input archive, foo.ear:

java weblogic.appc -idl foo.ear

<wlappc source="foo.ear" idl="true"/>

weblogic.appc Reference

The following sections describe how to use the command-line version of the appc compiler. The command-line compiler reports descriptor warnings and errors and compiles the relevant modules. It preserves the input archive/directory as its output by default; use -output to select another output archive or directory. Processing a standalone module does not automatically wrap it in an EAR.

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

Table 5-4 lists selected appc options. Use -help for standard usage and -advanced for the extended option list available in this release.

Table 5-4 weblogic.appc Options

Option	Description
-help	Prints standard usage information.
`-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`	Writes deployment descriptors containing metadata inferred from annotations into the compilation output. To keep the input archive separate from that output, specify -output.
`-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 <signature>	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 <name>	Selects the Java compiler mode. Accepted values are javac, jdt and none. The default generated-EJB compiler mode is jdt.
`-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`	Legacy compiler pass-through switch retained by the parser. It does not select a compiler; current appc compiler values are javac, jdt and none.
`-J<option>`	Passes an option to the runtime of an externally invoked Java compiler. The inline compiler path ignores -J options. This does not configure the JVM running weblogic.appc.
`-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.

java weblogic.appc -writeInferredDescriptors -output application-inferred.ear application.ear

For an existing application.ear, write inferred descriptors into a separate output archive:

java weblogic.appc -help
java weblogic.appc -advanced

The following commands display usage without compiling an application: