A supplemental command can be very useful to configure extra or external components * of an installation. For instance, a load-balancer module can be installed * when a load-balancer is added to a glassfish installation. Such module can contain * supplemental commands to supplement commands like "create-instance" in order to update * the load-balancer specific information. * *
An implementation must use the value() attribute of the @Supplemental annotation * to express the supplemented command. Its value is the name of the command as defined * by the supplemented command @Service annotation. * *
Example : take a command implementation *
*
* @Service(name="randomCommand")
* public MyRandomCommand implements AdminCommand {
* ...
* }
*
*
* a supplemental command may be defined as follows : *
*
* @Service(name="mySupCommand")
* @Supplemental("randomCommand")
* public MySupplementalCommand implements AdminCommand {
* ...
* }
*
*
* * Another implementation that does not use the same parameter names as the * supplemented command will need to use a @Bridge annotation *
*
* @Service(name="otherSupCommand")
* @Supplemental(value="randomCommand" bridge=MyParameterMapper.class)
* public OtherSupplementedCommand implements AdminCommand {
* ...
* }
*
*
* There can be several supplemental commands for a command implementation. * *
A supplemental command can be executed in "isolation" (not part of the supplemented * command execution) and should not make any assumption that it is called as part * of its supplemented command execution. If a command should not be invokable in * isolation, it must not define a name() attribute on the @Service annotation : *
*
* @Service
* @Supplemental("randomCommand")
* public MySupplementalCommand implements AdminCommand {
* // can only be invoked as a supplemental command
* }
*
*
* If a supplemental command is annotated with @Rollback, the annotation will be ignored * when the supplemental command is executed in isolation. * *
If a supplemental command is annotated with @Rollback, it is still subject to the * supplemented command {@link org.glassfish.api.admin.ExecuteOn#ifFailure()} value to decide * whether or not roll-backing should happen in case of failure. * *
When associating a supplemental command to a command X, it's always a good idea * to associate a roll-backing supplemental command to the rollbacking command of X. * For instance, if an "add-lb-config" supplemental command is attached to the * "create-instance" command, a "delete-lb-config" supplemental command should be * attached to the "delete-instance" command. * * @author Jerome Dochez * */ @Retention(RetentionPolicy.RUNTIME) @Contract @InhabitantAnnotation("default") public @interface Supplemental { /** * enumeration of when a supplemental command can be invoked with regards to the supplemented * command execution. */ public enum Timing {Before, After} /** * Name of the supplemented command as it can be looked up in the habitat. * * Therefore the supplemented command must have the {@link AdminCommand} type and the * provided registration name. * * @return habitat registration name for the command */ @InhabitantMetadata("target") public String value(); public Class bridge() default ParameterBridge.NoMapper.class; /** * Supplemental commands can be run before or after the supplemented command. * Returns when this supplemental command is expecting its execution. * * @return Before if it should be run before the supplemented method * or After if it should run after the supplemented method. */ public Timing on() default Timing.After; /** * Indicates to the framework what type of action should be taken if the * execution of this command was to return a failure exit code. * The action will apply on the supplemented command as well as all * supplemental commands. * *
If rollback is expected, the failure of this * supplemental command will cause the rollbacking of all the already * executed supplemented commands as well as the main supplemented command. * * @return the action the framework is expected to invoke when this * supplemental command execution failed. */ public FailurePolicy ifFailure() default FailurePolicy.Error; }