5 Activating Applied Patches in Your Installations and Applications

Patches That Must Be Referenced By Start Scripts

If a patch contains class or library files that are loaded by a start script, those classes or files are stored, by Smart Update, in a central, installation-level patch directory on the system. These classes and library files are then available for loading when the WebLogic Server instances by which they are used are started.

Examples of patches in this category are those that contain the following:

• Class files that are loaded into the WebLogic Server system classpath

• Class files that are loaded into the classpath of an application that is deployed on WebLogic Server

• Library files that are loaded into the library path for WebLogic Server

  Note:

  Although a patch may be validated and applied to a target installation at any time, some patches do not become effective immediately. Any patch that contains either (a) classes to be loaded into a classpath, or (b) native library files to be loaded into a library path, does not become effective until you (a) modify the appropriate domain or server start scripts, if necessary, so they point to the patch and (b) restart the corresponding domains or servers.

Patches That Replace Resources For All Applications, Domains, and Servers

Patches that replace existing resources in a product installation become effective, automatically, throughout the installation, as soon as they are applied; they are not enabled by a start script. Therefore, you do not need to change start scripts for patches that contain replacements for system resources.

Examples of patches that typically contain replacement artifacts include the following:

• Resources for Web server plug-ins

• Socket multiplexers

• Dynamically linked libraries

  Note:

  Smart Update stores files that have been replaced in the backup subdirectory of the installation-level patch directory. If you subsequently remove the patch in which a replacement was delivered, the original resource is restored from backup. (For details about backup, see Table 5-1.) For optimal security, however, it is recommended that you create a backup of any system resource that you plan to replace before applying the patch that replaces it.

Patches That Must Be Deployed and Referenced By Applications

Shared archive patches must be explicitly deployed and referenced by applications that require them. If a Shared Archive patch is to be applied to selected applications and not all applications, you must create a custom patch profile for each unique patch level.

How Patch Files Are Stored on Your System By Smart Update

When you download a patch or patch set from My Oracle Support, a patch container is placed in the patch download directory. A patch container holds the following:

• A patch or patch set

  A patch may contain several files. These files may include:

  • Classes delivered as replacements for classes, with the same name, that are inserted into the WebLogic system classpath at server start time

  • Native library files to be inserted into the system path

  • Configuration files

  A patch set is a collection of two or more individual patches, each with its own set of files.

• Metadata about each patch in the patch container

  Metadata is information used by Smart Update to validate each patch against all other patches applied to the same product installation. (When you apply a patch, metadata is placed in a patch registry in a directory on your system that is maintained by Smart Update. For details, see Structure of the Installation-Level Patch Directories.)

When you apply a patch to a given patch profile, each file in the patch is handled as follows:

• If the patch contains a replacement for a system resource, such as a WebLogic Server plug-in module, the existing resource is automatically updated with the replacement.

• If the patch contains a patch JAR file, that is, a set of classes to be loaded into a classpath as updates for existing classes with the same names in the target installation, the following events occur:

  • The patch JAR file is placed in the installation-level patch directory. For a description of this directory, see Structure of the Installation-Level Patch Directories.

  • Smart Update creates a file, called the patch manifest JAR, which contains pointers to the classes in the patch JAR file. If a patch manifest JAR for the current profile exists, it is updated with pointers to the classes in the patch JAR file. The patch manifest JAR file is described in Patch Manifest JAR Files.

• If the patch contains native library files to be loaded into the system library path, through either the PATH or LIBPATH environment variable, Smart Update Verifies the existence of a subdirectory called native that is specific to the currently selected patch profile. If Smart Update does not find such a subdirectory, it creates one. For a description of the native subdirectory, see Open Start Script Dialog Box Icons.

Structure of the Installation-Level Patch Directories

After you install the products and run Smart Update, the patch directories are created. Each product (for example, WebLogic Server, Workshop for WebLogic, WebLogic Integration, and WebLogic Portal) has its own patch directory structure (for example, patch_wls1001, patch_wlw1020, patch_wli1020, and patch_wlp1020) under the middleware home directory.

The product-specific patch directory structure provides clean demarcation of patch maintenance on a product basis. It also provides more flexibility for future products to interoperate with separate or common versions of WebLogic Server.

Figure 5-1 shows the structure of the MW_HOME\patch_product directories.

Figure 5-1 Installation-Level Patch Directories

Description of "Figure 5-1 Installation-Level Patch Directories"

Table 5-1 describes the contents of each patch directory.

About Pointing Start Scripts at Patches

