Table of Contents
1. Introduction

1.1 Project/Component Working Name
1.2 Name(s) and e-mail address of Document Author(s)/Supplier
1.3. Date of This Document

2. Project Summary

2.1 Project Description
2.2 Risks and Assumptions

3. Problem Summary

3.1 Problem Area
3.2 Justification

4. Technical Description

4.1 Details
4.2 Bugs/RFE's
4.3 Scope
4.4 Out-of-scope
4.5 Interfaces
4.6 Documentation Impact
4.7 Configuration/administration Impact
4.8 High Availability Impact
4.9 Internationalization
4.10 Packaging
4.11 Security Impact
4.12 Compatibility
4.12 Dependencies

5. References
6. Schedule

1. Introduction

1.1. Project/Component Working Name

Sun Java System Application Server

1.2. Name(s) and e-mail address of Document Author(s)/Supplier

Prasad Subramanian : prasad.subramanian@sun.com

1.3. Date of This Document

01/29/2007

2. Project Summary

2.1. Project Description

This project can be described as the procedure for upgrading a previous version of the Application Server to Glassfish v2 of SJSAS 9.1 . The SJAS 9 upgrade tool (asupgrade) as the name indicates provides a facility for the users to upgrade the configuration of a previous version of SJSAS to a SJSAS 9 configuration. This is an update to the SJSAS 8.2 asupgrade.

2.2. Risks and Assumptions

It is assumed that any special upgrade requirements by the appserver modules will be accurately documented by the module owners. There is risk that if there are any major or too many changes to the AS 9 configurations late in the development cycle that the upgrade tool development will need to extend beyond HCF.

3. Problem Summary

3.1. Problem Area

When a customer upgrades from a previous version of the application server to the current version, the following is expected to happen

• Availability of the configuration and data from the domain of the version from which the user is upgrading. This includes deployed applications.

• Availability of the new features and configuration in the new version of the Application Server, out-of-box after upgrade

Its also imperative that the user know , which of these data would be transferred by the tool and which of these data would need to be done manually. The user should also know , what the are the pre-conditions for installation , before an Upgrade is carried out.

3.2. Justification

Anyone who has an AS 8.0 / AS 8.1 / AS 8.2 configuration and wants to upgrade it to an AS 9 configuration. Adds ease of use by making it easier to move the customer's current configuration to the newest version of the Application Server.

4. Technical Description

4.1 Details

The Upgrade Process

The Upgrade process for the Application Server starts with the user installing the binaries, of GlassFish v2 ( using the GlassFish jar installer) or Application Server 9.1 ( the file based installer ). The installation can be done either over the existing installation or in parallel to the existing installation.

The next step is to upgrade the domains in 8.x installation to make them work with 9.1 binaries installed. This process would involve the migration of existing configuration and data from the 8.x domains to the 9.1 domains. It also involves providing the new configuration, applications that area available “out-of-the-box” in a 9.1 domain , to this upgraded domain.

The Upgrade Tool

The Upgrade Tool , enables the user to upgrade domains from 8.x to 9.1 as mentioned in the above section. The tool has a CLI ( invoked by asupgrade -c ) and a GUI ( invoked by asupgrade ) , which interview the users for the location of the source domain and the target domain, and the admin credentials of the domain being upgraded. The tool supports the upgrade of domains on a per domain basis i.e. Each of the domains can be upgraded one-by-one, each domain at a time.

Upgrade Scenarios

The domains can be upgraded ( as per the process mentioned above ) in the following scenarios :

• In-Place

  The domains are upgraded in the same location or In-Place. In this case, the location of the 8.x domain is the same as the location of 9.1 or v2 domain. The existing domain is backed up , and after the Upgrade process is completed, the backed up domain is deleted. In case the Upgrade process fails, the backed up domain is restored back.

• Side-by-Side

  The 9.1 domain is installed in parallel to the existing 8.x domain , in a location specified by the user. In this scenario, the existing domain is retained as it is and a parallel domain corresponding to the 9.1 installation is created.

How is Upgrade Invoked ?

• In-line upgrade

  In-line upgrade is a silent mode of invoking upgrade via the asadmin start-domain command. When a user invokes the asadmin start-domain command, using the 9.1 binaries to start a 8.x domain , the asadmin detects that the domain corresponds to an older version of the AS and invokes the upgrade tool. This is an In-Place upgrade.

• Upgrade from file based installer ( for SJSAS 9.1)

  The file based installer would give the users an option of invoking the Upgrade Tool at the end of the installation process . It would seed the Upgrade Tool with the source domain, target domain and the admin credentials of the target server. Note that in this case, the scenario would be side-by-side and only domains that are in the default domains path ( defined by the AS_DEF_DOMAIN_PATH token in asenv.conf ) would be upgraded.

