Package org.glassfish.api.admin
Admin commands in GlassFish
Basic Support
Commands are annotated withService
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 theSupplemental
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 withExecuteOn
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 theUndoableCommand
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 aorg.jvnet.hk2.component.Scope
value ofPerLookup
AdminCommandContext Useful services for administrative commands implementationAdminCommandEventBroker<T> Events broker for AdminCommands.AdminCommandEventBroker.AdminCommandListener<T> Listener for AdminCommand events.AdminCommandEventBroker.EventBrokerUtils Place relevant for utility methodsAdminCommandSecurity 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 CommandAspectsCommandAspectImpl<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 Interface for running commands on an instanceJob Represents running (or finished) command instance.JobCreator This is the contract responsible for creating JobJobLocator This is a contract which is used to locate all the jobs.xml files on server startupJobManager 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 theirProgress
annotation.ProgressStatus API for providing information about work progress inAdminCommand
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 commandSupplementalCommandExecutor.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 ofAdminCommandContext
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 implementationAdminCommandEventBroker.BrokerListenerRegEvent AdminCommandLock The implementation of the admin command lock.CommandAspectBase<T extends Annotation> Empty implementation of CommandAspectImpl.CommandModel Model for an administrative commandCommandModel.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 objectsParameterBridge.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 withCommandWrapperImpl
. -
Enum Summary Enum Description 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 Class for an exception that occurred while executing an asadmin commandCommandValidationException 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 actionsAccessRequired.NewChild Declares access control for creating a new childConfigBean
in a collection on an existingConfigBean
.AccessRequired.NewChild.List Declares multiple authorization checks for creating the same single newConfigBean
.AccessRequired.To Declares access control on an existing, non-nullConfigBean
.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 ManagerNamedResource 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 @RestRedirectSupplemental 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.