3 Preparing Applications and Modules for Deployment

This chapter describes how to prepare applications and modules for deployment to WebLogic Server.

This chapter includes the following sections:

Packaging Files for Deployment

WebLogic Server supports deployments that are packaged either as archive files using the jar utility or Ant's jar tool, or as exploded archive directories.

Note:

In general, using archived files is more efficient when deploying applications to Managed Servers. However, it makes updating the application, such as updating Web content, more difficult as it requires a redeployment of the application.

Using Archived Files

An archive file is a single file that contains all of an application's or module's classes, static files, directories, and deployment descriptor files. In most production environments, the applications an administrator receives for deployment are stored as archive files.

Deployment units that are packaged using the jar utility have a specific file extension depending on the type:

  • EJBs and client archives are packaged as .jar files.

  • Web applications are packaged as .war files.

  • Resource adapters are packaged as .rar files.

  • Enterprise applications are packaged as .ear files, and can contain other Java EE modules such as Web archives (.war files), EJB archives (.jar files), connector archives (.rar files) and client archives (.jar files).

  • Web services can be packaged either as .war files or as .jar files, depending on whether they are implemented using Java classes or EJBs. Typically, the .war or .jar files are then packaged in an enterprise application .ear file.

  • Java EE libraries are packaged either as an enterprise application (.ear file) or as a standard Java EE module.

  • Client applications and optional packages are packaged as .jar files.

In addition to an archive file, you may also receive a deployment plan, which is a separate file that configures the application for a specific environment. Configuring Applications for Production Deployment describes deployment plans in more detail.

Using Exploded Archive Directories

An exploded archive directory contains the same files and directories as a JAR archive. If you choose to use an exploded archive directory, you may be required to manually unpack a previously-archived deployment. However, the files and directories reside directly in your file system and are not packaged into a single archive file with the jar utility.

You may choose to deploy from an exploded archive directory under the following circumstances:

  • You want to perform partial updates of an enterprise application after deployment. Deploying enterprise applications as an exploded archive directory makes it easier to update individual modules of the application without having to re-create the archive file.

  • You are deploying a Web application or enterprise application that contains static files that you will periodically update. In this case, it is more convenient to deploy the application as an exploded directory, because you can update and refresh the static files without re-creating the archive.

  • You are deploying a Web application that performs direct file system I/O through the application context (for example, a Web application that tries to dynamically edit or update parts of the Web application itself). In this case, the modules that perform the I/O operations should have a physical file system directory in which to work; you cannot obtain a file when the application is deployed as an archive, as per the specification.

Java EE Rules for Deploying Exploded EAR Directories without Deployment Descriptors

The Java EE specification recommends that archived EARs (Enterprise Application Archives) can be deployed to a Java EE-compliant server without any deployment descriptors. To achieve this, all containers assume reasonable defaults or use annotated classes. In addition to supporting this mandate, WebLogic Server also allows deploying exploded EAR directories without deployment descriptors.

Since this applies to directories, certain rules are used to identify EARs and their nested modules. Otherwise, the WebLogic Server Administration Console or deployment tools will not treat the directories as valid exploded Java EE directories.

  • For an exploded archived Web application, in the absence of WEB-INF/web.xml descriptor, the name of the directory should have a .war suffix.

  • For an exploded archived enterprise application without a META-INF/application.xml descriptor, the directory should have an .ear suffix. Within the application, the directory of exploded Web module should have a .war suffix. Similarly, the exploded EJB module should have a .jar suffix and the exploded RAR module should have a .rar suffix.

  • If an exploded enterprise application contains no META-INF/application.xml descriptor, the order in which modules are deployed is undefined and is dependent on the underlying File.listFiles() method order. To ensure a specific order in which modules are deployed, you must add an application.xml descriptor and list the modules in the desired order.

Creating an Exploded Archive Directory from an Archive File

If you have an archive file that you want to deploy as an exploded archive directory, use the jar utility to unpack the archive file in a dedicated directory. For example:

   mkdir /myapp
   cd /myapp
   jar xvf /dist/myapp.ear

If you are unpacking an archive file that contains other module archive files (for example, an enterprise application or Web Service that includes JAR or WAR files) and you want to perform partial updates of those modules, you must expand the embedded archive files as well. Make sure that you unpack each module into a subdirectory having the same name as the archive file. For example, unpack a module named myejb.jar into a /myejb.jar subdirectory of the exploded enterprise application directory.

Note:

