Command succeeded, continue chain

Successful command execution with continued chain is signaled by:

• The execute(..) method returns false.

If the command resides in a chain then returning false signals that execution should continue on the next command in the chain. If no command returns true, before reaching the end of the command sequence, the chain is assumed to have completed normally.

Command succeeded, discontinue chain

Successful command execution with discontinued chain is signaled by:

• The execute(..) method returns true.

If the command resides in a chain then returning true signals that execution shouldn't continue on the next command in the chain. A command should return true if the chain has completely handled the process. This notion is the basis of the Chain of Responsibility. Processing is handed off from command to command, until a command handles the command.

Command failed

Failed command execution is signaled by:

• A command throws a com.alpha.pineapple.command.CommandException.

A chain ends abnormally when any exception is thrown by a command. With Commons Chain, if a command throws an exception, the chain is broken. The exception, be it a runtime exception or application exception, will bubble up to the original caller of the chain.

Initialization by inheritance

This hasn't been designed yet. Until then, please use delegation.

Initialization by delegation

Example of how to implement initialization in a command:

public class SomeCommand {
        
    // Context key
    public static final String CONTEXT_KEY = "my-key";

    // Definition of some field.
    @Initialize( CONTEXT_KEY )
    String someField;
                                                
        public boolean execute(Context context) throws Exception
        {

                // initialize command 
                CommandInitializer initializer =  new CommandInitializerImpl();
                initializer.initialize(context, this);

                // remaining command execution here....
                ...      
        }
                        
}

The example consists of three parts:

• Definition of key CONTEXT_KEY which defines key in the context which contains a value in context.
• Definition of annotated field someField to whom the context value is mapped.
• Execution of CommandInitializer.initialize(..) to do the initialization.

How to implement automatic command initialization

Add these three elements to a command class:

1. Definition of annotated fields which should be initialized with value from the context. A field is annotated with @Initialize( <key> ). Where <key> is an String constant which is expected by the command to be defined in the context at runtime.
2. Definition of content keys for the values which should be mapped into command fields. Please notice that the initialization can map value from any context key.
3. Add execution of CommandInitializer.initialize(..) to the beginning of the execute(..) method body to trigger the initialization.

Failing initialization

If an expected context key-value pairs isn't found then a com.alpha.pineapple.command.initialization.CommandInitializationFailedException is thrown and command initialization is aborted.

Value conversion during field initialization

The strategy for conversion of values used during field initialization, depends on the type and value of the source key in the context and the type of the target field:

The benefits of using automatic command initialization

The benefits are:

• Removes the need for wiring code which map values from context into command fields.
• Removes the need to type cast context values to field types.
• Context values can be supplied as String and be automatically converted to the type declared by a field.
• Command execution fails if expected context keys isn't defined in the context at runtime, i.e. the the annotated fields serves to define the precondition for execution of a command.

Failing validation

If an illegal value is found in the context then a com.alpha.pineapple.command.initialization.CommandInitializationFailedException is thrown and command initialization is aborted.

Supported validation policies

Two validation policies is defined:

• Not Null - validates that the value isn't null.
• Not Empty - validates that the content of validated object isn't null and empty. The semantics of depends on the type of the validated object. The "not empty" validation is supported for these types:
  • java.lang.String
  • java.util.Map
  • java.util.Collection
  • java.lang.Object[]

Implementation is based on org.apache.commons.lang.Validate

The validation of the policies is implemented using org.apache.commons.lang.Validate so the validation of the supported types corresponds to the behavior that class:

The not-empty policy for java.lang.String fails if:

• The object is null.
• The length of the string is zero.

The not-empty policy for java.util.Map and java.util.Collection fails if:

• The object is null.
• The size of the collection / map is zero.

The not-empty policy for java.lang.File fails if:

• The object is null.
• The length of the parent and child is zero.
• The length of the file name or the path is zero.

The not-empty policy for java.lang.Object[] fails if:

• The object is null.
• The length of the array is zero.

Examples

1) String is not null

    // Definition of some field.
    @Initialize( SomeCommand.CONTEXT_KEY )
    @ValidateValue( ValidationPolicy.NOT_NULL )
    String someField;                                                                   

2) Object is not null

    // Definition of some field.
    @Initialize( SomeCommand.CONTEXT_KEY )
    @ValidateValue( ValidationPolicy.NOT_NULL )
    Object someField;                                                                   

3) String is not empty

    // Definition of some field.
    @Initialize( SomeCommand.CONTEXT_KEY )
    @ValidateValue( ValidationPolicy.NOT_EMPTY )
    String someField;                                                                   

