Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java Enterprise System 5 Upgrade Guide for UNIX 

Chapter 11
Application Server

This chapter describes how to upgrade Application Server to Java ES 5 (Release 5): Sun Java System Application Server Enterprise Edition 8.2.

The chapter provides an overview of upgrade considerations for the different upgrade paths supported by Release 5. The chapter covers upgrades on both the Solaris and Linux operating systems:

Overview of Application Server Upgrades

This section describes the following general aspects of Application Server that impact upgrading to Java ES 5 (Release 5):

About Java ES Release 5 Application Server

Java ES Release 5 Application Server represents a minor release with respect to Release 4, including only selected bug fixes. Release 5 Application Server is functionally the same as Release 4.

Application Server Upgrade Roadmap

There are two sets of upgrade paths that apply to upgrade of Application Server to Java ES Release 5:

Application Server Data

The following table shows the type of data that could be impacted by an upgrade of Application Server software.

Table 11-4  Application Server Data Usage

Type of Data

Location

Usage

Environment variables

AppServer8-base/config/asenv.conf

Global variables

Configuration data

Release 3, Release 4, & Release 5:
domain.xml and server.policy files in
AppServer8Config-base/domains/domainName/config

Release 2:
server.xml and server.policy files in
AppServer7Config-base/domains/domainName/
instanceName/config

Configuration of Application Server instances

Deployment data

Release 3, Release 4, & Release 5:
AppServer8Config-base/domains/domainName/
applications

Release 2:
AppServer7Config-base/domains/domainName/
instanceName/applications

Configuration of J2EE container for specific J2EE components and applications

Access log files

Release 3, Release 4, & Release 5:
AppServer8Config-base/domains/domainName/
logs/access/
Contains two files:
server_acces_log and _asadmin_access_log

Release 2:
AppServer7Config-base/domains/domainName/
instanceName/logs/access

Access logging

Application Server Upgrade Strategy

Your strategy for upgrading Application Server generally depends on the many considerations discussed in Chapter 1, "Planning for Upgrades": upgrade path, dependencies between Java ES components, selective upgrade versus upgrade all, multi-instance deployments, and so forth.

This section is to particularize that general discussion to Application Server by presenting issues that might influence your Application Server upgrade plan.

Compatibility Issues

Release 5 Application Server does not introduce any interface changes with respect to Release 4 or Release 3. However, there are major interface changes between Release 5 and Release 2, making Release 5 incompatible with Release 2.

Release 5 Application Server, however, does not support Release 4 Service Registry. If Application Server is upgraded to Release 5, the Service Registry must also be upgraded to Release 5.

Application Server Dependencies

Application Server dependencies on other Java ES components can impact the procedure for upgrading and re-configuring Application Server software. Changes in Application Server interfaces or functions, for example, could require upgraded versions of components upon which Application Server depends. The need to upgrade such components depends upon the specific upgrade path.

Application Server has dependencies on the following Java ES components:

Dual Upgrade

Dual upgrades, in which both Application Server and operating system are upgraded (as described in Dual Upgrades: Java ES and Operating System Softwared) can be performed in either of two ways:

Fresh Operating System Installation
  1. Back up existing Application Server data.

    2. See Application Server Data for the location of essential data.

  2. Install the new operating system.

    3. The operating system installation can only be on the same computer and will wipe out the existing file system.

  3. Restore the Application Server data that was backed up in Step 1.
  4. Install Release 5 Application Server.

    5. Use the procedure documented in the relevant upgrade section of this chapter, depending on the version of Application Server data that was backed up in Step 1.

In-place Operating System Upgrade
  1. Back up existing Application Server data.

    2. See Application Server Data for the location of essential data.

  2. Upgrade the operating system.

    3. The upgrade leaves the existing file system in place.

  3. Upgrade to Release 5 Application Server.

    4. See the relevant section of this chapter, depending on upgrade path.

Upgrading Application Server from Java ES Release 4