If you want to use different subdirectory names for the archived modules in an exploded EAR file, you must modify any references to those modules in the application itself. For example, you must update the URI values specified in application.xml and CLASSPATH entries in the manifest.mf file.

Understanding Default Deployment Names

When you first deploy an application or standalone module to one or more WebLogic Server instances, you specify a deployment name to describe collectively the deployment files, target servers, and other configuration options you selected. You can later redeploy or stop the deployment unit on all target servers by simply using the deployment name. The deployment name saves you the trouble of re-identifying the deployment files and target servers when you want to work with the deployment unit across servers in a domain.

If you do not specify a deployment name at deployment time, the deployment tool selects a default name based on the deployment source file(s). For archive files, weblogic.Deployer uses the name of the archive file without the file extension. For example, the file myear.ear has a default deployment name of myear. For an exploded archive directory, weblogic.Deployer uses the name of the top-level directory you deploy. Auto-deployed applications and standalone modules get a computed name exactly as described for other applications; they will neither have the file extension nor be pre-pended with a string that starts with an underscore.

For Java EE libraries and optional packages, weblogic.Deployer uses the name specified in the library's manifest file. If no name was specified in the library's manifest file, you can specify one with the -name option.

As of WebLogic Server 12.1.1, in compliance with Java EE 6 specifications, there is an additional way of specifying an application name, the <application-name> element in application.xml. For standalone modules, you can specify the <module-name> element in the respective deployment descriptor. Application names provided in deployment descriptors (application-name in application.xml or module-name in web.xml) may also be overridden by the weblogic.Deployer -name option or by the manifest application name attribute.

The naming precedence is as follows, starting with the highest precedence:

  • The -name weblogic.Deployer option.

  • The name specified in the manifest file.

  • The name specified in the deployment descriptor.

  • A computed name based on the deployment source file.

If a provided or computed application or module name is already in use, now WebLogic Server will modify the name to make it unique by adding a numerical suffix.

See the following section, Understanding Application Naming Requirements for information on application naming requirements; See Deploying Applications and Modules with weblogic.Deployer to specify a non-default deployment name.

Understanding Application Naming Requirements

In order to successfully deploy an application to WebLogic Server, the application name must be valid. Application naming requirements are as follows:

  • Application names must only contain the following characters:

    • a-z

    • A-Z

    • 0-9

    • _ (underscore)

    • - (hyphen)

    • . (period)

    No additional characters are allowed in application names.

  • Application names that contain the "." character must contain at least one additional different character; "." and ".." are not valid application names.

  • Application names must be less than 215 characters in length.

Understanding Deployment Version Strings

In addition to a deployment name, an application or module can also have an associated version string. The version string distinguishes the initial deployment of the application from subsequent redeployed versions. For example, you may want to later update the application to fix problems or add new features. In production systems, it is critical to maintain a version string for both the initial and subsequent deployments of an application. Doing so allows you to update and redeploy an application version without interrupting service to existing clients. See Redeploying Applications in a Production Environment for more information.

The version string is specified in the manifest file for the application, and should be provided by your development team along with the other deployment files. "Assigning Application Versions" in Developing Applications for Oracle WebLogic Server describes the conventions for specifying the version string.

Creating an Application Installation Directory

The application installation directory separates generated configuration files from the core application files, so that configuration files can be easily changed or replaced without disturbing the application itself. The directory structure also helps you to organize and maintain multiple versions of the same application deployment files.

The following figure shows the application installation directory hierarchy for storing a single version of a deployable application or module.

Figure 3-1 Application Installation Directory

Description of Figure 3-1 follows
Description of "Figure 3-1 Application Installation Directory"

Oracle recommends copying all new production deployments into an application installation directory before deploying to a WebLogic Server domain. Deploying from this directory structure helps you easily identify all of the files associated with a deployment unit—you simply deploy the installation root using the Administration Console, and the Console automatically locates associated files such as deployment plans and WebLogic Server deployment descriptors that were generated during configuration.

Steps for Creating an Application Installation Directory

