How Upgrade of Developer Domain is Done

Requirements of Sorts

See Some write-up

Issue 3003

Backend Implementation

• MBean ObjectName: com.sun.appserv:type=domain,category=config
• MBean Java Class: /glassfish/admin/mbeans/src/java/com/sun/enterprise/admin/mbeans/DomainMBean.java

There were several approaches:

Transform the domain.xml using templates:

This implies that we register the operation and don't do anything about it. Upon restarting the
domain, the startup sequence identifies that this is a case of upgrade and then transforms the
domain. This has some side-effects in that the startup logic gets impacted. We currently already support the in-place upgrade and addon configuration. The transformation templates also need to
written in such a way that it preserves the current configuration of the admin server and hence
this is a cumbersome approach.

Transform the config context in memory using domain.xml template:

This leverages the fact that the basic difference between domain.xml of a domain that supports clusters and the one that does not is the "default-config" – a config that acts as a template configuration of the non-admin-server instances. Moreover, if we modify the domain.xml in-place like any other admin
operation, it makes the implementation logic easier.

This approach has been chosen. Following are the details:

1. The name of the profile is accepted. For GlassFish V2, it has to be "cluster".
2. The domain.xml template for the given profile is looked for. Note that this is the template that is generated during the build time and is packaged in the product along with all the profiles. For example, for "cluster" profile, the domain.xml is always found at install-dir/lib/install/templates/cluster/domain.xml. It is made sure that this is the right domain.xml template (i.e. it contains the "default-config"). The good thing about this is that this domain.xml is already transformed.
3. From this domain.xml a temporary config context is formed.
4. From the temporary config context, the config object corresponding to default-config is extracted and is cloned.
5. The cloned default-config is modified to support clusters and an additional token replacement is done (e.g. the property named client-hostname should exist and should have a value that denotes the host name of the machine).
6. The Domain Admin Server's configuration is modified to change the pluggable feature factory and MBeanServer Builder.

API to Call (for admin console)

Note: Don't hard-code the ObjectName in client code.

Information Admin Console Should Display

Console should make the operation intuitive. Following should be evident:

• The server configuration is being changed.
• The server will now support management of standalone server instances and instance clusters.
• The template configuration for server instances is picked from given profile (cluster).
• All the applications deployed on the server will continue to work.
• The current (single instance) server will assume the role of Domain Administration Server
  which itself can host user applications.
• By default, in-memory replication will be used for applications that are required to be available.
• With every server instance, a local JMS broker will be provided.
• The name of configuration used as a template by server instances and clusters is named default-config.
• The changes will be effective only on server restart.
• Since the domain now supports clusters, the start-domain command will take longer to start up.
• After the operation is completed successfully, redirect the user to restart domain page. That way, we make it explicit that restart is required.
• We should also suggest to users that they enhance the JVM configuration (heap-size etc.) of the admin server now that it supports clusters.
• Only domain.xml is modified by this operation. So, administrators can be directed to take a backup of that file in case something goes wrong.

It is better to make users confirm their decision.