Developing Applications for Production Redeployment

What is Production Redeployment?

Production redeployment enables an administrator to redeploy a new version of an application in a production environment without stopping the deployed application or otherwise interrupting the application's availability to clients.

Production redeployment works by deploying a new version of an updated application alongside an older version of the same application. WebLogic Server automatically manages client connections so that only new client requests are directed to the new version. Clients already connected to the application during the redeployment continue to use the older, retiring version of the application until they complete their work.

See Using Production Redeployment to Upgrade Applications for more information.

Supported and Unsupported Application Types

Production redeployment supports HTTP and RMI clients, and the inbound JMS/message-driven-bean case described in Additional Application Support. Your development and design team must ensure that applications using production redeployment are not accessed by an unsupported client. Additional Application Support

See Additional Application Support.

WebLogic Server does not detect when unsupported clients access the application, and does not preserve unsupported client connections during production redeployment.

Enterprise applications can contain any of the supported Jakarta EE module types. Enterprise applications can also include application-scoped JMS and JDBC modules.

If an enterprise application includes a JCA resource adapter module, the module:

Must implement the jakarta.resource.spi.ResourceAdapter lifecycle contract supported by this release.
Both versions must implement weblogic.connector.extensions.Suspendable and report supportsVersioning() as true; the new version must also report supportsInit() as true.
Both resource adapters must be modules of their EAR application, with enable-access-outside-app set to false.

WebLogic Server calls init(oldResourceAdapter, properties) on the new adapter before its start, then calls startVersioning(newResourceAdapter, properties) on the old adapter. The old adapter must notify the connector container through ExtendedBootstrapContext.complete() when it is safe to undeploy. Coordinate the adapter’s resource migration with these callbacks.

For a complete list of production redeployment requirements for resource adapters, see Production Redeployment in Developing Resource Adapters for Oracle WebLogic Server.

Additional Application Support

Additional production redeployment support is provided for enterprise applications that are accessed by inbound JMS messages from a global JMS destination, and that use one or more message-driven beans as consumers. For this type of application, WebLogic Server suspends message-driven beans in the older, retiring application version before deploying message-driven beans in the newer version. Production redeployment is not supported with JMS consumers that use the JMS API for global JMS destinations. If the message-driven beans need to receive all messages published from topics, including messages published while beans are suspended, use durable subscribers.

Programming Requirements and Conventions

WebLogic Server performs production redeployment by deploying two instances of an application simultaneously. You must observe certain programming conventions to ensure that multiple instances of the application can co-exist in a WebLogic Server domain.

The following sections describe each programming convention required for using production redeployment:

Applications Should Be Self-Contained

As a best practice, applications that use production redeployment should be self-contained in their use of resources. This means you should generally use application-scoped JMS and JDBC resources, rather than global resources, whenever possible for versioned applications.

If an application must use a global resource, you must ensure that the application supports safe, concurrent access by multiple instances of the application. This same restriction also applies if the application uses external (separately-deployed) applications, or uses an external property file. WebLogic Server does not prevent the use of global resources with versioned applications, but you must ensure that resources are accessed in a safe manner.

Looking up a global JNDI resource from within a versioned application results in a warning message. To disable this check, set the JNDI environment property weblogic.jndi.WLContext.ALLOW_GLOBAL_RESOURCE_LOOKUP to true when performing the JNDI lookup.

Similarly, looking up an external application results in a warning unless you set the JNDI environment property, weblogic.jndi.WLContext.ALLOW_EXTERNAL_APP_LOOKUP, to true.

WLContext exposes these Java constants for JNDI environment keys. In a Properties file or other string-key configuration, use the literal key. Set the selected property to the String value "true" only when the application meets the resource/version compatibility requirements; the default is false.

Table 7-1 JNDI Version-Lookup Environment Properties

Java constant	Literal environment key	Effect
WLContext.ALLOW_GLOBAL_RESOURCE_LOOKUP	weblogic.jndi.allowGlobalResourceLookup	Suppresses the versioning warning for the global JDBC/JMS resources checked by the naming service.
WLContext.ALLOW_EXTERNAL_APP_LOOKUP	weblogic.jndi.allowExternalAppLookup	Suppresses the external-application versioning warning when a lookup has no version association for the target application.
WLContext.RELAX_VERSION_LOOKUP	weblogic.jndi.relaxVersionLookup	When the requested application version cannot be found, permits fallback to the active version.

Suppressing a warning does not coordinate shared-resource access or make different versions compatible.

Versioned Applications Access the Current Version JNDI Tree by Default

WebLogic Server binds application-scoped resources, such as JMS and JDBC application modules, into a local JNDI tree available to the application. As with non-versioned applications, versioned applications can look up application-scoped resources directly from this local tree. Application-scoped JMS modules can be accessed via any supported JMS interfaces, such as the JMS API or a message-driven bean.

Application modules that are bound to the global JNDI tree should be accessed only from within the same application version. WebLogic Server performs version-aware JNDI lookups and bindings for global resources deployed in a versioned application. By default, an internal JNDI lookup of a global resource returns bindings for the same version of the application.

If the current version of the application cannot be found, you can use the JNDI environment property weblogic.jndi.WLContext.RELAX_VERSION_LOOKUP to return bindings from the currently active version of the application, rather than the same version.