To create an application installation directory:

  1. Choose a top-level directory where you want to store deployment files for applications and modules on your system. Follow these best practices:

    • Do not store deployment files within a WebLogic Server domain directory.

    • Use source control if available to maintain deployment source files.

    • If possible, store deployment files in a directory that is accessible by the Administration Server and Managed Servers in your domain.

    The instructions that follow use the sample deployment directory, c:\deployments\production.

  2. Create a dedicated subdirectory for the application or module you want to deploy:

    mkdir c:\deployments\production\myApplication
    
  3. Create a subdirectory beneath the application directory to designate the version of the application you are deploying. Name the subdirectory using the exact version string of the application. For example:

    mkdir c:\deployments\production\myApplication\91Beta
    
  4. The version subdirectory will become the installation root directory from which you deploy the directory. Create subdirectories named app and plan under the version subdirectory:

    mkdir c:\deployments\production\myApplication\91Beta\app
    mkdir c:\deployments\production\myApplication\91Beta\plan
    

    Note:

    If you have more than one deployment plan associated with the application, create one \plan subdirectory for each plan. For example, if you have two deployment plans associated with the 91Beta version of the application myApplication, you would create two \plan subdirectories. For instance:

    • mkdir c:\deployments\production\myApplication\91Beta\plan1

    • mkdir c:\deployments\production\myApplication\91Beta\plan2

  5. Copy your application source deployment files into the \app subdirectory. If you are deploying from an archive file, simply copy the archive file, as in:

    cp c:\downloads\myApplication.ear c:\deployments\production\myApplication\91Beta\app
    

    If you are deploying from an exploded archive directory, copy the complete exploded archive directory into \app:

    cp -r c:\downloads\myApplication c:\deployments\production\myApplication\91Beta\app
    

    This results in the new directory, c:\deployments\production\myApplication\91Beta\app\myApplication.

  6. If you have one or more deployment plans for the application, copy them into the \plan subdirectories.

    If you have one deployment plan for the application:

    cp c:\downloads\myApplicationPlans\plan.xml c:\deployments\production\myApplication\91Beta\plan
    

    If you have two deployment plans for the application:

    cp c:\downloads\myApplicationPlans\plan1.xml c:\deployments\production\myApplication\91Beta\plan1
    cp c:\downloads\myApplicationPlans\plan2.xml c:\deployments\production\myApplication\91Beta\plan2
    

    Note:

    If you do not have an existing deployment plan, you can create one using the Administration Console as described in Configuring Applications for Production Deployment. The Administration Console automatically stores newly-generated deployment plans in the \plan subdirectory of the application installation directory.

  7. To install the application using Administration Console, select the application installation directory. By default, the Administration Console will use a plan named plan.xml, if one is available in the \plan subdirectory. The Administration Console does not identify plans in subdirectories other than the \plan subdirectory; in other words, plans in \plan1 or \plan2 subdirectories are not identified by the Administration Console. Therefore, if multiple plans for your application are available, you must indicate, in config.xml, the plan you would like to use. See Configuring Applications for Production Deployment. For information on config.xml, see Creating WebLogic Domains Using the Configuration Wizard.

    After installing the application, you can configure, deploy, or distribute the application as necessary.

    Note:

    You cannot specify an application installation directory when using the weblogic.Deployer tool, and the tool does not use an available plan.xml file by default. You must specify the actual deployment file(s) and plan to use for deployment. See Deploying Applications and Modules with weblogic.Deployer.

Using FastSwap Deployment to Minimize Redeployment

Today's Web application developers expect to make changes to a deployed application and see those changes immediately by refreshing the browser. On the Java EE side, developers typically have to go through the following cycle to see their changes in action.

Edit -> Build -> Deploy -> Test

These steps, along with the many required descriptor elements, makes developing applications with Java EE seem complex and top-heavy. Among these steps, the build and deploy cycles are necessitated by Java and by the application server being employed. IDEs are trying to make the edit and build steps seamless by providing incremental compilation support. On the server side, the WebLogic Server FastSwap deployment feature makes the deploy and test cycles just as seamless.

How FastSwap Deployment Works

Java EE 5 introduced the ability to redefine a class at run time without dropping its classloader or abandoning existing instances. This allowed containers to reload altered classes without disturbing running applications, vastly speeding up iterative development cycles and improving the overall development and testing experiences. The usefulness of the Java EE dynamic class redefinition is severely curtailed, however, by the restriction that the shape of the class – its declared fields and methods – cannot change. The purpose of FastSwap is to remove this restriction in WebLogic Server, allowing the dynamic redefinition of classes with new shapes to facilitate iterative development.

With FastSwap, Java classes are redefined in-place without reloading the classloader, thereby having the decided advantage of fast turnaround times. This means that you do not have to wait for an application to redeploy and then navigate back to wherever you were in the Web page flow. Instead, you can make your changes, auto compile, and then see the effects immediately.

