Monday Jul 18, 2011

The GlassFish Upgrade Tool: End of the Line

In the 2.X timeframe of GlassFish, there was an upgrade tool that would transform your existing configuration information and move you to a newer version of GlassFish. This tool did all the work of mapping one version's configuration information to another.

Starting with GlassFish v3, the application server became modular, and components became responsible for their own part of the configuration upgrade. See the upgrade one pager for more details on how configuration upgrades work.

With the real work of the upgrade happening in the application server itself, the job of the upgrade tool became smaller and smaller until it now does the following:

  1. Copies the source domain to the target app server.
  2. Runs asadmin start-domain --upgrade.

When the steps are that simple, there isn't much value in having the tool. If you read the Oracle GlassFish Server 3.1 Upgrade Guide, you'll see that there are several upgrade uses cases that do not involve the upgrade tool at all. One example is an in-place upgrade using the update center.

For this reason, and to avoid confusion between the upgrade tool and update center, we'll be removing the upgrade tool from versions of GlassFish after 3.1.X. Upgrades should still be a simple affair. After all, the tool is just doing a copy and starting the server. If it can, you can.

Monday Feb 28, 2011

Moving On Up: Upgrading to GlassFish 3.1

GlassFish 3.1 is here, and once you're done playing around with it, it might be time to do some work. If you already have an earlier GlassFish installation working for you, this blog will walk you through the steps to upgrade it to GlassFish 3.1. Specifically, I'm going to upgrade a v2.1.1 installation with a two-instance cluster.

If you're upgrading from a v2 developer profile or a 3.0.1 installation, then the upgrade process is mostly the same. You're just done after the upgrade tool exits, since you won't have cluster instances to recreate. If you're upgrading from a v2 enterprise edition installation, then please see the Upgrade Guide for more information. The upgrade process is the same, but there are some manual steps you will need to perform because GlassFish 3.1 does not support NSS.

All of the steps in this example are included in this video, and I'll describe them below:

Step 1: Upgrade the DAS

First, make sure the DAS, node agent, and instances are all stopped. If you have any 3rd-party libraries installed in glassfish/lib (not domainX/lib), you'll need to copy those over to the 3.1 installation. Then you can use the upgrade tool located in the bin directory: bin/asadmin/asupgrade. While you don't need to give it any options, the following are the most useful (use --help for the full list):

  • -c or --console This will start the tool in console mode instead of GUI mode.
  • -s or --source This will specify the source domain to be upgraded.
  • -t or --target This will specify the target domains directory into which the source domain will be copied. This is only really needed when using the console mode. In the GUI mode, it is filled in for you.

When we say "upgrading the DAS," what you're really doing is upgrading the domain that is running in the DAS. This process hasn't really changed since GlassFish v3. Later, this information will be synchronized with the cluster instances. What the upgrade tool does for you is copy the old domain to the 3.1 server, and then it runs asadmin start-domain --upgrade <domain_name> to upgrade the configuration in the domain. Just like with GlassFish v3, the server itself performs the upgrade duties.

Step 2: Recreate the Cluster Instances

Because the cluster information is stored in domain.xml, we don't have to do any other steps to create the 3.1 cluster. However, we need to recreate the instances. I'm using the asadmin create-local-instance command to create my instances. See Jennifer's blog for more information on the command.

In the video, I specify the --node and --cluster options when creating the instances. These values, along with the instance name, match the node agent, cluster name, and instance names that were used in the v2 cluster. When the cluster is started, all of the configuration and application data in the DAS will be synchronized with the instances. The original instances do not store any per-instance data (with one exception below), so there is no separate "upgrade instances" step.

The one extra step you need before starting up the cluster is to copy the IMQ directories from the old instances to the newly-created ones. This persistent JMS information is not part of the domain configuration, and you don't want to lose it during the upgrade process. For instance, copy the directory:




Then you're ready to start everything up with asadmin start-cluster <cluster_name> and the upgrade of your cluster is complete. Please see the upgrade guide linked above for full information. Happy upgrading!


Whatever part of GlassFish or the Java EE world that catches my attention. (Also, go Red Sox.)


« June 2016