• Manual upgrade

  The user would use the manual invocation of the Upgrade Tool to upgrade domains. ( i.e. <as-install-dir>/bin/asupgrade -c OR <as-install-dir>/bin/asupgrade . This is by far the most flexible method , which can be used for upgrading either side-by-side / In-Place , domains in any location.

4.2. Bug/RFE Number(s)

6480040 : Need to redeploy apps while upgrading

6480041 : Need to add the newly added domain.xml elements while upgrade

6480060 : Need to add logging levels for the upgrade log

4.3. In Scope

With the introduction of profiles, the distinction between editions are being deprecated. There would one set of binaries for GlassFish v2/ Application Server 9.1 which would be available via three sets of installers. These installers are

1. File based PE installer - Installs the V2/ Application Server binaries

2. File Based EE installer – Installs the V2 / Application Server binaries and NSS/HADB and lbplugin

3. GlassFish jar installer – Installs the V2 binaries , and provides an ANT based build file to create domains and configure the installation.

The following table lists the upgrade options from 8.x PE or 8.x EE to 9.1

Note that , upgrading a domain in a PE installation creates a domain with a “developer” profile.

The Upgrade Tool would take care of the following areas while upgrading

• Migrating data and configuration

  Each domain could possibly have more than one instance and clusters, along with standalone instance and node-agents. This data regarding the domain setup would be migrated across to the new domain. This includes the domain.xml , server.policy and realms .

• Migrating certificates and keys

  Each domain would have the key-cert pairs in keystores, which would be migrated across to the new domain.

• Migrating Applications deployed

  Each domain would have applications deployed on clusters or instances, which would need to be migrated over. The current thought is that these applications would need to be redeployed on the 9.1 domain . The Upgrade Tool would create an archive for each of these applications from the domain-dir/applications/j2ee-modules/<app-name> directory and use these archives for redeployment. This is an OPEN ISSUE and is under discussion.

New Features

• Automatic In-Line upgrade

  of a 8.x domain when started with the AS 9 asadmin start-domain command , as mentioned in the section 4.1 above.

• Improved logging for the upgrade process

  The current upgrade log supports a single logging level.We need to add support to have multiple logging levels namely FINEST,FINE,WARNING,SEVERE,INFO .

4.4. Out of Scope

• Upgrade of HADB/MQ

  Upgrade tool does not upgrade HADB or MQ. Upgrade documentation will cross reference the upgrade guides for these products.

• Migration of custom libraries

  If the user applications on the AS use custom libraries, it would be the responsibility of these applications to transfer these custom libraries to AS 9.1 . The upgrade tool would simply migrate the classpath setting ( if any) associated with these custom libraries.

4.5. Interfaces

4.5.1 Exported Interfaces

// Disclose all interfaces that this project exports.

Interface

Stability

Former Stability (if changing)

Comments

 Asupgrade CLI

Evolving 

AsupgradeGUI

Unstable

Upgrade.log

Evolving

4.5.2 Imported interfaces

// Disclose interfaces this project imports.

Interface

Stability

Exporting Project: Name, Specification or other Link.

Comments

 Asadmin CLI commands

 Unstable

 http://www.glassfishwiki.org/gfwiki/attach/GlassFishV2AdminRelatedOnePagers/cli-one-pager.html

SUNtls

Stable

WSARC/2002/366 NSS: Network Security Services

SUNtlsu

Stable

WSARC/2002/511 NSS: Network Security Services Command Line Utilities

4.5.3 Other interfaces (Optional)

// Any private interfaces that may be of interest?

Interface

Stability

Exporting Project: Name, Specification or other Link.

Comments

 Domain-passwords

Unstable 

This project 

4.6. Doc Impact

Upgrade Manual

4.7. Admin/Config Impact

To support the inline upgrade , asadmin CLI needs to make a call to the asupgrade utility.

4.8. HA Impact

None

4.9. I18N/L10N Impactinks

None

4.10. Packaging & Delivery

SUNasut

4.11. Security Impact

No

4.12. Compatibility Impact

None

4.13. Dependencies

1. Admin CLI

2. sun-domain-1_3.dtd

5. Reference Documents

Upgrade Tool Functional Specification SJSAS 8.2pe/ee

Admin Infrastructure Functional Specification

http://www.glassfishwiki.org/gfwiki/attach/GlassFishV2AdminRelatedOnePagers/admin-fs.html

Profile Support Functional Specification

http://www.glassfishwiki.org/gfwiki/attach/GlassFishV2AdminRelatedOnePagers/profile-support-fs.html

6. Schedule

6.1. Projected Availability

Q1 CY2007