Supported FastSwap Application Configurations

The following application configurations are supported when using FastSwap deployment:

  • FastSwap is only supported when WebLogic Server is running in development mode. It is automatically disabled in production mode.

  • Only changes to class files in exploded directories are supported. Modifications to class files in archived applications, as well as archived JAR files appearing in the application's classpath are not supported. Examples are as follows:

    • When a Web application is deployed as an archived WAR within an EAR, modifications to any of the classes are not picked up by the FastSwap agent.

    • Within an exploded Web application, modifications to Java classes are only supported in the WEB-INF/classes directory; the FastSwap agent does not pick up changes to archived JARs residing in WEB-INF/lib.

Enabling FastSwap In Your Application

To enable FastSwap in your application, add the following element to the weblogic-application.xml file.

 <fast-swap>
    <enabled>true</enabled>
 </fast-swap>

For more information on the weblogic-application.xml elements, see "Enterprise Application Deployment Descriptor Elements" in Developing Applications for Oracle WebLogic Server.

FastSwap can also be enabled for a standalone Web application by adding the <fast-swap> element to the weblogic.xml file. For more information on the weblogic.xml elements, see "weblogic.xml Deployment Descriptor Elements" in Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server.

Overview of the FastSwap Process

The following steps describe how the FastSwap deployment process works:

  1. Once FastSwap is enabled at the descriptor level, an appropriate classloader is instantiated when the application is deployed to WebLogic Server.

  2. Open a browser to see the application at work. Modify (add/edit/delete) the methods and/or classes (see Limitations When Using FastSwap) and then compile them.

    It is recommended that you use an IDE such as Eclipse or IntelliJ and setting the compile-on-save option so that Java files are compiled on saving. Also note that the FastSwap agent does not compile Java files.

  3. Refresh the browser or send a new request to the application.

    The FastSwap agent tries to find all classes that have been modified since the last iteration by looking at all directories in the classpath. Considering an exploded application with a single Web application, the following directories are examined for any class file modifications based on their timestamps:

    ExampleApp/APP-INF/classes
    ExampleApp/webapp/WEB-INF/classes
    

    The FastSwap agent redefines the modified classes in the application and then serves the request.

Using Ant with the JMX Interface

For headless applications (that is, applications not fronted by a Web application), class redefinition can be explicitly initiated using the JMX interface. An Ant task that uses the JMX interface can be used to initiate class redefinition, as shown in following Ant FastSwapTask example.

Example 3-1 Using Ant with the JMX Interface

<project name='MyProject' default='all' >
  <taskdef name='fast-swap'  classname='com.bea.wls.redef.ant.FastSwapTask'/>
  <target name='all'>
    <!--
      Redefine classes which have changed since they were last loaded.
      Required parameters:
       adminUrl: Connection url
           user: User name
       password: User password
         server: Managed server name
      application: Deployed application name
      Optional parameters:
          module: Name of the module within the application.
                  If not specified, all modules within the application
                  will be processed.
       failonerror: Default=true. If true, task will fail if fast-swap failed.
                  Otherwise, a message will be displayed and the task will
                    return success.
         timeout: Default=300. Timeout in seconds.
      classnames: Comma separated list of classnames to process. If not
                  specified, all classes within specified modules (if any)
                    in the application will be considered.
    -->
    <fast-swap
      adminUrl='t3://localhost:7001'
      user='weblogic'
      password='weblogic'
      server='myserver'
       application='SimpleApp'
      module='SimpleAppCookie'
      failonerror='false'
      timeout='30'
      classnames='examples.servlets.CookieCounter1,
                  examples.servlets.CookieCounter2,
                    examples.servlets.CookieCounter'
    />
  </target>
</project>

Application Types and Changes Supported with FastSwap

FastSwap is supported with POJOs (JARs), Web applications (WARs) and enterprise applications (EARs) deployed in an exploded format. FastSwap is not supported with resource adapters (RARs).

The following types of changes are supported with FastSwap:

  • Addition of static methods

  • Removal of static methods

  • Addition of instance methods

  • Removal of instance methods

  • Changes to static method bodies

  • Changes to instance method bodies

  • Addition of static fields

  • Removal of static fields

  • Addition of instance fields

  • Removal of instance fields

The following table lists detailed change types supported with FastSwap:

Table 3-1 Supported Application Types and Changes

Scope Java Change Type Supported Notes

Java Class