Note:

Set weblogic.jndi.WLContext.RELAX_VERSION_LOOKUP to true only if you are certain that the newer and older version of the resource that you are looking up are compatible with one another.

Security Providers Must Be Compatible

Every authorization, role-mapping and credential-mapping provider configured in the application’s security realm must support application versioning through the weblogic.security.spi.VersionableApplicationProvider SSPI. The default WebLogic Server security providers for authorization, role mapping, and credential mapping support the application versioning SSPI.

Applications Must Specify a Version Identifier

In order to use production redeployment, both the current, deployed version of the application and the updated version of the application must specify unique version identifiers. See Assigning an Application Version.

Applications Can Access Name and Identifier

Versioned applications can programmatically obtain both an application name, which remains constant across different versions, and an application identifier, which changes to provide a unique label for different versions of the application. Use the application name for basic display or error messages that refer to the application's name irrespective of the deployed version. Use the application ID when the application must provide a unique identifier for the deployed version of the application. See Accessing Version Information for more information about the MBean attributes that provide the name and identifier.

Client Applications Use Same Version when Possible

As described in What is Production Redeployment?, WebLogic Server attempts to route a client application's requests to the same version of the application until all of the client's in-progress work has completed. However, if an application version is retired using a timeout period, or is undeployed, the client's request will be routed to the active version of the application. In other words, a client's association with a given version of an application is maintained only on a "best-effort basis."

This behavior can be problematic for client applications that recursively access other applications when processing requests. WebLogic Server attempts to dispatch requests to the same versions of the recursively-accessed applications, but cannot guarantee that an intermediate application version is not undeployed manually or after a timeout period. If you have a group of related applications with strict version requirements, Oracle recommends packaging all of the applications together to ensure version consistency during production redeployment.

Assigning an Application Version

Specify a unique version identifier in the application’s META-INF/MANIFEST.MF and update it for each application release. Production redeployment requires both the existing deployment and its replacement to be versioned, with different version identifiers, and to meet the supported-application and compatibility requirements. Use the production redeployment procedure and an appropriate retirement policy when introducing the new version.

For testing purposes, a deployer can also assign a version identifier to an application during deployment and redeployment. See Assigning a Version Identifier During Deployment and Redeployment in Deploying Applications to Oracle WebLogic Server.

Application Version Conventions

WebLogic Server obtains the application version from the value of the Weblogic-Application-Version property in the MANIFEST.MF file. The version string can be a maximum of 215 characters long, and must consist of valid characters as identified in Table 7-2.

The Deployer -appversion argument has a stricter limit in this release: it must contain fewer than 215 characters. Use at most 214 characters when the same version value must work through both paths.

Table 7-2 Application Version Character and Length Rules

Rule	Value
Allowed ASCII characters	A–Z, a–z, 0–9, period (.), underscore (_) and hyphen (-).
Disallowed complete version values	A single period (.) or two periods (..). These are whole-value restrictions, not a ban on periods inside other values.
Application version validator maximum	215 characters.
Deployer -appversion argument maximum	214 characters.

A production-redeployment version identifier must be nonempty. Underscore and hyphen are accepted individually, although meaningful release labels are easier to identify.

For example, the following manifest file content describes an application with version "v920.beta":

Manifest-Version: 1.0
Weblogic-Application-Version: v920.beta

Upgrading Applications to Use Production Redeployment

You can upgrade applications for deployment to WebLogic Server to use production redeployment.

An existing unversioned deployment cannot be converted into a versioned deployment by a side-by-side production redeployment. Establish the initial versioned deployment through a planned undeploy/deploy transition before using production redeployment for later versions; that initial transition does not provide the production-redeployment availability guarantee. For versioned deployments, AppDeploymentMBean.ApplicationName is the logical deployment name. AppDeploymentMBean.Name and ApplicationIdentifier identify the particular version. Use the attribute appropriate to the application’s need; see Accessing Version Information. Accessing Version Information

Accessing Version Information

Application code or management clients can use the following MBean attributes to read version information for display, logging or other uses.

AppDeploymentMBean provides the following read-only configuration attributes.

Table 7-3 Read-Only Version Attributes in AppDeploymentMBean

Attribute Name	Description
`ApplicationName`	Logical deployment name of the application, shared by its versions.
`VersionIdentifier`	Version identifier for this deployment; null for an unversioned application.
`ApplicationIdentifier`	Identifier for this particular application deployment/version; for an unversioned application it is the application name.

ApplicationRuntimeMBean provides the following read-only runtime attributes.

Table 7-4 Read-Only Version Attributes in ApplicationRuntimeMBean

Attribute Name	Description
`ApplicationName`	A String that represents the deployment name of the application
`ApplicationVersion`	A string that represents the version of the application.
`ActiveVersionState`	An int indicating this application version’s activation role. Values defined by weblogic.deploy.version.AppActiveVersionState are: INACTIVE (0)—not the currently active version; it may not yet be activated or may be retiring. ACTIVE_ADMIN (1)—the active version for administrative-channel requests. ACTIVE (2)—the active version for normal, non-administrative-channel requests. These values are distinct from application/module lifecycle states.AppActiveVersionState constants

7 Developing Applications for Production Redeployment