4) Collection is not empty

    // Definition of some field.
    @Initialize( SomeCommand.CONTEXT_KEY )
    @ValidateValue( ValidationPolicy.NOT_EMPTY )
    Collection someField;                                                                       

4) Unnecessary double test using not-null + not-empty

    // Definition of some field.
    @Initialize( SomeCommand.CONTEXT_KEY )
    @ValidateValue( {ValidationPolicy.NOT_NULL, ValidationPolicy.NOT_EMPTY})
    Collection someField;                                                                       

Since the not-empty policy includes a not-null validation before the object is tested for emptiness, there is no need to combine not-null and not-empty on fields. A not-empty policy will do.

Invoking commands using a command facade

Invocation of indirectly commands through a command facade requires the implementation of the facade.

The facade should expose the parameter required by a command through the facade interface. Examples of commands facades are the CommandFacade in the core component and the DockerClient in the docker support project.

The facade should invoke commands using a command as described in the next section.

The usage of a facade is recommended for command which are reused across a project, since the command invocation using a command runner only needs to be implemented once.

A command facade should throw a an exception when the command invocation fails. The exception should be a subclass of the ExecutionResultException which can contain an embedded ExecutionResult. The exception should contain execution result for the failed command to allow for further inspection by the client.

Invoking commands using a command runner

Invoking commands using a command runner supports:

• Execution of a command in a controlled way, i.e. runtime exceptions are caught and collected for analysis.
• Information about how the execution went is collected for analysis.
• Factory for creation of command context.

The command runner core interface is com.alpha.pineapple.command.execution.CommandRunner which provides the interface for execution of commands in Pineapple. The command API contains a standard implementation of the interface which is named CommandRunnerImpl.

Example of how to execute a command using the command runner:

class SomeClass {

  /**
   * Test response properties command.
   */
  @Resource
  Command testResponsePropertiesCommand;

  /**
   * Command runner
   */
  @Resource
  CommandRunner commandRunner;        

  public void someMethod( ExecutionResult executionResult ) {
            
    // configure command runner with execution result
    commandRunner.setExecutionResult( executionResult );

    // create context
    Context context = commandRunner.createContext();
    
    // setup the context
    context.put(.....);

    // create description
    String description = "description of the command....";
                                        
    // run command            
    commandRunner.run(testResponsePropertiesCommand, description, context);
  }
}                                

The example shows the five steps needed to run a command:

• Get a command runner.
• Get the command.
• Configure the command runner with a execution result.
• Setup the context.
• Use the runner to run the command.

Getting the command runner

A command runner is obtained by dependency injection done by Spring. In the example above the class SomeClass is part of some project. The project should define a Spring context configuration file where SomeClass and the command runner are defined as beans:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:context="http://www.springframework.org/schema/context"
    
        xsi:schemaLocation="http://www.springframework.org/schema/beans 
                        http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
                http://www.springframework.org/schema/context 
                http://www.springframework.org/schema/context/spring-context-3.0.xsd" >
        
        <!-- import pineapple-command-api bean definitions. -->
        <bean id="commandRunner" class="com.alpha.pineapple.command.execution.CommandRunnerImpl" />                                                                                                     

        <!-- enable annotation based configuration / dependency injection -->
        <context:annotation-config />

        <!-- define SomeClass bean-->
        <bean id="someClass" class="com.alpha.pineapple.example.SomeClass" />
        
        <!-- define command bean-->     
    <bean id="testResponsePropertiesCommand" class="com.alpha.pineapple.plugin.net.command.TestResponsePropertiesCommand" scope="prototype" />          
</beans>

The configuration file contains:

• The class SomeClass is defined as a bean named someClass.
• The class CommandRunnerImpl is defined as a bean named commandRunner.
• Annotation based configuration is enabled with the tag context:annotation-config.

The configuration file is missing the wiring of the command runner into the someClass bean. The dependency injection is instead setup by these two steps:

• SomeClass defines a @Resource annotated field with a matching of the type CommandRunner and matching name of the command runner bean, i.e. commandRunner:

  @Resource
  CommandRunner commandRunner;        
  

• The Spring configuration file has annotation based configuration enabled, which trigger the wiring of the command runner into the someClass bean when the context is initialized.

  <!-- enable annotation based configuration / dependency injection -->
  <context:annotation-config />
  

..so lookup the SomeClass bean from the application context (or inject it into another object) and it will be initialized with a command runner instance.

Finally, a few bits about the command runner bean definition:

• The command runner is defined as a prototype bean. This is not necessary but it ensures that a new command runner instance is injected into each dependent object.
• The spring context configuration file shown above will reside in the project where SomeClass is defined, and yet there is a bean definition of the command runner which reside in the pineapple-commands-api project. This is not an optimal solution as each project is required to (re)define command runner as a bean.