To ensure that a patch is loaded into a classpath or the system library path when a WebLogic Server instance is started, you might need to add a pointer to the patch to the start script for that server. The following sections explain how Smart Update works and describe the changes that you might need to make to your start scripts:

• Default Script that Defines Class and Library Paths for All Domains and Servers

• Default Patch Path Environment Variables

• How Patch Path Variables Are Inserted into Class and Library Paths

• About Setting a Patch Path Variable in a Server Start Script

WL_HOME\common\bin\commEnv.cmd

WL_HOME/common/bin/commEnv.sh

if "%PATCH_CLASSPATH%" == "" set PATCH_CLASSPATH=
%WLS_PATCH_CLASSPATH%;%WLW_PATCH_CLASSPATH%

if "%WEBLOGIC_EXTENSION_DIRS%" == "" 
set WEBLOGIC_EXTENSION_DIRS= %BEA_HOME%\
patch_wls1030\profiles\default\sysext_manifest_classpath

if [ "${PATCH_LIBPATH}" = "" ];
 then PATCH_LIBPATH=${BEA_HOME}
 /patch_wls1030/profiles/default/native

if "%PATCH_PATH%" == "" set PATCH_PATH=
%BEA_HOME%\patch_wls1030\profiles\default\native

How Patch Path Variables Are Inserted into Class and Library Paths

Within the commEnv script, the patch path variables described in Table 5-2 are inserted into statements that set the system classpath, library path, and so on, as appropriate. For example, the following default statement in the commEnv script sets the WebLogic system classpath. The variable PATCH_CLASSPATH, at the beginning of the classpath definition, is shown in bold.

set WEBLOGIC_CLASSPATH=%PATCH_CLASSPATH%;%JAVA_HOME%\lib\tools.jar;
%WL_HOME%\server\lib\weblogic_sp.jar;%WL_HOME%\server\lib\weblogic.jar;
%WL_HOME%\server\lib\webservices.jar

When the commEnv script is executed at server start time, the classes and library files referenced by these patch path variables are loaded, overriding any classes or library files of the same name that are listed later in the classpath or path statement.

Figure 5-2 shows a patch JAR file that contains classes referenced through the PATCH_CLASSPATH environment variable and loaded into the WebLogic system classpath by the commEnv script.

Figure 5-2 Patch JAR File Classes Referenced by PATCH_CLASSPATH Variable

Description of "Figure 5-2 Patch JAR File Classes Referenced by PATCH_CLASSPATH Variable"

startManagedWebLogic.cmd

startManagedWebLogic.sh

startWebLogic.cmd

startWebLogic.sh

setDomainEnv.cmd

setDomainEnv.sh

commEnv.cmd

commEnv.sh

. WL_HOME/common/bin/commEnv.sh

. ./commEnv.sh

Script Snippet for Windows

SET PATCH_CLASSPATH=%BEA_HOME%\patch_wls1001\profiles\myCustomProfile\sys_manifest_classpath\weblogic_patch.jar

SET WEBLOGIC_EXTENSION_DIRS=%BEA_HOME%\patch_wls1001\profiles\myCustomProfile\sysext_manifest_classpath

SET PATCH_LIBPATH=%BEA_HOME%\patch_wls1001\profiles\myCustomProfile\native
SET PATCH_PATH=%BEA_HOME%\patch_wls1001\profiles\myCustomProfile\native

Script Snippet for UNIX

export PATCH_CLASSPATH=${BEA_HOME}/patch_wls1001/profiles/myCustomProfile/sys_manifest_classpath/weblogic_patch.jar

export WEBLOGIC_EXTENSION_DIRS=${BEA_HOME}/patch_wls1001/profiles/myCustomProfile/sysext_manifest_classpath

export PATCH_LIBPATH=${BEA_HOME}/patch_wls1001/profiles/myCustomProfile/native
export PATCH_PATH=${BEA_HOME}/patch_wls1001/profiles/myCustomProfile/native

This procedure describes the steps for using the Start Script Editor for WebLogic Platform 9.x, ALSB 2.5, and ALSB 2.6. To use the Start Script Editor, complete the following steps:

1. In Smart Update, select a target installation from the Target Installation panel.

2. Choose Patches > Start Script Editor.