Add method

Yes

Addition of the finalize method is not supported.

Instance (non-abstract)

Remove method

Yes

Addition of the finalize method is not supported.

 

a) Add field

Yes

 
 

b) Remove field

Yes

 
 

c) Change method body

Yes

 
 

d) Add constructor

Yes

 
 

e) Remove constructor

Yes

 
 

f) Change field modifiers

Yes

 
 

g) Change method modifiers

Yes

 

Class-level (static)

Add method

Yes

 
 

Remove method

Yes

 
 

Change body method

Yes

 

Class Hierarchy Changes

Change list of implemented interfaces

No

 
 

Change extends "SuperClass"

No

 

Abstract Java Class

Add abstract method

Yes

 
 

Delete abstract method

Yes

 
 

All other supported changes (a–g) listed in Instance

Yes

 

"final" Java Class

Same supported changes (a–g) listed in Instance

Yes

 

"final" Java Method

Same supported changes (a–g) listed in Instance

Yes

 

"final" Java Field

Same supported changes (a–g) listed in Instance

Yes

 

Enum

Add constants

No

 
 

Remove constants

No

 
 

Add/remove methods

No

 

Anonymous Inner Class

Add/remove fields

NA

Not supported by the Java language

Add/remove methods

No

 

Static Inner Class

Same supported changes (a–g) listed in Instance

Yes

 

Member Inner Classes (non-static inner classes)

Same supported changes (a–g) listed in Instance

Yes

 

Local Inner Classes

Same supported changes (a–g) listed in Instance

Yes

 

Java Interface

Add method

Yes

 

Java Reflection

Access existing fields/methods

Yes

 
 

Access new methods

No

New methods are not seen using Reflection and some synthetic methods are exposed.

 

Access new fields

No

New fields are not seen using Reflection.

Annotations on Classes

Add or remove method/field annotations

No

 

Annotation Type

Add or remove methods/attributes

No

 

Exception Classes

Same supported changes (a–g) listed in Instance

Yes

 

EJB Interface

Add/remove methods

No

Changes to EJB interfaces involve Reflection, which is not fully supported.

EJB 3.0 Session/MDB

EJB Implementation Class

Add/remove methods

No

Any support classes referenced by the EJB classes can be modified.

Add/remove fields

No

 

EJB 3.0 EntityBean

Add/remove methods

No

Any support classes referenced by the EJB classes can be modified.

 

Add/remove fields

No

 

EJB Interceptors

Add/remove methods

No

Any support classes referenced by the EJB classes can be modified.

 

Add/remove fields

No

 

Limitations When Using FastSwap

The following limitations apply when using FastSwap deployment:

  • Java reflection results do not include newly added fields and methods and include removed fields and methods. As a result, use of the reflection API on the modified classes can result in undesired behavior.

  • Changing the hierarchy of an already existing class is not supported by FastSwap. For example, either a) changing the list of implemented interfaces of a class; or b) changing the superclass of a class, is not supported.

  • Addition or removal of Java annotations is not supported by FastSwap, since this is tied to the reflection changes mentioned above.

  • Addition or removal of methods on EJB Interfaces is not supported by FastSwap since an EJB Compilation step is required to reflect the changes at run time.

  • Addition or removal of constants from Enums is not supported.

  • Addition or removal of the finalize method is not supported.

  • When you change a field name, the object state is not retained. This type of change occurs as follows: the field with the old name is deleted and a field with the new name is added. As such, any state in the old field is not carried over to the renamed field. You should expect an instance value to be reset when you change a field name.

Handling Unsupported FastSwap Changes

When FastSwap is enabled, after you recompile a class, FastSwap attempts to redefine classes in existing classloaders. If redefinition fails because your changes fall outside the scope of supported FastSwap changes, the JVM throws an UnsupportedOperationException in the WebLogic Server window and in the server log file. Your application will not reflect the changes, but will continue to run.

To implement your changes, you can redeploy the application or affected modules (partial redeploy), depending on the application type and the extent of your changes.

Best Practices for Preparing Deployment Files

The following best practices are recommended when preparing applications and modules for deployment:

  • Regardless of whether you deploy an archive file or exploded archive directory, store the deployment files in an installation directory for the application, as described in Creating an Application Installation Directory. Using an installation directory simplifies the deployment process, because the Administration Console understands where to locate deployment and configuration files.

  • Manage the entire application installation directory in a source control system, so you can easily revert to previous application versions if necessary.