Package org.glassfish.api.admin

Admin commands in GlassFish

See:
Description

Interface Summary

AdminCommand	This is an admin command interface, command implementations have to be stateless and should also have a Scope value of PerLookup
ClusterExecutor	A ClusterExecutor is responsible for remotely executing commands.
CommandModelProvider	Interface denoting administrative commands that provide their model.
CommandParameters	A marker interface to indicate classes that are used to pass parameters to the parameters method of the CommandRunner.CommandInvocation API.
CommandRunner	CommandRunner is a service that allows you to run administrative commands.
CommandRunner.CommandInvocation	CommandInvocation defines a command excecution context like the requested name of the command to execute, the parameters of the command, etc...
FileMonitoring	Service to monitor changes to files.
FileMonitoring.FileChangeListener
InstanceCommand
ParameterBridge	A parameter mapper acts as a bridge between supplied parameters (by the user on the command line for instance) and expected parameters by a action.
Payload	Interface for admin command payloads--data carried in the http request and response which flow between the admin client and the server.
Payload.Inbound	Public API for inbound payloads.
Payload.Outbound	Public API for outbound Payloads.
Payload.Part	Public API for the payload Part.
ServerEnvironment	Allow access to the environment under which GlassFish operates.
SupplementalCommandExecutor	An executor responsible for executing suplemental commands registered for a main command

Class Summary

AdminCommandContext	Useful services for administrative commands implementation
AdminCommandLock	The implementation of the admin command lock.
CommandModel	Model for an administrative command
CommandModel.ParamModel	Model for a command parameter.
ExecuteOn.TargetBasedExecutor	Convenience implementation that delegate to a provided system executor.
InstanceCommandResult
InstanceState	This holds the late status of the instance, the commands that are Queued up while the instance was starting etc.
ParameterBridge.NoMapper	Provided mapper that does not change parameters names or values from the input set.
ParameterMap	A map from parameter name to a list of parameter values.
ProcessEnvironment	Process environment allow access to information related to the execution or process.

Enum Summary

AdminCommandLock.SuspendStatus	The status of a suspend command attempt.
CommandLock.LockType	The type of command lock.
FailurePolicy	Defines the expected behaviour from the system when a supplemental command (could be a local or remote invocation) fails to execute properly.
InstanceState.StateType
ProcessEnvironment.ProcessType	Enumeration of the supported process types Server is the application server ACC is the application client Other is a standalone java.
RestRedirect.OpType
RuntimeType	Defines a server process type.
ServerEnvironment.Status
Supplemental.Timing	enumeration of when a supplemental command can be invoked with regards to the supplemented command execution.

Exception Summary

AdminCommandLockException	The AdminCommandLockException is generated when a command can not acquire an AdminCommandLock.
AdminCommandLockTimeoutException	The AdminCommandLockTimeoutException is generated when a command can not acquire an AdminCommandLock within the allotted time.
AuthenticationException	A specialized CommandException that indicates an authentication failure.
CommandException
CommandValidationException
InvalidCommandException
SSHCommandExecutionException	Created by IntelliJ IDEA.

Annotation Types Summary

CommandLock	Annotation used to indicate what type of lock to acquire before executing an admin command.
ExecuteOn	Annotation to qualify when an action like a command is targeted to be run on a cluster or a set of instances.
IfFailure	Annotation used to indicate what type of failure action should be performed if the annotated method was to return a failure error code or throw an exception.
RestRedirect	annotation to redirect a rest request from CRUD operations on the configuration tree to a command invocation (like deploy, undeploy).
RestRedirects	List of @RestRedirect
Supplemental	Annotation to define a supplemental command A supplemental command runs when a main command implementation is ran, it can be used to attach behaviours to existing commands without modifying the original implementation.

Package org.glassfish.api.admin Description

Admin commands in GlassFish

Basic Support

Commands are annotated with Service annotation and must implement the AdminCommand contract. Commands are looked up based on the @Service Service.name() attribute.

Commands can be singleton or instantiated at each invocation depending on the org.jvnet.hk2.annotations.Scope annotation. Singleton commands will be injected once for all Inject dependencies but will have all @{link org.glassfish.api.admin.Param} dependencies injected for each invocation.

more to be added to describe the v3 behaviors.

Supplemental Commands

A supplemental command is an administrative command that will supplement the execution of an existing command. Although most supplemental commands can execute in isolation, they usually represent added administrative tasks that can be optionally installed inside a GlassFish installation and need to be notified when higher level administrative requests are invoked. A supplemental command must be annotated with the Supplemental annotation.

For instance, a supplemental command might configure a particular load-balancer when instances are created or deleted within a cluster. Usually, this required complicated scripts to first create the instance and then invoke some subsequent commands to configure the load-balancer. With supplemental commands, the load-balancer supplemental command can attach itself to the create or delete instance methods and be automatically invoked by the administration framework when the supplemented command is invoked by the user.

A supplemental command usually run after the supplemented command has finished running successfully. If the supplemented command fail to execute, none of the supplemental commands should be invoked. A supplemental command can request to be invoked before the supplemented command. In such a case, these commands must have a UndoableCommand annotation to undo any changes in case the supplemented command fail to execute successfully. If a supplemental command is executing before and does not have Rollbak annotation, the system should flag this as an error, and prevent the supplemental method execution.

It might be possible for a supplemental command to fail executing and since such commands execute usually after the supplemented command has finished executing, a rollbacking mechanism can be described though the combination of the ExecuteOn.ifFailure() annotation value and the UndoableCommand}. If a clustered command requires rollbacking when any of its supplemented command fail then it must be annotated with UndoableCommand and all of its supplemented commands must also be annotated with UndoableCommand, otherwise, it must be flagged by the system as an error.

Supplemental commands can be a wrapper for existing external commands, and therefore can use a very different set of parameters than the ones provided to the supplemented command. Supplemental commands can use Supplemental.bridge() annotation value to translate or bridge the parameters names and values from the supplemented command to the supplemental ones.

Clustering support

A command can be optionally annotated with ExecuteOn to specify the clustering support. A command not annotated with ExecuteOn will have a virtual @ExecuteOn annotation with the default values. (note to asarch, this is mainly for backward compatibility, can be revisited).

A Clustered command will be executed on the server receiving the command from the user (the DAS usually) and any of the remote instances identified by the ExecuteOn.executor() instance.

For a command to not be "cluster" available requires the following annotation :

 @ExecuteOn(RuntimeType.DAS)
 

Whether commands are executed in parallel or synchronously is immaterial to the user as long as he gets proper feedback on the remote commands executions successes or failures.

Rollbacking

Supplemental and clustered commands execute separately and can create issues when one of the invocation fails. Commands can optionally implement the UndoableCommand interface to allow for roll-backing a previously successful execution of an administrative change.

In a clustering environment, any of the remote invocations can rollback the entire set of changes depending on the values of ExecuteOn.ifFailure() and ExecuteOn.ifOffline() annotation values.

A Supplemental command can force the roll-backing of the supplemented command using the Supplemental.ifFailure() annotation value.