This section includes information about upgrading Application Server from Java ES 2005Q4 (Release 4) to Java ES 5 (Release 5). The section covers the following topics:

Introduction

When upgrading Java ES Release 4 Application Server to Release 5, consider the following aspects of the upgrade process:

Release 4 Application Server Upgrade

This section describes how to perform an upgrade of Application Server from Java ES Release 4 to Java ES Release 5 on both the Solaris and Linux platform. Where a topic depends on platform-specific procedures, the topic will indicate the operating system to which it applies. The section covers the following topics:

Pre-Upgrade Tasks

Before you upgrade Application Server software you should perform the following tasks:

Verify Current Version Information

You can verify the current version of Application Server by entering the following command:

Upgrade Application Server Dependencies

It is generally recommended that all Java ES components on a computer system (and in a computing environment) be upgraded to Java ES Release 5. Application Server has hard upgrade dependencies on the NSS shared component and on Message Queue, HADB, and Java DB product components.

When upgrading Application Server dependencies, you should do so in the order below (skipping any that might already have been upgraded), before you upgrade Application Server. However, upgrade of shared components as well as Message Queue, HADB, and Java DB is normally achieved automatically by the Java ES installer when upgrading Application Server.

  1. Shared Components.  Instructions for synchronizing Java ES shared components to Release 5 are provided in Upgrading Java ES Shared Components. However, all shared components required by Application Server are upgraded automatically by the Java ES installer when you perform an upgrade of Application Server to Release 5.
  2. Message Queue.  Instructions for upgrading Message Queue to Release 5 are provided in Chapter 10, "Message Queue".
  3. High Availability Session Store (HADB).  Instructions for upgrading HADB are provided in Chapter 9, "High Availability Session Store".
  4. Java DB.  Instructions for upgrading Java DB are provided in Chapter 8, "Java DB".
  5. Web Container Software (soft upgrade dependency).  Instructions for upgrading Web Server are provided in Chapter 7, "Web Server".
Back Up Application Server Data

The Application Server upgrade from Release 4 to Release 5 does not modify configuration data. There is therefore no need to back up current data.

Obtain Required Configuration Information and Passwords

You should know the Application Server administrator user ID and password for your currently installed version.

Upgrading Release 4 Application Server

This section discusses considerations that impact the upgrade procedure for Application Server followed by a description of the procedure itself.

Upgrade Considerations

The upgrade of Application Server software to Java ES Release 5 takes into account the following considerations:

Upgrade Procedure

The procedure documented below applies to Application Server instances residing locally on the computer where the upgrade is taking place.

  1. Log in as root or become superuser.

    2. su -

  2. Shut down all J2EE components running in the Application Server instances that are to be upgraded.
  3. Shut down all Application Server instances on the computer that is to be upgraded.
    1. Stop all running node agents.

      2. AppServer8-base/bin/asadmin stop-node-agent --user admin_ID
           nodeagentName

      where nodeagentName has the form hostName_domainName, but is simply hostName by default.

    2. Stop the Domain Administration Server (DAS).

      3. AppServer8-base/bin/asadmin stop-domain --user admin_ID
           domainName

    3. Stop the PointBase database server (if being used).

      4. AppServer8Config-base/appserver/pointbase/tools/stopserver.sh

  4. Launch the Java ES installer.

    5. cd Java ES Release 5 distribution/os_arch
    ./installer

    where 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.”)

  5. Select Application Server in the component selection page.

    6. As hard upgrade dependencies, Message Queue, HADB, and Java DB will also be automatically selected for upgrade.

  6. Choose to Configure Now.
  7. Specify the configuration values requested.

    8. You will be presented with a number of configuration panels.

  8. Confirm your upgrade choice.

    9. Application Server packages (and, if necessary, those for Message Queue, HADB, and Java DB) will be upgraded and an upgrade summary displayed.

  9. Exit the Java ES installer.
  10. Restart the upgraded Domain Administration Server (DAS).

    11. AppServer8-base/bin/asadmin start-domain --user admin_ID
         domainName

  11. Restart the upgraded Application Server instances.

    12. AppServer8-base/bin/asadmin start-node-agent --user admin_ID
         nodeagentName

    where nodeagentName has the form hostName_domainName, but is simply hostName by default.