3. In the Start Script Editor dialog box:

   1. Choose the patch profile to which the domain or server will point. For information about using a custom patch profile to scope a patch to a specific domain or server, see Chapter 9, "Best Practices for Distributing Maintenance Updates."

   2. Choose the product for which you are editing a start script. See Figure 5-3.

      Note:

      If you select Workshop for WebLogic, your domain does not automatically download any of the WebLogic Server patches that might exist in that custom profile.

   3. Open the start script you want to modify.

      For detailed instructions, see Opening a Start Script.

   4. Add the appropriate patch path variable definition to your patch profile.

      The Start Script Editor provides code snippets with suggested definitions for the PATCH_CLASSPATH, WEBLOGIC_EXTENSION_DIRS, PATCH_LIBPATH, and PATCH_PATH variables, all of which are customized for the previously-selected patch profile. You may want to modify these definitions, however, depending on your needs:

      • If you are modifying your script to point to the patches in the default patch profile, see Pointing All Domains and Servers at Patches Through Custom Scripts for instructions.

      • If you are modifying your script to point to the patches in a custom patch profile, see Chapter 6, "Patching Individual Applications, Domains, or Servers," to learn how to create a custom patch profile and add pointers to that profile to the start script for a domain or server.

   5. If your custom patch profile myCustomProfile contains both WebLogic Server and Workshop for WebLogic patches, and you want all of them to be active in a specific domain, you must first edit the domain start script to include a product-specific tokenized path declaration, similar to the snippets, but modeled on the declarations in setPatchEnv.cmd:

      For example:

      WLS_PATCH_CLASSPATH=  and  WLW_PATCH_CLASSPATH=
      

      instead of:

      PATCH_CLASSPATH=
      

      You must also include a concatenation statement similar to the one found in setPatchEnv.cmd:

      set PATCH_CLASSPATH=%WLS_PATCH_CLASSPATH%;%WLW_PATCH_CLASSPATH%
      

      Repeat this for each path type.

   6. Save the start script.

      Note:

      When adding a definition of a patch path variable to a start script, ensure that the definition appears before any statement that invokes another start script. For example, if you add a patch path variable definition to the setDomainEnv script, add it before the statement that invokes the commEnv script. This placement ensures that the definition you add is not overridden by a definition appearing in any of the start scripts that are subsequently invoked.

Smart Update does not enforce or control how you modify start scripts. If, however, you use the start scripts that are created by default by standard tools such as the Configuration Wizard, and maintain them in the default locations determined by those tools, Smart Update can provide a more structured and predictable way to locate the appropriate start scripts that must be modified for the purposes of pointing to the patches in a patch profile.

The Start Script Editor dialog box is not a wizard; it does not perform the following tasks:

• Detect all appropriate scripts that must be modified. If you use the start scripts provided, by default, by the Configuration Wizard, the Start Script Editor can help you find them quickly.

  If you have customized your server and domain start mechanisms, you might need to take additional steps beyond working with the Start Script Editor to make all the necessary changes.

• Modify start scripts. The Start Script Editor displays scripts and suggests additions to them, but you make the final decisions about which modifications to make and where to save them.

• Create backup copies of your start scripts.

Opening a Start Script

When you open a start script, by clicking Open in the Start Script Editor dialog box, Smart Update displays the Open Start Script dialog box. Use this dialog to locate the start script in which you want to add pointers from a domain, Managed Servers, a cluster, or an individual server to the patches in a patch profile.

In the Start Script Editor dialog box, the icons described in Table 5-5 are used to guide you to the directory containing the start script you want to modify.

Table 5-5 Open Start Script Dialog Box Icons

This icon	Marks
	The parent directory, within a domain, of the bin subdirectory in which, by default, the scripts you need to change reside.
	A domain subdirectory, such as bin, in which script files reside. To open a subdirectory and display the scripts in it, click this icon.

If you use the directory structure created for a domain by the Configuration Wizard, Smart Update guides you to the directories containing the start scripts that you need to change.

For information about locating a specific start script to modify, see the following topics:

• Modifying the Domain Start Script

• Modifying the Start Script for All Managed Servers or a Cluster

• Modifying the Start Script for a Specific Server

Modifying the Domain Start Script

To modify the start script for a domain, select the setDomainEnv or startWebLogic script in the domain bin subdirectory. Figure 5-3 shows how to select the setDomainEnv script on a Windows system.

Figure 5-3 Selecting the setDomainEnv Script in the Select Start Script Dialog Box

Description of "Figure 5-3 Selecting the setDomainEnv Script in the Select Start Script Dialog Box"

The setDomainEnv script contains placeholders for definitions of the PATCH_CLASSPATH, PATCH_LIBPATH, and PATCH_PATH variables. For information about modifying this script, see Table 5-6.

Table 5-6 Modifying Scripts

For information about modifying	See the following topic
The placeholders for definitions of the PATCH_CLASSPATH, PATCH_LIBPATH, and PATCH_PATH variables	Placeholders for Defining Patch Path Variables in Default Scripts
This script to point to the patches in the default patch profile	Pointing All Domains and Servers at Patches Through Custom Scripts
This script to point to the patches in a custom patch profile	Pointing Domains and Servers at a Custom Patch Profile

