things.thinger.service.command
Class Command

java.lang.Object
  extended by things.thinger.service.command.Command
Direct Known Subclasses:
Command_KILL, Command_PINGPONG, Command_PROCESSLIST, Command_QUIT, Command_RUN, Command_SETPROP, Command_SHOWPROPS

public abstract class Command
extends java.lang.Object

A command. It is an entity with a String object. The string is the text associated with the command. It's up to the command processor to decide what to do with it. The numeric defined the actual command. Parameters should be passed through the attributes.

Since commands are Entities, they have an Id and a creators Id.

Note that the Command validates PARAMETERs, where the CommandResponse will validate the RESPONSEs. This means it is possible for a responder to flood a CommandResponse. Later we may abstract Command enough to let a specific implementation handle the RESPONSE validation too.

Version:
1.0

Version History

EPG - Initial - 12 FEB 06
 
Author:
Erich P. Gatejen

Nested Class Summary
static class Command.CheckType
          Are we checking a command or a response.
static class Command.DataType
          The type of the parameter.
static class Command.Occurrence
          The occurence of a parameter.
static class Command.Requirement
          The requirement for a parameter.
 
Constructor Summary
Command()
          Default constructor.
Command(CommandRegistry imposedRegistry)
          Default constructor.
 
Method Summary
abstract  void accept()
          This will be called when the command is called.
static void checkDataForm(AttributeReader attributes, Command.CheckType type, CommandDefinition definition)
          Validate data for occurence and type.
static void checkRequiredData(AttributeReader attributes, Command.CheckType type, CommandDefinition definition)
          Validate data for required items.
 void DECLARE_NAME(java.lang.String theName, java.lang.String className)
          Declare the name of the command.
 void DECLARE_PARAMETER(java.lang.String parameterName, Command.Requirement theRequirement, Command.Occurrence theOccurence, Command.DataType theDataType)
          Declare a parameter.
 void DECLARE_RESPONSE(java.lang.String responseName, Command.Requirement theRequirement, Command.Occurrence theOccurence, Command.DataType theDataType)
          Declare a response.
abstract  void declare()
          Command declaration.
 void DONE()
          Set the response as done.
 void FLUSH()
          Force the response to flush.
 NVImmutable GET_PARAMETER(java.lang.String name)
          Get a parameter.
 SystemInterface GET_SYSTEM_INTERFACE()
          Get the system interface.
 CommandDefinition getDefinition()
          Get the command definition.
 AttributeReader getInstanceData()
          Get the instance data for the command.
 void instantiateCommand()
          Instantiate a new instance.
static Command instantiateResponse(java.lang.String commandName, CommandResponder responder)
          Create a new instance object and instantiate.
abstract  java.lang.String named()
          Return the official name of this command.
 void RESPOND(NV item)
          Set a response.
 void RESPOND(java.lang.String name, java.lang.String... value)
          Set a response.
 void SET_PARAMETER(java.lang.String name, java.lang.String... value)
          Set a parameter.
 void validateReceiptList(ReceiptList result)
          Validate this is a valid receipt list.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Command

public Command()
Default constructor. This will use the system global registry.


Command

public Command(CommandRegistry imposedRegistry)
Default constructor.

Parameters:
imposedRegistry - This will set which registry to use.
Method Detail

DECLARE_NAME

public final void DECLARE_NAME(java.lang.String theName,
                               java.lang.String className)
                        throws SystemException
Declare the name of the command.

Parameters:
theName - The name.
className - The class name. Chose to do this since you can't trust 'this'.
Throws:
SystemException - For any missuse.

DECLARE_PARAMETER

public final void DECLARE_PARAMETER(java.lang.String parameterName,
                                    Command.Requirement theRequirement,
                                    Command.Occurrence theOccurence,
                                    Command.DataType theDataType)
                             throws SystemException
Declare a parameter. If a parameter by the same name is already declared, it will throw an error Exception.

Parameters:
parameterName - The parameter name.
theRequirement - The requirement for the item.
theOccurence - The occurence for the item.
theDataType - The data type for the item.
Throws:
SystemException

DECLARE_RESPONSE

public void DECLARE_RESPONSE(java.lang.String responseName,
                             Command.Requirement theRequirement,
                             Command.Occurrence theOccurence,
                             Command.DataType theDataType)
                      throws SystemException
Declare a response. If a parameter by the same name is already declared, it will throw an error Exception.

Parameters:
responseName - The response name.
theRequirement - The requirement for the item.
theOccurence - The occurence for the item.
theDataType - The data type for the item.
Throws:
SystemException

