Package org.glassfish.api.admin

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.

Interface Summary

Interface	Description
AdminCommand	This is an admin command interface, command implementations have to be stateless and should also have a org.jvnet.hk2.component.Scope value of PerLookup
AdminCommandContext	Useful services for administrative commands implementation
AdminCommandEventBroker<T>	Events broker for AdminCommands.
AdminCommandEventBroker.AdminCommandListener<T>	Listener for AdminCommand events.
AdminCommandEventBroker.EventBrokerUtils	Place relevant for utility methods
AdminCommandSecurity
AdminCommandSecurity.AccessCheckProvider	Behavior required of all command classes which provide any of their own custom authorization enforcement.
AdminCommandSecurity.Preauthorization
AdminCommandState
AuthorizationPreprocessor	Defines the API for services which provide additional information to be used during authorization.
ClusterExecutor	A ClusterExecutor is responsible for remotely executing commands.
CommandAspectFacade	This is an extensible facade class to support options which can be passed from the client to server and uses the CommandAspects
CommandAspectImpl<T extends Annotation>	Interface for defining aspects for AdminCommands.
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.
CommandProgress	Base interface of progress status implementation.
CommandProgressRegistry
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
Job	Represents running (or finished) command instance.
JobCreator	This is the contract responsible for creating Job
JobLocator	This is a contract which is used to locate all the jobs.xml files on server startup
JobManager	This is the contract for the JobManagerService The JobManager will be responsible for 1.
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.
PasswordAliasResolver	Resolves password alias expressions of the form ${ALIAS=aliasName} using an internal password alias store while also accepting passwords themselves which are not translated.
PasswordAliasStore	Represents a fully-functional password alias store.
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.
ProgressProvider	Interface denoting administrative commands that provide their Progress annotation.
ProgressStatus	API for providing information about work progress in AdminCommand implementations.
SelfAuthorizer	Represents the ability (and responsibility) of an AdminCommand implementation to provide its own authorization logic, instead of relying on the command framework and the AccessRequired annotation to do so.
ServerEnvironment	Allow access to the environment under which GlassFish operates.
SupplementalCommandExecutor	An executor responsible for executing supplemental commands registered for a main command
SupplementalCommandExecutor.SupplementalCommand

Class Summary

Class	Description
AccessRequired.AccessCheck<T>	Represents an authorization check: a resource and an action to be authorized on that resource.
AccessRequired.Util	Utility methods used both from AccessCheck and from CommandSecurityChecker.
AdminCommandContextForInstance	Most of AdminCommandContext attributes are used in any phase of command execution (supplemental commands, replication) but some of them must be different for every instance.
AdminCommandContextImpl	Useful services for administrative commands implementation
AdminCommandEventBroker.BrokerListenerRegEvent
AdminCommandLock	The implementation of the admin command lock.
CommandAspectBase<T extends Annotation>	Empty implementation of CommandAspectImpl.
CommandModel	Model for an administrative command
CommandModel.ParamModel	Model for a command parameter.
CommandSupport	Utility class for command framework.
InstanceCommandResult
InstanceState	This holds the late status of the instance, the commands that are Queued up while the instance was starting etc.
JobManager.Checkpoint	Container for checkpoint related objects
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.
ProgressProvider.Utils
TargetBasedExecutor	Convenience implementation that delegate to a provided system executor.
WrappedAdminCommand	Represents command wrapped with CommandWrapperImpl.

Enum Summary

Enum	Description
AdminCommandLock.SuspendStatus	The status of a suspend command attempt.
AdminCommandState.State
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.
RestEndpoint.OpType
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

Exception	Description
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

Annotation Type	Description
AccessRequired	Allows command developers to declare what resources are affected by the command and what actions must be authorized on each to allow the command to execute.
AccessRequired.Delegate
AccessRequired.List	Declares multiple class-level @AccessRequired authorization steps, typically each identifying different resources and/or different actions
AccessRequired.NewChild	Declares access control for creating a new child ConfigBean in a collection on an existing ConfigBean.
AccessRequired.NewChild.List	Declares multiple authorization checks for creating the same single new ConfigBean.
AccessRequired.To	Declares access control on an existing, non-null ConfigBean.
CommandAspect	A marker annotation for annotations that indicate that an AdminCommand functionality is to be extended in a certain way.
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.
ManagedJob	This annotation will be added for commands which need to be managed by Job Manager
NamedResource	Marks a POJO class, a field, or a method as a named resource.
NamedResource.Key
Progress	ProgressStatus of a command.
RestEndpoint
RestEndpoints
RestParam
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.