Modifying the Start Script for All Managed Servers or a Cluster

To modify the start script for all Managed Servers in a domain, which by default includes all servers in a cluster, select the startManagedWebLogic script in the domain bin subdirectory, as Figure 5-4 shows on a Windows system.

Figure 5-4 Selecting the startManagedWebLogic Script in the Select Start Script Dialog Box

Description of "Figure 5-4 Selecting the startManagedWebLogic Script in the Select Start Script Dialog Box"

For information about modifying this script, see the following table.

Table 5-7 Modifying Script

For information about modifying this script to	See the following topic
Point to the patches in the default patch profile	Pointing All Domains and Servers at Patches Through Custom Scripts
Point to the patches in a custom patch profile	Pointing Domains and Servers at a Custom Patch Profile

Modifying the Start Script for a Specific Server

To modify the start script for a particular server in a domain, select the uniquely-named start script for that server in the domain bin subdirectory. Figure 5-5 shows how to select the start script startWebLogicServer1 on a Windows system.

Figure 5-5 Selecting a Server Start Script in the Select Start Script Dialog Box

Description of "Figure 5-5 Selecting a Server Start Script in the Select Start Script Dialog Box"

For information about modifying this script, see the following table.

Table 5-8 Modifying Start Script

For information about modifying this script to	See the following topic
Point to the patches in the default patch profile	Pointing All Domains and Servers at Patches Through Custom Scripts
Point to the patches in a custom patch profile	Pointing Domains and Servers at a Custom Patch Profile

Pointing Domains and Servers at Patch JARs in the Default Patch Profile for the WebLogic System Classpath

When the domains and servers in your environment are started, the patch JARs that have been applied to the default patch profile should be inserted into the WebLogic system classpath. To ensure that the patch JARs are inserted into this classpath properly, you must add, to your start script, the code described in this section.

1. Add a default definition of the PATCH_CLASSPATH environment variable. For example:

   if "%PATCH_CLASSPATH%" == "" set PATCH_CLASSPATH=BEA_HOME\patch_wls1001\profiles\default\sys_manifest_classpath\weblogic_patch.jar
   

   This definition enables individual servers or domains to override this definition, if those servers or domains must point to the patches in a custom patch profile. In this definition, BEA_HOME represents the Middleware home directory path. You can specify an absolute path, or use an environment variable, which you have previously defined (recommended).

   Note:

   Starting from the Oracle Fusion Middleware 11gR1 release, MW_HOME is the new term for BEA_HOME.

2. Add PATCH_CLASSPATH to the beginning of the statement that sets the WebLogic system classpath. For example:

   set WEBLOGIC_CLASSPATH=%PATCH_CLASSPATH%;%JAVA_HOME%\lib\tools.jar;
   %WL_HOME%\server\lib\weblogic_sp.jar;%WL_HOME%\server\lib\weblogic.jar;
   %WL_HOME%\server\lib\webservices.jar
   

   This ensures that classes in the patch JARs override existing, same-named classes appearing later in the classpath.

   If your default patch profile contains patch JARs for applications that are deployed on WebLogic Server for a product, you can define the WEBLOGIC_EXTENSION_DIRS environment variable to point to the patch JARs for that application as follows:

   if "%WEBLOGIC_EXTENSION_DIRS%" == "" set WEBLOGIC_EXTENSION_DIRS=
   %BEA_HOME%\patch_wls1001\profiles\default\sysext_manifest_classpath
   

   Note:

   The WEBLOGIC_EXTENSION_DIRS variable is reserved for use by products that require the classes in a patch JAR file to be loaded into the classpath of an application that is deployed on WebLogic Server. This mechanism for patching deployed applications is not currently being used with WebLogic Server 9.1.Note that starting from the Oracle Fusion Middleware 11gR1 release, MW_HOME is the new term for BEA_HOME.

Pointing Domains and Servers at Library Patches in the Default Patch Profile

It is important to ensure that the native files that have been applied to the default patch profile are inserted into the system library path, whenever any of the domains or servers in your environment are started. To ensure that these files are inserted properly, add the code provided in this section to the script that you have chosen to point to the patches applied to the default patch profile.

To add this code to your script, follow the appropriate instructions:

• For UNIX Systems

• For Windows Systems

Module Patching in WebLogic Server

Products such as WebLogic Server load modules to run-time containers through the classpath. For more information about loading patches to a classpath, see Classpath, Extended Classpath, and Native Library Patches.

