The Upgrade Tool, which is bundled with Oracle GlassFish Server 3.0.1 (GlassFish Server 3.0.1), replicates the configuration of a previously installed server in the target installation. The Upgrade Tool assists in upgrading the configuration and applications from an earlier version of the Application Server or GlassFish Server to GlassFish Server 3.0.1. To view a list of the older versions from which you can upgrade, see Supported Releases For Upgrade to GlassFish Server 3.0.1.
The following topics are addressed here:
The Upgrade Tool is different from the Update Tool, which allows you to add or update components of GlassFish Server 3.0.1. For more information about the Update Tool, see Update Tool in Oracle GlassFish Server 3.0.1 Administration Guide.
The subsections that follow provide information that you will need when you perform an upgrade.
Upgrade to GlassFish Server 3.0.1 from the following earlier releases of the software is supported:
Sun Java System Application Server 9.1 Update 2 (Developer Profile)
Sun GlassFishTM Enterprise Server v2 Update 2 (Developer Profile)
Sun GlassFish Enterprise Server v2.1 (Developer Profile)
Sun GlassFish Enterprise Server v2.1.1 (Developer Profile)
Sun GlassFish Enterprise Server v3 Prelude
GlassFish Server 3.0.1 does not support clustering. Therefore, upgrading from the Enterprise Profile is not supported.
Because the differences between GlassFish Server 3.0.1 and Sun GlassFish Enterprise Server v3 do not affect applications and data, upgrade from Sun GlassFish Enterprise Server v3 is not required.
You can use the tool through the command-line interface (CLI) or the GUI.
To use the Upgrade Tool in GUI mode, issue the asupgrade command with no options. See To Upgrade by Using the Upgrade Tool Wizard for details.
To run the Upgrade Tool in CLI mode, invoke the asupgrade command with the -c/--console option. See To Upgrade From the Command Line for more details.
The following are important terms related to the upgrade process.
The directory of the server domain from which you are upgrading to the new version (for example, c:\glassfish\domains\domain1).
The directory where domains are created on the server to which you are upgrading (for example, c:\glassfishv3\glassfish\domains).
The SSL certificate database password used in operations such as GlassFish Server startup. This term refers to the master password of the installation from which you want to upgrade. You need to specify this password if you have changed it from the default value of changeit.
The Upgrade Tool migrates the configuration and deployed applications from an earlier version of Sun Java System Application Server or Sun GlassFishEnterprise Server to the current version. The Upgrade Tool does not upgrade the binaries of the server. The installer is responsible for upgrading the binaries. Database migrations or conversions are also beyond the scope of this upgrade process.
Before starting the upgrade process, make sure that you stop all domains in the source server (the server from which you are upgrading) and the target server (the server to which you are upgrading).
Application archives (EAR files) and component archives (JAR, WAR, and RAR files) that are deployed in the source server do not require any modification to run on Oracle GlassFish Server 3.0.1. Components that may have incompatibilities are deployed on GlassFish Server 3.0.1 with the compatibility property set to v2 and will run without change on GlassFish Server 3.0.1. You may, however, want to consider modifying the applications to conform to Java EE 6 requirements.
The Java EE 6 platform specification imposes stricter requirements than Java EE 5 did on which JAR files can be visible to various modules within an EAR file. In particular, application clients must not have access to EJB JAR files or other JAR files in the EAR file unless they use a Class-Path header in the manifest file, or unless references use the standard Java SE mechanisms (extensions, for example), or use the Java EE library-directory mechanism. Setting this property to v2 removes these Java EE 6 restrictions.
Applications and components that are deployed in the source server are deployed on the target server during the upgrade. Applications that do not deploy successfully on the target server must be deployed manually on the target server by the user.
If a domain contains information about a deployed application and the installed application components do not agree with the configuration information, the configuration is migrated as is without any attempt to reconfigure the incorrect configurations.
An upgrade log records the upgrade activity. The upgrade log file is named upgrade.log and is created in the working directory from which the Upgrade Tool is run. Additional information is recorded in the server log of the upgraded domain.
When you use the Upgrade Tool, the source server and the target server are normally installed on the same machine, but under different install locations. Both server file systems must be accessible from the system on which you perform the upgrade.
The Upgrade Tool upgrades your server configuration and deployed applications.
To perform the upgrade, the user who runs the upgrade needs to have read permissions for the source and target directories and write permission for the target directory.
Ensure that you have stopped all domains in the source server before you start the upgrade process.
There are two ways to upgrade your server installation:
To run Upgrade Tool in command-line mode, use the -c option. You can run the upgrade tool in command-line mode using the following syntax:
asupgrade [--console] [--version] [--help] [--source source-path] [--target target-path] [--passwordfile password-file]
Table 2–1 describes the command options in greater detail, including the short form, the long form, and a description.
Table 2–1 asupgrade Utility Command Options
Short Form |
Long Form |
Description |
---|---|---|
-c |
--console |
Launches the upgrade command line utility. |
-V |
--version |
The version of the GlassFish Server. |
-h |
--help |
Displays the arguments for launching the upgrade utility. |
-s source-path |
--source source-path |
The installation directory of the older server installation. |
-t target-path |
--target target-path |
The domains directory of the GlassFish Server 3.0.1 installation. |
-f password-file |
--passwordfile password-file |
The file containing the administration password and the master password. |
The following example shows how to use the asupgrade command-line utility to upgrade an existing Sun GlassFish Enterprise Server v2.1 installation to GlassFish Server 3.0.1.
asupgrade -c --source /home/glassfish/domains/domain1 --target /home/glassfishv3/glassfish/domains |
If you invoke the tool only with the -c/--console option, the tool enters the interactive CLI mode, where you are asked to supply the needed options.
After you issue the asupgrade command, the tool informs you that domain1 already exists in the target directory and asks if you would like to rename it. If you type y, the directory is renamed domain1.original. If domain1.original already exists, the directory is named domain1.original.0.
Start the wizard as follows.
In the Source Domain Directory field, type the domain directory of the existing installation from which to import the configuration, or click Browse.
For example, you might type c:\glassfish\domains\domain1.
In the Target Domains Root Directory field, type the location of the GlassFish Server 3.0.1 installation to which to transfer the configuration, or click Browse.
The default is the full path name of the domains directory of your GlassFish Server 3.0.1 installation (for example, c:\glassfishv3\glassfish\domains).
(Optional) Provide the master password of the source application server.
The domain will be upgraded using these credentials.
Click Next.
A dialog box informs you that domain1 already exists in the target directory and asks if you would like to rename it. If you click OK, the directory is renamed domain1.original. If domain1.original already exists, the directory is named domain1.original.0.
The Upgrade Results page displays the status of the upgrade operation.
Click Finish to exit the Upgrade Tool when the upgrade process is complete.
After you complete the upgrade, start the GlassFish Server using the asadmin start-domain command. Log in to the Administration Console with the user name and password you used in the older server.
To register your installation of GlassFish Server from the Administration Console, select the Registration node. For step-by-step instructions on the registration process, click the Help button on the Administration Console.
Visit the URL http://localhost:8080 to view the domain-dir/docroot/index.html file. This file is brought over during the upgrade. You may want to copy the default GlassFish Server 3.0.1 file from the domain1.original/docroot directory and customize it for your GlassFish Server 3.0.1 installation.