things.thinger.service.command.local
Class LocalCommander

java.lang.Object
  extended by 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


Things.