Module Patching in OSGi-Based Products

OSGi-based products load modules to run-time containers through the OSGi-based launcher. The launcher determines the necessary modules and the sequence of modules to be loaded at run time. It also determines whether a module is patched for a given product. If a module is patched, the updated version is loaded and used. The scope of a module patch is specific to the product and to the patch profile. This provides the necessary granularity to ensure that a patch is specific to one product and not to all products in the same Middleware home directory.

In an OSGi-based product installation, you can see two directories for modules—common modules (BEA_HOME\modules) and product-specific modules (for example, BEA_HOME\wlevs20\modules). Figure 5-6 shows the structure of these directories.

Figure 5-6 Installation-Level Directory Structure for WebLogic Event Server

Description of "Figure 5-6 Installation-Level Directory Structure for WebLogic Event Server"

Overview

Shared archive patches were introduced to support shared libraries, and in particular WebLogic library modules. Unlike other artifacts installed in the product directory, applications can use shared archives by direct name and version references, rather than relying on a well-known location. This implies that a default installation of a shared archive has an installation-wide (or domain-wide) scope until superseded by a custom installation of the same shared archive into a specified profile.

To activate a shared archive patch after application to the default or a custom profile in Smart Update, you must first deploy the patched archive in the affected domain, and potentially modify the application description to make specific reference to it.

Shared archive patches can be applied to an entire domain (or all domains running in a given installation) or selected applications in a domain. To affect potentially all domains in an installation, apply the shared archive patch to the default profile in Smart Update.

For more information on this topic, see Default Application of Shared Archive Patches.

To affect only a specific application, you should apply the patch to a custom profile and update the archive references in the application descriptor. This approach would enable you to maintain unique patch profiles for each application that utilizes shared libraries, if necessary.

For more information on this topic, see Activating Shared Archive Patches in Custom Profiles with Application Scope.

Default Application of Shared Archive Patches

When a shared archive patch is applied in Smart Update to the default profile, it is treated by the Patch Management System as applicable to the entire installation. Consequently, when you apply a shared archive patch to the default profile, the patch is applied to all custom profiles (if any) as well. Smart Update warns you that the patch will be applied to the entire product installation. If you click Continue, the patch is applied to all profiles.

The actual write location of the patched shared archive is usually relative to the product shared library directory. You may need this information, depending on how you choose to deploy it.

Shared libraries are located under:

• WL_HOME/common/deployable-libraries

• WL_HOME/portal/lib/modules

• WL_HOME/servicebus/lib

• WL_HOME/integration/common/lib/installation

Typically, portal-shared archive patches are installed under maintenance/default in the above common and portal shared library directories. Other products may institute differing default patch directory structures. If you need further guidance for a specific patch, consult My Oracle Support.

If the patch is replacing an existing archive and it is already deployed, you just need to restart the server. If the patch contains a new version, or is to be installed under a different directory, you must deploy the patched archive. Deployment can be done using the WebLogic Server console, custom WLST script, or by directly updating config.xml for the target domain.

On successful deployment of the patched archive, it (including the name, specification, and version number) is visible in the WebLogic Server administration console.

If you leave the library module manifest untouched, all references to the library module remain intact and all applications in the domain immediately take advantage of new functionality without additional manual configurations to application descriptors.

Activating Shared Archive Patches in Custom Profiles with Application Scope

In some cases, you may want to control and apply a patch at a certain level to selected applications. To apply a shared archive patch in such a scenario, create a custom profile and apply shared archive patches to that custom profile only.

To distinguish one version of a shared library patch from another and to allow different versions of a shared library to coexist in a single domain, versions can be distinguished by unique names or unique implementation versions, or both.

After applying a shared archive patch to a custom profile in Smart Update, two steps are required to activate it for the application you intend to patch:

1. Deploy the patch in the custom profile.

2. Update the application descriptor to reference the specific version of the patched archive.

The steps to deploy the shared archive patch in a custom profile are the same as those for shared archive patches in the default profile, except that in the custom profile case the patch is located in the following directory:

BEA_HOME/patch_weblogic[version]/profile/custom-profile-name/archives

For example: BEA_HOME/patch_wls1001/profile/customProfile

<weblogic-application xmlns="http://www.bea.com/ns/weblogic/90"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> 
<library-ref> 
<library-name>wlp-tools-admin-app-lib</library-name> 
<specification-version> 9.2.0 </specification-version> 
implementation-version> 9.2.0.0.1 </implementation-version> 
<exact-match> true </exact-match> 
</library-ref> 
</weblogic-application>