protoj.core
Class InstructionChain

java.lang.Object
  protoj.core.InstructionChain

public final class InstructionChain
extends java.lang.Object

Represents the list of instruction that are to be executed, that are usually parsed from the command line. However instructions may be programmatically added with the addInstruction(String, String) method. The instructions are separated by spaces and consist of a name with possible options. Each instruction can also contain spaces when options are specified and so when this is the case, quotes be used around the entire instruction. The following example is an chain of two instructions:

 command1 "command2 -optA -optB"
 

The first instruction consists of just a name whereas the second instruction consists of a name as well as two options.

Most of the instructions correspond to commands with the same name from the commandStore that should be executed. However there are three special instructions that need specific handling:

• Instruction.INIT instruction: provides initialization information for the protoj domain objects including the project root directory and script name used to start the application.
• Instruction.OPTS instruction: provides system properties to the application

Author:

Ashley Williams

Constructor Summary

InstructionChain(java.io.File rootDir, java.lang.String scriptName)
Alternative constructor that doesn't rely on a main args array.

InstructionChain(java.lang.String[] args)
Creates an instance based on command line arguments.

Method Summary

Instruction	addInstruction(java.lang.String name, java.lang.String options) Adds another item to the configuration.
void	addJvmArg(java.lang.String jvmArg) Adds an additional jvm arg that will be applied to each command that is started in a new vm during the call to DispatchFeature.startVm(String, String[], String, ArgRunnable).
void	breakVisit() See visitAndRemove(ArgRunnable).
java.lang.String[]	createArgsAndRemove(boolean skipFirst) Creates command line args suitable for passing in a main method, including all the command instructions in this chain.
java.lang.String[]	createMainArgs(java.lang.String name, java.lang.String opts) Creates command line args suitable for passing in a main method, including just the specified instruction name and opts parameters.
Instruction	getInitInstruction() The init definition that should always be present.
java.util.List<java.lang.String>	getJvmArgs() See addJvmArg(String).
Instruction	getOptsInstruction() The opts definition that may be null.
java.io.File	getRootDir() The project root directory.
java.lang.String	getScriptName() The name of the script that invokes this application.
void	init(java.io.File rootDir, java.lang.String scriptName) Common initialization method.
Instruction	remove(java.lang.String name) Removes the instruction with the given name and returns it.
void	visitAndRemove(ArgRunnable<Instruction> visitor) Visits each of the instructions in turn, removing them as they are encountered.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

InstructionChain

public InstructionChain(java.lang.String[] args)

Creates an instance based on command line arguments.

Parameters:

args -

InstructionChain

public InstructionChain(java.io.File rootDir,
                        java.lang.String scriptName)

Alternative constructor that doesn't rely on a main args array.

Parameters:

rootDir -

scriptName -

Method Detail

init

public void init(java.io.File rootDir,
                 java.lang.String scriptName)

Common initialization method. Called by the constructors as well as by the InstructionChainArgs helper class.

Parameters:

rootDir -

scriptName -

getJvmArgs

public java.util.List<java.lang.String> getJvmArgs()

See addJvmArg(String).

Returns:

addJvmArg

public void addJvmArg(java.lang.String jvmArg)

Adds an additional jvm arg that will be applied to each command that is started in a new vm during the call to DispatchFeature.startVm(String, String[], String, ArgRunnable). The specified jvmArg should be in -DX=Y format.

Parameters:

jvmArg -

addInstruction

public Instruction addInstruction(java.lang.String name,
                                  java.lang.String options)

Adds another item to the configuration. A single item may contain not just the name but also the options, for example: "mycommand -arg1 -arg2". The first word in each instruction string when spaces are used as separators is assumed to be the name of the instruction.

The special init and opts instructions are kept out of the commandInstructions property since they don't correspond to commands in the command store. Instead they receive special treatment and are assigned to the initInstruction and optsInstruction properties instead.

If an instruction of the same name already exists it will be replaced. This limitation may be revisited in future.

Parameters:

name -

options -

Returns:

getInitInstruction

public Instruction getInitInstruction()

The init definition that should always be present.

Returns:

getOptsInstruction

public Instruction getOptsInstruction()

The opts definition that may be null.

Returns:

remove

public Instruction remove(java.lang.String name)

Removes the instruction with the given name and returns it. Null is returned if no matching instruction is found.

Parameters:

name -

Returns:

visitAndRemove

public void visitAndRemove(ArgRunnable<Instruction> visitor)

Visits each of the instructions in turn, removing them as they are encountered. This is because the assumption is that the commands are being handled one at a time and don't want to risk them being rehandled. In order to stop the visit early, the visitor should call breakVisit(). This will mean that it doesn't get passed any further instructions, but they are all still removed by the time this method returns.

Parameters:

visitor -

breakVisit

public void breakVisit()

See visitAndRemove(ArgRunnable).

createArgsAndRemove

public java.lang.String[] createArgsAndRemove(boolean skipFirst)

Creates command line args suitable for passing in a main method, including all the command instructions in this chain. Delegates to createMainArgsAsArray(Collection). The command instructions are then removed since the assumption is that a new vm will be started to handle them instead. We don't want to handle them again in the current vm.

Parameters:

skipFirst - specify true if the first command instruction isn't required - useful when bootstrapping commands not including the current

Returns:

createMainArgs

public java.lang.String[] createMainArgs(java.lang.String name,
                                         java.lang.String opts)

Creates command line args suitable for passing in a main method, including just the specified instruction name and opts parameters. Delegates to createMainArgsAsArray(Collection).

Parameters:

name -

opts -

Returns:

getRootDir

public java.io.File getRootDir()

The project root directory.

Returns:

getScriptName

public java.lang.String getScriptName()

The name of the script that invokes this application.

Returns: