Making asadmin Subcommands Cluster-Aware

The GlassFish Server asadmin command framework provides support for making asadmin subcommands work properly in a clustered environment or with standalone server instances. A command that changes a configuration is first executed on the domain administration server (DAS) and then executed on each of the server instances affected by the change. Annotations provided by the framework determine the instances on which the command should be replicated and executed. Commands that do not change a configuration need not be executed on the DAS at all, but only on the necessary instances. The framework provides support for collecting the output from the instances and sending a report back to the user.

Subcommands in a multi-instance environment can accept a --target option to specify the cluster or instance on which the command acts. From within the command, the Target utility allows the command to determine information about where it is running. For some commands, it may be desirable to have a main command that runs on the DAS and supplemental preprocessing or postprocessing commands that run on the instances.

The following topics are addressed here:

• Specifying Allowed Targets

• The Target Utility

• Specifying asadmin Subcommand Execution

• Subcommand Preprocessing and Postprocessing

• Running a Command from Another Command

Specifying Allowed Targets

When you define a --target option by using the @Param annotation in the org.glassfish.api package, possible targets are as follows:

• domain — The entire domain

• server — The domain administration server, or DAS

• cluster — A homogeneous set of server instances that function as a unit

• standalone instance — A server instance that isn't part of a cluster

• clustered instance — A server instance that is part of a cluster

• config — A configuration for a cluster or standalone server instance

These possible targets are represented by the following CommandTarget elements of the @TargetType annotation in the org.glassfish.config.support package:

• CommandTarget.DOMAIN

• CommandTarget.DAS

• CommandTarget.CLUSTER

• CommandTarget.STANDALONE_SERVER

• CommandTarget.CLUSTERED_INSTANCE

• CommandTarget.CONFIG

By default, the allowed targets are server (the DAS), standalone server instances, clusters, and configurations. Not specifying a @TargetType annotation is equivalent to specifying the following @TargetType annotation:

@TargetType(CommandTarget.DAS,CommandTarget.STANDALONE_SERVER,CommandTarget.CLUSTER,CommandTarget.CONFIG)

Subcommands that support other combinations of targets must specify @TargetType annotations. For example, the create-http-lb subcommand supports only standalone server instance and cluster targets. Its @TargetType annotation is as follows:

@TargetType(CommandTarget.STANDALONE_SERVER,CommandTarget.CLUSTER)

Most subcommands do not act on server instances that are part of a cluster. This ensures that all server instances in a cluster remain synchronized. Thus, the CommandTarget.CLUSTERED_INSTANCE element of the @TargetType annotation is rarely used.

An example exception is the enable subcommand. To perform a rolling upgrade of an application deployed to a cluster, you must be able to enable the new application (which automatically disables the old) on one clustered instance at a time. The @TargetType annotation for the enable subcommand is as follows, all on one line:

@TargetType(CommandTarget.DAS,CommandTarget.STANDALONE_INSTANCE,CommandTarget.CLUSTER,
CommandTarget.CLUSTERED_INSTANCE)

Note that the CommandTarget.CLUSTERED_INSTANCE element is specified.

The target name specified in the command line is injected into the subcommand implementation if the following annotation is present:

@Param(optional=true,defaultValue=SystemPropertyConstants.DEFAULT_SERVER_INSTANCE_NAME)
    String target;

The Target Utility

The Target utility is a service, present in the internal-api module, org.glassfish.internal.api package, which a command implementation can obtain by using the following annotation:

@Inject Target targetUtil;

You can use this utility to avoid writing boiler plate code for actions such as getting the list of server instances for a cluster or checking if a server instance is part of a cluster. For example, here is an example of using the utility to obtain the configuration for a target cluster or server instance:

Config c = targetUtil.getConfig(target);

The Target utility is packaged in the as-install/modules/internal-api.jar file. Its methods are documented with comments.

Specifying asadmin Subcommand Execution

By default, all asadmin subcommands are automatically replicated and run on the DAS and all GlassFish Server instances specified in the --target option. To run a subcommand only on the DAS, use the following @ExecuteOn annotation in the org.glassfish.api.admin package:

@ExecuteOn(RuntimeType.DAS)

The stop-domain subcommand and subcommands that list information are examples of subcommands that execute only on the DAS.

