things.thinger.service.command.local
Class LocalCommander

java.lang.Object
  things.thinger.service.command.local.LocalCommander

All Implemented Interfaces:

Verbose, ResourceInterface, Commander

public class LocalCommander
extends java.lang.Object
implements Commander, ResourceInterface, Verbose

A Commander implementation intended for a local environment.

Command semantics:
Command
- creates-[ Entity<LocalCommandInfo>(idNumber,COMMAND,ROUTINE,ConduitId.responseConduit,WhoAmI(commandIdString),id, attributeData ]
Entity(int n, Type t, Priority p, O thing, WhoAmI imposedId, WhoAmI creatorId, AttributeReader a))
- sends Entity<LocalCommandInfo> ---} myCommandConduit
[--- returns Receipt(myId, commandIdString, Receipt.Type.ACCEPTANCE, commandIdString)
Receipt(WhoAmI callerID, String theToken, Receipt.Type theType, String note)

commandIdString is the command transaction id and can be used to associate commands with responses.


CommandResponse
- gets-[ Entity<Receipt>(idNumber,COMMAND_RESPONSE,ROUTINE,Receipt,echo.Command.WhoAmI(commandIdString),id, attributeData ]
Entity(int n, Type t, Priority p, O thing, WhoAmI imposedId, WhoAmI creatorId, AttributeReader a))


Some of the methods are synchronized to keep the pendingCommands safe. It might be possible to trim this some later.

Version:

1.0

Version History

EPG - Initial - 22 MAY 06
 

Author:

Erich P. Gatejen

Nested Class Summary

Nested classes/interfaces inherited from interface things.thinger.kernel.ResourceInterface

ResourceInterface.State

Field Summary

static java.lang.String

COMMAND_ID_TAG Command tag.

Fields inherited from interface things.thinger.kernel.ResourceInterface

NULL_ID

Constructor Summary

LocalCommander(Conduit commandConduit, Conduit responseConduit, WhoAmI id)
Construct a commander.

Method Summary

void	disposal() Allow the disposal procecure to run.
void	disposeResource() RESOURCE INTERFACE IMPLEMENTATION.
void	drainResponses() Spend some time draining responses.
WhoAmI	getId() RESOURCE INTERFACE IMPLEMENTATION.
ResourceInterface.State	getState() RESOURCE INTERFACE IMPLEMENTATION.
void	initResource(WhoAmI id) RESOURCE INTERFACE IMPLEMENTATION.
Receipt	issueCommand(Command commandToIssue) This will issue a command.
boolean	isVerbose() VERBOSE INTERFACE.
boolean	lock() RESOURCE INTERFACE IMPLEMENTATION.
CommandResponse	queryResponse(Receipt commandReceipt) Query the reponse progress a command.
void	screech(java.lang.String message) VERBOSE INTERFACE.
void	unlock() RESOURCE INTERFACE IMPLEMENTATION.
void	verboseOff() VERBOSE INTERFACE.
void	verboseOn(StringPoster poster) VERBOSE INTERFACE.

Methods inherited from class java.lang.Object

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

Field Detail

COMMAND_ID_TAG

public static final java.lang.String COMMAND_ID_TAG

Command tag.

See Also:

Constant Field Values

Constructor Detail

LocalCommander

public LocalCommander(Conduit commandConduit,
                      Conduit responseConduit,
                      WhoAmI id)
               throws SystemException

Construct a commander.

Throws:

SystemException

Method Detail

issueCommand

public Receipt issueCommand(Command commandToIssue)
                     throws SystemException

This will issue a command. It returns a receipt for the issuance, not for the other all interaction. If there was something wrong with the issuance process, it will throw an exception. It will not issue a BAD receipt.

Specified by:

issueCommand in interface Commander

Parameters:

commandToIssue - The command to issue.

Throws:

SystemException

queryResponse

public CommandResponse queryResponse(Receipt commandReceipt)
                              throws SystemException

Query the reponse progress a command. It is up to the implementation as to when responses are handled. If they are not handled in a separate thread, it is possible this call with take time to handle responses. The implementation will make a best-effort to keep InterruptedExceptions from fouling the process. If it successful, the interruption will propagate as a simple WARNING level SystemException. If not, you could see anything up to a PANIC.
If the resposne is not found, it will throw an exception.

Specified by:

queryResponse in interface Commander

Parameters:

commandReceipt - The issuance receipt.

Returns:

A response object.

Throws:

SystemException

disposal

public void disposal()
              throws SystemException

Allow the disposal procecure to run. It is safe to call this any time. It will sweep any DISPOSED responses from the system, which may build up over time. The CommandResponse implementations may or may not call it.

This implementation will remove any references to it to it can go away for good. Any delayed command responses will get dropped and a WARNING will be logged.

Specified by:

disposal in interface Commander

Throws:

SystemException

drainResponses

public void drainResponses()
                    throws SystemException

Spend some time draining responses. A call to queryResponse will always do this. The LocalCommandResponse should do this. Anyone else not using LocalCommandResponse should definately do this from time to time.

Throws:

SystemException

verboseOn

public void verboseOn(StringPoster poster)
               throws ThingsException

VERBOSE INTERFACE. DON'T TOUCH.

Specified by:

verboseOn in interface Verbose

Parameters:

poster - StringPoster where to put the debug info

Throws:

ThingsException

verboseOff

public void verboseOff()

VERBOSE INTERFACE. DON'T TOUCH.

Specified by:

verboseOff in interface Verbose

screech

public void screech(java.lang.String message)

VERBOSE INTERFACE. DON'T TOUCH.

Specified by:

screech in interface Verbose

Parameters:

message - The message.

isVerbose

public boolean isVerbose()

VERBOSE INTERFACE. DON'T TOUCH.

Specified by:

isVerbose in interface Verbose

Returns:

true if it is verbose, otherwise false.

initResource

public void initResource(WhoAmI id)
                  throws SystemException

RESOURCE INTERFACE IMPLEMENTATION. LEAVE ALONE.

Specified by:

initResource in interface ResourceInterface

Parameters:

id - The id of the resource.

Throws:

SystemException

See Also:

WhoAmI

disposeResource

public void disposeResource()
                     throws SystemException

RESOURCE INTERFACE IMPLEMENTATION. LEAVE ALONE.

Specified by:

disposeResource in interface ResourceInterface

Throws:

SystemException

lock

public boolean lock()
             throws SystemException

RESOURCE INTERFACE IMPLEMENTATION. LEAVE ALONE.

Specified by:

lock in interface ResourceInterface

Returns:

true if the lock was completed, false if locks are not allowed.

Throws:

SystemException

unlock

public void unlock()
            throws SystemException

RESOURCE INTERFACE IMPLEMENTATION. LEAVE ALONE.

Specified by:

unlock in interface ResourceInterface

Throws:

SystemException

getId

public WhoAmI getId()
             throws SystemException

RESOURCE INTERFACE IMPLEMENTATION. LEAVE ALONE.

Specified by:

getId in interface ResourceInterface

Returns:

WhoAmI

Throws:

SystemException

See Also:

WhoAmI

getState

public ResourceInterface.State getState()
                                 throws SystemException

RESOURCE INTERFACE IMPLEMENTATION. LEAVE ALONE.

Specified by:

getState in interface ResourceInterface

Returns:

State

Throws:

SystemException