Getting the command

The command is obtained the same way as the command runner, e.g. by dependency injection. The steps are the same:

• Define the command in the Spring context configuration file, as shown in the above example:

  <!-- define command bean-->     
  <bean id="testResponsePropertiesCommand" class="com.alpha.pineapple.plugin.net.command.TestResponsePropertiesCommand" scope="prototype" />              
  

• Define a field of the type Command in the class where the command runner is used. Let the field name match the bean ID in the Spring application context (or define the bean ID on the @Resource annotation). Here is the field definition in SomeClass:

   @Resource
   Command testResponsePropertiesCommand;         
  

• The field is initialized where the class is wired by Spring.

Configure the command runner with a execution result

The command runner should be configured with a execution result object to provide a way to capture the result of the execution of the command. Invoke the CommandRunner.setExecutionResult( executionResult ) with a root execution result object:

// configure command runner with execution result
commandRunner.setExecutionResult( executionResult );

If the no execution result object is configured before the command runner is used then the command runner will create a new root execution result object when the runner is used to execute commands. This create an new hierarchy of execution objects and this is not recommended. Always tap into an existing hierarchy of execution objects as this will ensure that the results are propagated to the client.

Setup the context

Create a context for the chain command and populate it with the properties required by the command. Use the command runner to create contexts for commands by invoking the method CommandRunner.createContext() which creates e new Chain context;

// create context
Context context = commandRunner.createContext();
    
// setup the context
context.put(.....);              

Use the runner to run the command

Invoke the method CommandRunner.run(Command command, String description, Context context) to execute the command:

// run command            
commandRunner.run(testResponsePropertiesCommand, description, context);

When the runner is invoked it will:

1. The runner validates whether it has been configured with a root execution result object. If this is not the case, then it will create a new root execution result object.
2. The runner creates a new child execution result object and stores the supplied description argument with the result object. This result object is used to describe how the execution of the command proceeds.
3. The child execution result object is added as the child to the root execution result object.
4. The runner adds the child execution object to the context with the key execution-result.
5. The runner invokes Command.execute(Context context) on the command.
6. The command executes its business logic. And prior to completion it should update the execution result object which where added to the context. The command should update the state by:
   • Set the execution state to reflect the outcome of the execution, e.g. success, failed, error or computed.
   • Add a message with the key Message which describes how the execution went.
   • If the execution completed with an error state, then add a message with the key StackTrace which contains the stack trace for the error.
7. If the command throws an exception, then the runner will catch it and complete the child execution result as failed with an error using the exception as input.
8. Return the child execution result.

Invoking command from other commands

The recommended approach to invoke a command from another command is to implemente the invocation in a command facade which enable reused of the invocation plumbing code.

The recipe for invoking other commands from a command is basically the same as invoking a command from any class, which was illustrated by SomeClass above. Here is an example of CommandA which invokes CommandB:

class CommandA implements Command{

 @Resource
 Command commandB;              

 @Resource
 CommandRunner commandRunner;        

 public boolean execute(Context context) throws Exception {

   // get execution result from context
   ExecutionResult result = (execution result) context.get("execution-result");

   // configure command runner with execution result
   commandRunner.setExecutionResult( result );

   // create context for CommandB
   Context cmdBcontext = commandRunner.createContext();
    
   // setup the context CommandB
   cmdBcontext.put(.....);

   // run command            
   commandRunner.run(commandB, "description of the command B...", context);
 
   // other stuff here....  
 }

}

Be aware of these points:

• Create child execution results from the existing execution result. If CommandA is invoked from the class SomeClass using the recipe described above, then command context contains a execution result object for CommandA. The execution result should be used to configure the command runner which is used to invoke CommandB. This will ensure that the execution result for CommandB is created as a child for CommandA and all of the results are propagated to the Pineapple client:

  class CommandA implements Command{
  
   @Resource
   Command commandB;              
  
   @Resource
   CommandRunner commandRunner;        
  
   public boolean execute(Context context) throws Exception {
  
     // get execution result from context
     ExecutionResult result = (execution result) context.get("execution-result");
  
     // configure command runner with execution result
     commandRunner.setExecutionResult( result );
  
     // create context for CommandB
     Context cmdBcontext = commandRunner.createContext();
      
     // setup the context CommandB
     cmdBcontext.put(.....);
  
     // run command            
     commandRunner.run(commandB, "description of the command B...", context);
   
     // other stuff here....  
   }
  
  }
  
  

• Create a separate command context. Create a new command context for CommandB to avoid overwriting properties that the invoker of CommandA expects to be defined in the context.

These principles should be observed even if the commands reside in the same project.