Verifying the Upgrade

You can verify successful upgrade using the following command:

AppServer8-base/bin/asadmin version --verbose

See Table 11-5 for output values.

Post-Upgrade Tasks

If you want to continue using the embedded Release 4 PointBase database in stead of Java DB, a new Release 5 Java ES product component, you have to manually edit the upgraded AppServer8-base/config/asenv.conf file.

After upgrading Application Server from Release 4, the PointBase settings in asenv.conf are as follows:

Change these settings to the following values:

AS_POINTBASE="AppServer8-base/pointbase"
AS_POINTBASE_SAMPLESDB="AppServerConfig8-base/var/appserver/pointbase"

Rolling Back the Upgrade

Rollback of the Release 5 upgrade is not supported.

Upgrading Application Server from Java ES Release 3

The procedure for upgrading Java ES 2005Q1 (Release 3) Application Server to Release 5 is the same as that for upgrading Release 4 Application Server to Release 5.

To upgrade Release 3 Application Server to Release 5, use the instructions in Upgrading Application Server from Java ES Release 4, except substitute Release 3 wherever Release 4 is referenced.

Upgrading Application Server from Java ES Release 2

This section includes information about upgrading Application Server from Java ES Release 2 to Java ES 5 (Release 5). The section covers the following topics:

Introduction

When upgrading Java ES Release 2 Application Server to Release 5, consider the following aspects of the upgrade process:

Release 2 Application Server Upgrade

This section describes how to perform an upgrade of Application Server from Java ES Release 2 to Java ES Release 5 on both the Solaris and Linux platform. Where a topic depends on platform-specific procedures, the topic will indicate the operating system to which it applies. The section covers the following topics:

Pre-Upgrade Tasks

Before you upgrade Application Server you should perform the following tasks:

Solaris OS Only: Manually Remove the Application Server Packages Bundled with the Operating System

The installation of Release 2 Application Server did not remove the version of Application Server bundled with the Solaris OS. To properly upgrade Release 2 Application Server to Release 5, you have to perform the following steps.

  1. Uninstall the bundled version of by manually removing the corresponding Application Server packages located in the /usr/appserver directory:

    2. pkgrm SUNWascmnse SUNWaslb SUNWasut ...

    where the full set of packages can be obtained using the following command:

    pkginfo -i|grep -i “application server”

    The results would include packages such as:

    SUNWasacee, SUNWascmnse, SUNWasu, SUNWasuee, SUNWasac, SUNWascmn, SUNWasdb, SUNWasdem, SUNWasdemdb, SUNWasr, SUNWasut, SUNWasman, SUNWasjdoc

    and might include localization packages as well:

    SUNWLocaleasacee, SUNWLocaleascmnse, SUNWLocaleasu, SUNWLocaleasuee

  2. If the bundled version has been used, delete the domains information:

    3. rm /usr/appserver/domains

Verify Current Version Information

You can verify the current version of Application Server by entering the following command:

AppServer7-base/bin/asadmin version --verbose

See Table 11-5 for version outputs.

Upgrade Application Server Dependencies

The upgrade of Application Server dependencies requires the upgrade to Release 5 of all locally-resident Release 2 components upon which Application Server depends, specifically Message Queue and shared components. Shared components, however, are upgraded automatically by the Java ES installer as part of the upgrade procedure (see Upgrade Procedure).

In addition, the upgrade of Application Server requires that HADB, and Java DB, upon which Release 5 Application Server depends, be installed. These product components, however, are automatically selected and installed by the Java ES installer as part of the upgrade procedure (see Upgrade Procedure).

