Sun Java Enterprise System 5 Upgrade Guide for UNIX |
Chapter 2
Upgrading Java ES Shared ComponentsThis chapter provides information on upgrading Java ES shared components to Java ES 5 (Release 5).
Each Java ES product component depends on one or more locally shared libraries known as Java ES shared components. Shared components are installed automatically by the Java ES installer during product component installation, depending on the product components that are being installed. They are not explicitly selected, installed, or configured during deployment of Java ES product components.
Similarly, for those product components that can be upgraded using the Java ES installer, the corresponding shared components are upgraded automatically.
However, in cases where product components are upgraded manually, as described in several chapters of this Upgrade Guide, the upgrade of shared components might need to be performed explicitly, using the procedures described in this chapter.
The chapter contains the following sections:
Be sure to read Special Upgrade Procedures before performing a shared component upgrade.
Shared Component Upgrade OverviewUpgrading shared components to Java ES 5 (Release 5) should be done as part of a larger upgrade plan, as discussed in Chapter 1, "Planning for Upgrades." To ensure that you have a successful upgrade, read Chapter 1 carefully and prepare an upgrade plan that meets your needs.
This section covers the following topics:
General Considerations
When upgrading shared components, consider the following issues:
- Operating System Issues. Perform any operating system upgrades, as described in Operating System Considerations. For all platforms except for Solaris 10 operating system, perform operating system upgrades before you upgrade shared components.
- Sequencing Guidelines. Review the sequencing guidelines listed in Upgrade Sequencing Guidelines. Typically, shared components are upgraded first. However, you should understand the entire sequence of your upgrade to Java ES Release 5 before beginning your upgrade process.
Synchronizing Shared Components
The difficulty of testing and supporting the large number (around 30) and complex interactions between Java ES shared components and Java ES product components requires that all shared components within a single operating system instance be synchronized to the same Java ES version. An operating system instance means a single computer running the Solaris 9 or Linux operating system, or in the case of the Solaris 10 operating system, it means any of the virtual operating system environments (zones) running on a single computer.
In other words, all Java ES shared components installed in an operating system instance must be of the same version. This synchronization requirement sets certain restrictions on how Java ES shared components can be installed and upgraded:
- Different versions of Java ES shared components can only reside in different operating system instances. For example, you can install Java ES Release 4 shared components in one operating system instance and Java ES Release 5 shared components in another operating system instance, but you cannot combine them in the same operating system instance.
- If any shared component in an operating system instance is upgraded or any new shared component of higher version is introduced, then all shared components in that operating system instance must also be upgraded at the same time. (Shared components are required to be backwardly compatible, so there is no problem for Release 4 product components to work with Release 5 shared components.)
For example, suppose an Release 5 product component is installed in an operating system instance in which one or more Release 4 product components reside. Because the Release 5 product component requires some number of Release 5 shared components, the synchronization requirement means that all Release 4 shared components residing in that operating system instance must be upgraded to Release 5 at the same time the Release 5 product component is installed. (This is the case even if the Release 5 product component being installed requires different shared components from those that are already installed.)
Similarly, if an Release 4 product component is upgraded to Release 5, and that upgrade requires the upgrade of some number of shared components upon which it depends, then all shared components installed in that operating system instance must be upgraded to Release 5, whether or not the particular Release 4 product component being upgraded has dependencies upon all of them or not.
Synchronize All Shared Components
The Java ES installer includes a synchronize all shared components function for situations in which all shared components must be synchronized to their Release 5 versions.
When All Shared Components is selected in the component selection page of the Java ES installer, the installer will upgrade any existing shared components and install any missing shared components, whether or not they are needed by any specific product component.
The synchronize all shared components function supports the upgrade of product components not explicitly upgraded by the Java ES installer (that is, all Java ES product components except Application Server, Message Queue, HADB, and Java DB). For example, the synchronize all shared components function is used to upgrade Web Proxy Server and Portal Server to Release 5.
The rationale for the synchronization of all shared components in this case is that the installer currently has no knowledge of which shared components need to be synchronized on a computer. Therefore this function installs or upgrades all Java ES shared components to the Release 5 version.
The synchronize all shared components function also supports a number of zones scenarios as described in Solaris 10 Zone Considerations, below.
Solaris 10 Zone Considerations
Some of the limitations in the way Java ES can be deployed in a Solaris 10 multi-zone environment derive from shared component considerations.
Foremost of these considerations is that a large number of shared components cannot be installed in sparse root zones because of the read-only file systems in sparse root zones. This limitation applies to those shared components whose base directory is /usr (a directory that by default is shared by the global zone).
The inability to install a number of Java ES shared components in sparse root zones means that to successfully install or upgrade product components which have dependencies on such shared components into sparse root zones, the shared components must first be installed or upgraded in the global zone from which they propagate to non-global zones.
Because of the synchronization requirements regarding shared components (see Synchronizing Shared Components), and because the installation or upgrade of shared components in the global zone must accommodate any product component that is being installed or upgraded in the sparse root zone, it is necessary to synchronize all shared components in the global zone to their Release 5 versions. This means upgrading any existing shared components and installing any missing shared components, whether or not they might be needed by any specific product component in a sparse root zone.
This synchronization of shared components in the global zone can be performed by selecting All Shared Components in the component selection page of the Java ES installer.
When shared components are installed in and propagate from the global zone (for example, by installing a Java ES product component in the global zone), then special care must be taken to maintain synchronization of shared components in all zones. Otherwise it would be possible for shared components of an earlier version in a non-global zone to be mixed with Release 5 shared components that have been propagated from the global zone.
Approaches to Upgrading Shared Components
There are two approaches possible for upgrading the shared components needed to upgrade a particular Java ES product component. One is to determine all the shared components required and manually install or upgrade these to their Release 5 versions. The other is to use the Java ES installer’s synchronize All Shared Components function.
However, because of the synchronization requirement regarding shared components (see Synchronizing Shared Components), the only practical approach is to use the synchronize All Shared Components function of the Java ES installer.
This is because it is very difficult in most cases to determine which shared components need to be installed or upgraded in any particular case, and even if this were done successfully, the manual upgrade of the required shared components is not trivial. Some shared components can be patched to their Release 5 versions, however some require replacement of previous packages with Release 5 packages. Depending on the upgrade path, some previous packages might need to be manually removed.
In the past, the difficulty of manually upgrading shared components created a significant barrier to upgrading product components. The synchronize All Shared Components function, despite the drawback of installing shared components that might not be needed, represents a significant improvement over the manual upgrading of shared components required in Java ES Release 3 and Release 4.
Shared Component Upgrade ProcedureThe procedure for upgrading shared components is to use the synchronize All Shared Components function of the Java ES installer.
- Log in as root or become superuser.
su -
- Shut down services or processes as indicated in Special Upgrade Procedures.
- Launch the Java ES installer.
cd Java ES Release 5 distribution/os_arch
./installerwhere os_arch matches your platform, such as Solaris_sparc. (Use the installer -nodisplay option for the command line interface.)
After the Welcome and License Agreement pages are displayed, you will be presented with a component selection page. (When installed components are detected that can be directly upgraded by the Java ES installer, they are shown with a status of “upgradable.”)
- Select All Shared Components in the component selection page.
- Confirm your choice.
All shared components will be synchronized to their Release 5 versions.
- Exit the Java ES installer.
See Special Upgrade Procedures for any follow-up procedures.
Special Upgrade ProceduresThis section provides special procedures needed for upgrading the following shared components:
Java SE Upgrade Procedures
Java ES Release 5 is certified for Java Platform, Standard Edition (Java SE) Version 5.0 Update 9, identified here as Java SE 5.0 Update 9. (Java SE 5.0 is sometimes referred to as developer version 1.5.0).
Like other shared components, Java SE is upgraded by the Java ES installer. However, the installer upgrades to Java SE 5.0 Update 9 whether or not other shared components are being installed or upgraded. You do not have to explicitly choose All Shared Components for Java SE 5.0 Update 9 to be installed.
When the installer detects an older version of Java SE packages or an incomplete set of packages on your computer (the complete set is: SUNWj5rt, SUNWj5rtx, SUNWj5dev, SUNWj5dmo, SUNWj5dvx, SUNWj5man, SUNWj5cfg, SUNWj5dmx), it presents you with a dialog. The dialog, which follows the component selection page, lets you choose to automatically upgrade Java SE to the Release 5 level or to bypass that automatic upgrade in favor of manually performing the upgrade.
- Manual Upgrade. If you choose to perform a manual upgrade of Java SE, use the following procedure:
- Exit the Java ES installer before installing or upgrading other components.
- Manually install the appropriate version of Java SE.
- Relaunch the Java ES installer.
If the installer detects the correct/complete version of Java SE, then it will allow you to proceed, otherwise, it will display the previous dialog.
- Automatic Upgrade. If you choose to perform an automatic upgrade of Java SE, the Java ES installer upgrades Java SE to Version 5.0 Update 9. The upgrade has the following behavior:
Checking the Java SE Symbolic Link
Java Enterprise System maintains a symbolic link to the supported version of Java SE platform to ensure that Java ES services can find the correct Java SE runtime to use.
Check the symbolic link (for example, on Solaris operating system) as follows:
ls -l /usr/jdk/entsys-j2se
lrwxrwxrwx 1 root other 7 Jul 7 23:18 /usr/jdk/entsys-j2se -> /usr/jdk/instances/jdk1.5.0where /usr/jdk/instances/jdk1.5.0 is the default location.
Verifying the Current Java SE Version
To determine which version of Java SE your Java ES installation is using, run the following command, which verifies the version of Java SE referenced by the Java SE symbolic link:
/usr/jdk/entsys-j2se/bin/java -version
The outputs are shown in the following table.
Common Agent Container Upgrade Procedures
If you are upgrading the Common Agent Container shared component in preparation for upgrading Sun Cluster software (that is, patching version 1.1), follow the procedures for upgrading dependency software in “Upgrading Sun Cluster Software” in the Sun Cluster Software Installation Guide for Solaris OS, http://docs.sun.com/doc/819-0420/6n2rlnncr?a=view.
For updates to the above Guide, see “Upgrading to Sun Cluster 3.1 8/05 Software” in the Sun Cluster 3.1 8/05 With Java Enterprise System 5 Special Instructions, http://docs.sun.com/doc/819-4351.
If you are upgrading the Common Agent Container shared component in preparation for upgrading other Java ES components (that is, upgrading to version 2.0), use the following procedure, noting the path name variables below:
Table 2-3 Common Agent Container Directory Paths
Path Name Variable
Solaris OS
Linux OS
rel4CACbase-dir
/opt/SUNWcacao
/opt/sun/cacao
rel5CAC-admin-dir
/usr/lib/cacao
/opt/sun/cacao
- If the current installation uses custom configuration settings, capture the configuration settings using the following commands:
rel4CAC-base-dir/bin/cacaoadm list-params
The output will be similar to the following:
java-flags=-Xms4M -Xmx64M
jmxmp-connector-port=10162
snmp-adaptor-port=10161
snmp-adaptor-trap-port=10162
commandstream-adaptor-port=10163
retries=4The example above shows the default values. Note any nondefault settings for use in Step 4.
- Stop Common Agent Container processes using the following commands:
rel4CAC-base-dir/bin/cacaoadm stop
echo $?If the exit code is not 0, force the stop:
rel4CAC-base-dir/bin/cacaoadm stop -f
- Upgrade the Common Agent Container using the synchronize All Shared Components function of the Java ES installer.
See Shared Component Upgrade Procedure.
- Apply any custom configuration settings previously captured in Step 1.
rel5CAC-admin-dir/bin/cacaoadm set-param java-flags=Value
rel5CAC-admin-dir/bin/cacaoadm set-param jmxmp-connector-port=Value
rel5CAC-admin-dir/bin/cacaoadm set-param snmp-adaptor-port=Value
rel5CAC-admin-dir/bin/cacaoadm set-param
snmp-adaptor-trap-port=Value
rel5CAC-admin-dir/bin/cacaoadm set-param
commandstream-adaptor-port=Value
rel5CAC-admin-dir/bin/cacaoadm set-param retries=Value- If you have upgraded Java SE to Java SE Version 5, run the rebuild-dependencies utility:
rel5CAC-admin-dir/bin/cacaoadm rebuild-dependencies
The output of this command will be:
Property updated: [java-home].
Property updated: [jdmk-home].
Property updated: [nss-lib-home].
Property updated: [nss-tools-home].- Restart Common Agent Container services:
rel5CAC-admin-dir/bin/cacaoadm stop
rel5CAC-admin-dir/bin/cacaoadm start- Verify the upgrade of Common Agent Container:
rel5CAC-admin-dir/bin/cacaoadm status
rel5CAC-admin-dir/bin/cacaoadm verify-configuration