To run a subcommand only on applicable server instances, use the following @ExecuteOn annotation:

@ExecuteOn(RuntimeType.INSTANCE)

Not specifying an @ExecuteOn annotation is equivalent to specifying the following @ExecuteOn annotation:

@ExecuteOn(RuntimeType.DAS,RuntimeType.INSTANCE)

In addition to RuntimeType, you can specify the following additional elements with the @ExecuteOn annotation:

• ifFailure — By default, if errors occur during execution of a subcommand on a server instance, command execution is considered to have failed and further execution is stopped. However, you can choose to ignore the failure or warn the user rather than stopping further command execution. Specify the ifFailure element and set it to FailurePolicy.Ignore or FailurePolicy.Warn. For example:

  @ExecuteOn(value={RuntimeType.DAS}, ifFailure=FailurePolicy.Warn)

• ifOffline — By default, if a server instance is found to be offline during the command replication process, command execution is considered to have failed and further execution is stopped. However, you can choose to ignore the failure or warn the user rather than stopping further command execution. Specify the ifOffline element and set it to FailurePolicy.Ignore or FailurePolicy.Warn. For example:

  @ExecuteOn(value={RuntimeType.DAS}, ifOffline=FailurePolicy.Ignore)

Subcommand Preprocessing and Postprocessing

Some asadmin subcommands may require preprocessing or postprocessing. For example, after an application is deployed to the DAS, references are created in all applicable server instances, which synchronize with the DAS. As another example, Message Queue or load balancer settings may have to be reconfigured whenever a server instance is added to a cluster.

For such cases, the command replication framework provides the @Supplemental annotation (in the org.glassfish.api.admin package). An implementation must use the value element of the @Supplemental annotation to express the supplemented command. This value is the name of the command as defined by the supplemented command's @Service annotation (in the org.jvnet.hk2.annotations package).

For example, the deploy subcommand requires postprocessing. The deployment command implementation looks like this:

@Service(name="deploy")
@ExecuteOn(RuntimeType.DAS)
public DeployCommand implements AdminCommand {
//Do Actual Deployment
}

A supplemental command that is run after every successful deployment looks like this:

@Service(name="DeploymentSupplementalCommand")
@Supplemental("deploy")
@ExecuteOn(RuntimeType.INSTANCE)
public DeploymentSupplementalCommand implements AdminCommand {
//Do logic that happens after deployment has been done
}

As another example, a subcommand to create a local server instance might look like this:

@Service(name = "create-local-instance")
@Scoped(PerLookup.class)
public final class CreateLocalInstanceCommand implements AdminCommand {
//Do local instance creation
}

A supplemental command to change Message Queue or load balancer settings after local instance creation might look like this:

@Service(name="CreateLocalInstanceSupplementalCommand")
@Supplemental("create-local-instance")
public CreateLocalInstanceSupplementalCommand implements AdminCommand {
//Change MQ/LB properties here
}

A supplemental command implements AdminCommand, thus it can use the @Param annotation and expect the corresponding asadmin command parameters to be injected at runtime. The parameter values available for injection are the same ones provided for the original command with which the supplemental command is associated. For example, the DeploymentSupplementalCommand has access to the parameter values available to the DeployCommand invocation.

An asadmin subcommand can be supplemented with multiple supplemental commands. In this case, all supplemental commands are run after completion of the main command but without any guarantee of the order in which they run.

To specify that a supplemental command is run before the main command, set the on element of the @Supplemental annotation to Supplemental.Timing.Before. For example:

@Supplemental(value="mycommand", on=Supplemental.Timing.Before)

Supplemental commands can use the @ExecuteOn annotation as described in Specifying asadmin Subcommand Execution.

Running a Command from Another Command

An asadmin subcommand or supplemental command might need to run another subcommand. For example, a subcommand running on the DAS might need to run a different subcommand on one or more server instances. Such invocations might use the ClusterExecutor class (in the org.glassfish.api.admin package), which accepts a ParameterMap, to pass parameters and their values to the invoked command.

The ParameterMapExtractor utility is a service, present in the common-util module, org.glassfish.common.util.admin package, which creates a new ParameterMap populated using the parameters and values of another AdminCommand that has already been injected.

To list parameter names you want excluded from the ParameterMap, pass the following:

Set<String>

This is optional.