SET_PARAMETER

public void SET_PARAMETER(java.lang.String name,
                          java.lang.String... value)
                   throws SystemException
Set a parameter. If it is a multi-value.

Parameters:
name - the name of the parameter.
value - the values associated with the parameter. It can be one or more.
Throws:
SystemException

GET_SYSTEM_INTERFACE

public SystemInterface GET_SYSTEM_INTERFACE()
                                     throws SystemException
Get the system interface.

Returns:
the system interface.
Throws:
SystemException

GET_PARAMETER

public NVImmutable GET_PARAMETER(java.lang.String name)
                          throws SystemException
Get a parameter. If it isn't set and required, it'll throw an exception. If it isn't set but not required, it'll just return a null.

Parameters:
name - the name of the parameter
Returns:
an NVImmutable containing the parameter.
Throws:
SystemException

RESPOND

public void RESPOND(java.lang.String name,
                    java.lang.String... value)
             throws SystemException
Set a response. If it is a multi-value, it'll be handled appropriately.

Parameters:
name - the name of the response item.
value - the values associated with the response. It can be one or more.
Throws:
SystemException

RESPOND

public void RESPOND(NV item)
             throws SystemException
Set a response. If it is a multi-value, it'll be handled appropriately.

Parameters:
item - the NV item with name/values associated with the response. It can be one or more.
Throws:
SystemException
See Also:
NV

FLUSH

public void FLUSH()
           throws SystemException
Force the response to flush.

Throws:
SystemException

DONE

public void DONE()
          throws SystemException
Set the response as done. This should be the LAST thing you do.

Throws:
SystemException

named

public abstract java.lang.String named()
Return the official name of this command. If there is another command named the same of different class signature, it will cause a significant system fault.

Returns:
The official name of the command.

declare

public abstract void declare()
                      throws SystemException
Command declaration. This will be called when the definition is needed.

Throws:
SystemException

accept

public abstract void accept()
                     throws SystemException
This will be called when the command is called.

Throws:
SystemException

instantiateCommand

public void instantiateCommand()
                        throws SystemException
Instantiate a new instance. This is what a commander should do. Technically, you can reinstantiate an object and use it again. This should ONLY be done by a commander.

Throws:
SystemException - As a fault.

instantiateResponse

public static Command instantiateResponse(java.lang.String commandName,
                                          CommandResponder responder)
                                   throws SystemException
Create a new instance object and instantiate. This requires the named command to have been defined by something else in the system already. This is what a command service should do when it receives a Command. This should ONLY be done by a command service.

Parameters:
commandName - The command class name.
responder - the responder.
Throws:
SystemException - As a fault.

getInstanceData

public AttributeReader getInstanceData()
                                throws SystemException
Get the instance data for the command. it will validate it. It will check the data and throw an exception if it is not good.

Returns:
an Attribute reader that will transport the command.
Throws:
SystemException

getDefinition

public CommandDefinition getDefinition()
                                throws SystemException
Get the command definition. Don't monkey with it!

Returns:
the definition.
Throws:
SystemException

checkRequiredData

public static void checkRequiredData(AttributeReader attributes,
                                     Command.CheckType type,
                                     CommandDefinition definition)
                              throws SystemException
Validate data for required items. It will throw an exception for any problem. The following codes are significant:

 SYSTEM_COMMAND_FAULT_INSTANCE_USED_BEFORE_READY          : Null attributes.
SYSTEM_COMMAND_ERROR_INSTANCE_MISSING_REQUIRED_PARAMETER : Missing required parameter.

Parameters:
attributes - Attributes to check.
type - Are we checking the parameters or the responses?
definition - The command definition to check against.
Throws:
SystemException

checkDataForm

public static void checkDataForm(AttributeReader attributes,
                                 Command.CheckType type,
                                 CommandDefinition definition)
                          throws SystemException
Validate data for occurence and type. It will throw an exception for any problem. The following codes are significant:

 SYSTEM_COMMAND_FAULT_INSTANCE_USED_BEFORE_READY          : Null attributes.
SYSTEM_COMMAND_ERROR_INSTANCE_MISSING_REQUIRED_PARAMETER : Missing required parameter.

Parameters:
attributes - Attributes to check.
type - Are we checking the parameters or the responses?
definition - The command definition to check against.
Throws:
SystemException

validateReceiptList

public void validateReceiptList(ReceiptList result)
                         throws SystemException
Validate this is a valid receipt list. If it isn't, it will throw an exception.

Parameters:
result - The receipt list to examine.
Throws:
SystemException


Things.