In general, when upgrading Application Server dependencies, you should do so in the order below (skipping any that might already have been upgraded), before you upgrade Application Server. However, upgrade of shared components as well as installation of HADB,and Java DB are performed automatically by the Java ES installer when upgrading Application Server.

  1. Shared Components.  Instructions for synchronizing Java ES shared components to Release 5 are provided in Upgrading Java ES Shared Components. However, all shared components required by Application Server are upgraded automatically by the Java ES installer when you perform an upgrade of Application Server to Release 5.

    2. Note

    Upgrade of shared components to Release 5 includes the upgrade of J2SE to JDK version 1.5, which is not supported by Release 2 Application Server. Hence, before upgrading shared components, you should shut down Release 2 Application Server. Shared components are upgraded to release 5 whenever the Java ES installer is used to install or upgrade any Java ES product component (such as Directory Server, Message Queue, HADB, Java DB, and others).

  2. Message Queue.  See Upgrading Message Queue from Java ES Release 2. Message Queue cannot be upgraded from Release 2 using the Java ES installer.
  3. High Availability Session Store (HADB).   A fresh install of HADB is performed by the Java ES installer when upgrading Application Server.
  4. Java DB.   A fresh install of Java DB is performed by the Java ES installer when upgrading Application Server.
  5. Web Container Software (soft upgrade dependency).   See Upgrading Web Server from Java ES Release 2.
Back Up Application Server Data

The Application Server upgrade from Release 2 to Release 5 does not overwrite Release 2 configuration data. However, for safe measure, the entire domains directory should be backed up before performing the upgrade to Release 5:

Obtain Required Configuration Information and Passwords

You should know the following information about your currently installed version:

Upgrading Release 2 Application Server

This section discusses considerations that impact the upgrade procedure for Application Server followed by a description of the procedure itself.

Upgrade Considerations

The upgrade of Application Server software to Java ES Release 5 takes into account the following considerations:

Upgrade Procedure

The procedure documented below applies to all Application Server instances residing locally on the computer where the upgrade is taking place.

  1. Log in as root or become superuser.

    2. su -

  2. If Java ES shared components have been upgraded to Release 5 (in particular J2SE upgraded to JDK 1.5) while Release 2 Application Server was still running, then edit the asenv.conf file to point directly to JDK 1.4.

    3. AS_JAVA=/usr/java

    Application Server cannot be shut down (Step 3, below) if asenv.conf is referencing JDK 1.5.

  3. Stop all Application Server and related processes.

    4. AppServer7-base/bin/asadmin stop-appserv domainName

  4. Install Release 5 Application Server.

    5. Perform the following steps:

    1. Launch the Java ES installer on the computer hosting Release 2 Application Server.

      2. cd Java ES Release 5 distribution/os_arch
      ./installer

      where 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.”) Application Server is not shown as upgradable from Release 2.

    2. Select Application Server from the component selection page.

      3. Choose to install at least the first three subcomponents, including the Node Agent component.

    3. Click Next.

      4. If Message Queue has not already been upgraded to Release 5, an error message window asks you to upgrade Message Queue. In that case, click OK and upgrade Message Queue. The procedure is documented in Release 2 Message Queue Upgrade.

    4. Specify an installation directory different from that in which Release 2 Application Server was installed.
    5. Select the Configure Later option.

      6. Note

      If you are the version of Application Server bundled with Solaris 9 OS, and have never used this version (no domain information has been created), then you can select Configure Now and omit Step 5 and succeeding steps.

    6. If needed, select the option to install localized packages.
    7. Exit the Java ES installer when installation is complete.
  5. Perform the following post-install procedure:
    1. Locate the postInstall readme file in the Application Server tools directory of the Java ES Release 5 distribution:

      2. Java ES Release 5 distribution/os_arch/Product/application_svr/Tools

      where os_arch matches your platform, such as Solaris_sparc.

    2. Refer to the ReadMe file and run the postInstall script.

      3. cd Java ES Release 5 distribution/os_arch/Product/application_svr/Tools
      ./postInstall       AppServer8Install-base AppServer8Config-base

      The scripts configure and create the AppServer8-base/bin/* shell scripts and a config/asenv.conf file from templates that are installed during installation. (Normally the Java ES installer creates the bin/* shell scripts, but if Configure Later is chosen, they have to be created as described.)

      Note

      When you upgrade Application Server to Release 5, non-admin ports 8080 (default) and 8181 (secure) are allocated to the Domain Administration Server (DAS). These port assignments could possibly conflict with the ports allocated to Release 2 Application Server instances. If this is the case, then you must change the DAS ports to avoid the conflict. For instructions, see the section on how to modify http-listener attributes in the Sun Java System Application Server Enterprise 8.2 Edition Administration Guide, http://docs.sun.com/doc/819-4733.

    3. If necessary, modify the environment settings in the AppServer8-base/config/asenv.conf file.

      4. You have to edit the file manually.

      Note

      To configure Application Server for load balancing, refer to the “Configuring Web Servers for HTTP Load Balancing” section in the “Application Server High Availability Features” chapter of the Sun Java System Application Server Enterprise 8.2 Edition High Availability Administration Guide, http://docs.sun.com/doc/819-4740.

  6. Run the asupgrade utility.

    7. The asupgrade utility creates a Release 5 node agent under which it migrates Release 2 Application Server instances.

    The utility is located under the Application Server directory, for example:

    • Upgrade wizard mode: AppServer8-base/bin/asupgrade
    • Upgrade console mode: AppServer8-base/bin/asupgrade -c

      • The upgrade wizard or upgrade console will guide you through the upgrade steps.

    • Identify both target and source directories for the migration of domains information:
      • Release 2: AppServer7-base
      • Release 5: AppServerConfig8-base/domains
    • Provide the admin user, admin password, and master password of Release 2 Application Server.

      • If asked for a master password, specify changeit, and if you are using a keystore that has a master password other than changeit you should change the password to changeit.

      jdk-home/bin/keytool -storepasswd -new changeit -keystore keystore -storepass oldpasswd

      For more information about the Application Server asupgrade utility, refer to the user commands section of the Sun Java System Application Server Enterprise Edition 8.2 Reference Manual, http://docs.sun.com/doc/819-4736. and the Sun Java System Application Server Enterprise Edition 8.2 Upgrade and Migration Guide, http://docs.sun.com/doc/819-4737/6n6sao3ju?a=view.

  7. If you had redirected the asenv.conf file in Step 2, restore it to point to JDK 1.5.

    8. AS_JAVA=/usr/jdk/entsys-j2se

    Application Server cannot be started (Step 8 and Step 9, below) if asenv.conf is referencing JDK 1.4.

  8. Start the Domain Administration Server (DAS).

    9. AppServer8-base/bin/asadmin start-domain --user admin_ID
         domainName

  9. Restart upgraded Application Server instances.

    10. Do this by starting the node agent under which the upgraded Application Server instances have been migrated:

    AppServer8-base/bin/asadmin start-node-agent --user admin_ID
         nodeagentName

    where nodeagentName has the form hostName_domainName, but is simply hostName by default.

Verifying the Upgrade

Start the Admin Console and verify that these servers are started. If any of the servers are not running, check the following log file for failures that might be caused by port conflicts:

If there failures due to port conflicts, use the Admin Console to modify the port numbers to eliminate the conflicts, then stop and restart the node agent.

You can verify the upgrade of Application Server to Release 5 by entering the following command:

AppServer8-base/bin/asadmin version --verbose

See Table 11-5 for output values.

Post-Upgrade Tasks

There are two post-upgrade tasks you have to perform beyond the steps described in Upgrade Procedure:

Correct the Reference to JSS

For Application Server to reference the correct version of the JSS shared component, you have to replace jss3.jar with jss4.jar in the Application Server domain.xml file located at:

AppServer8Config-base/domains/domainName/config/domain.xml

Migrate Release 2 J2EE Components

You have to migrate Release 2 J2EE components and applications to run in a Release 5 Application Server environment and redeploy them to the appropriate Application Server instances. For more information about migrating J2EE components and applications, refer to Chapter 4 of the Application Server Enterprise Edition 8.2 Upgrade and Migration Guide, http://docs.sun.com/doc/819-4737.

Rolling Back the Upgrade

The procedure for rolling back the upgrade to Release 5 of Application Server is simply to revert to the Release 2 version of Application Server, which was not removed by the upgrade to Release 5.

Upgrading the Solaris-bundled Application Server in a Solaris 10 Multi-zone Environment

Application Server (as well as Message Queue, upon which Application Server depends), is bundled with the Solaris 10 OS. Unless removed from the global zone, the bundled Application Server is propagated to non-global zones when such zones are created. The existence of the bundled Application Server in all zones impacts the subsequent upgrade of Application Server to Release 5:

The following example is provided to document some of the subtleties involved in upgrading Application Server in a Solaris 10 multi-zone environment. (For a more comprehensive discussion regarding Java ES and Solaris 10 zones, see Java ES 5 Upgrade and Solaris 10 Zones.)

The objective in the example is to upgrade to Release 5 the Solaris-bundled Application Server (version 8.0.0_01) in a Solaris 10 sparse root zone.

You cannot simply upgrade Application Server in a sparse root zone because the Solaris-bundled Application Server is installed in a read-only directory mounted from the global zone. Hence, to upgrade Application Server to Release 5 in the sparse root zone, you must first remove the bundled version in the global zone.

In addition, Message Queue is installed in the global zone, representing a departure from the practice by which only shared components (not product components) are to be installed in the global zone. This is because Message Queue cannot be installed or upgraded in a sparse root zone because of the read-only directories.

The procedure for upgrading the Solaris-bundled Application Server (version 8.0.0_01) in a Solaris 10 sparse root zone to Release 5 is as follows:

  1. Verify the initial state of your system.

    2. This example assumes a version of Solaris 10 with a sparse root zone that has been configured, installed, and booted by the global administrator.

    The sparse root zone includes all Java ES components that are already installed in the global zone, namely the versions of Message Queue and Application Server bundled with Solaris 10.

    In addition, the example assumes that the user has previously used the bundled Application Server in the sparse root zone, having created administrative domain information that needs to be preserved.

  2. Upgrade the bundled version of Application Server in the global zone.

    3. This operation removes the bundled Application Server packages and replaces them with Release 5 packages. The removal of the bundled packages is propagated to the sparse root zone, effectively uninstalling Application Server packages in the sparse root zone, but the Release 5 packages are not propagated to non-global zones.

    1. Run the Java ES installer in the global zone.
    2. Select Application Server in the component selection page.

      3. Message Queue, HADB, and Java DB will automatically be selected, and Application Server and Message Queue will be marked as upgradable.

    3. Complete the upgrade.

      4. While Release 5 Message Queue will propagate to the sparse root zone, neither Application Server, HADB, nor Java DB will be propagated. In addition all shared components will be synchronized to Release 5 and propagated to the sparse root zone.

  3. Install Application Server in the sparse root zone.
    1. Run the Java ES installer in the sparse root zone.
    2. Select Application Server in the component selection page.

      3. De-select Message Queue if it is automatically selected, and select HADB and Java DB if they are not automatically selected.

    3. Complete the installation of Application Server.

      4. Choose to Configure Later so that domain information is not overwritten by the installation process.

      In the case where no domains had been created, you can choose to Configure Now.c



Previous      Contents      Index      Next     

Part No: 819-6553-11
June 2007.   Copyright 2007 Sun Microsystems, Inc. All rights reserved.