com.sentilla.system
Interface Action

All Known Subinterfaces:
Button, ByteMessage, ByteReceiver, ByteSender, Cpu, DigitalPin, InterruptPin, Leds, Receiver, Sender, Sensor<Q>
All Known Implementing Classes:
AccelerationSensor, Action, Adc, Button, ByteReceiver, ByteSender, CC2420Radio.Receiver, CC2420Radio.Sender, CollectionProtocol.CSender, Cpu, CpuPowerSensor, DigitalPin, DispatcherAction, ExternUart, FileMapEntry, FlashFile, InterruptPin, KernelProperty, Leds, LoopBackProtocol.LoopBackReceiver, LoopBackProtocol.LoopBackSender, McuTemperature, McuVoltage, MotePower, ParSensorDriver.ParSensor, Receiver, RemoteInvoker, Sender, SensirionSht11.HumSensor, SensirionSht11.Sht11Sensor, SensirionSht11.TempSensor, TsrSensorDriver.TsrSensor, VoltageAdc

public interface Action

Actions represent asynchronous processes handled by an underlying action engine which encapsulating action verbs, submission states, and cached input and output parameters. Particular drivers implement the action interface, providing by convention blocking action verbs, getters, and setters.

The simplest and most common way to use a device action is through its blocking action verbs. Blocking action verbs appear to act as any other function by using the input parameters to prepare the action, submitting it to the action engine, blocking until the action engine completes the action, and returning any meaningful results. Examples of blocking action verbs are read, write, toggle, send, receive, and so on.

Getters and setters MUST access only the cached input and output parameters for the action. The particular device action defines which getters correspond to input parameters or output values or both, and which are valid before submission or after completion or both.

By convention, setters SHOULD always return a "this" pointer to the action. A device action MAY provide particular setters that directly or indirectly correspond to the blocking action verbs. Using this convention, advanced user code may asynchronously invoke a device action.

For example, imagine a device called BlockReader that implements Action to allows for block read operations, which may take some time to complete. The BlockReader interface may look something like this:

 interface BlockReader extends Action {
   public int read( byte[] buffer, int offset, int length );
   public BlockReadDevice setRead( byte[] buffer, int offset, int length );
   public int getNumRead();
 }

Given an instance of a BlockReader called block_reader, user code may directly call the blocking action verb read for synchronous reads, like this:

 byte[] buffer = new byte[200];
 int num_read = block_reader.read( buffer, 0, buffer.length );
 // here buffer has num_read valid bytes

Alternatively, advanced users may create more complex code to call setRead to perform asynchronous operations, like this:

 byte[] buffer = new byte[200];
 block_reader.setRead( buffer, 0, buffer.length ).submit();
 // ... do something else ...
 if( block_reader.block(250).isDone() ) {
   // Here, within 250ms of calling block(250), block_reader has completed
   // and buffer has valid bytes. Find out how many.
   int num_read = block_reader.getNumRead();
 }
 else {
   // Here, after at least 250ms, block_reader is not yet complete and buffer
   // has an indeterminate number of valid bytes, if any.  The result of
   // getNumRead is undefined here.
 }


Field Summary
static byte DONE
          Done action state.
static byte ERROR
          DoneError action state.
static byte IDLE
          Idle action state.
static byte PENDING
          Pending action state.
 
Method Summary
 Action block()
          Block an indefinite amount of time until this Action is no longer pending.
 Action block(int timeoutMilli)
          Block a defined amount of time or until the Action is no longer pending.
 Action cancel()
          Cancel this Action if PENDING.
 byte getActionState()
          Get the current state of this Action: IDLE, PENDING, DONE, or ERROR.
 boolean isDone()
          Return true is this Action is DONE.
 Action submit()
          Submit this Action for processing by the action engine.
 

Field Detail

IDLE

static final byte IDLE
Idle action state. The action may have valid inputs, has no valid output values and is not being processed by the action engine.

See Also:
Constant Field Values

PENDING

static final byte PENDING
Pending action state. The action input and output values are indeterminate while it is being processed by the action engine.

See Also:
Constant Field Values

DONE

static final byte DONE
Done action state. The action output values are valid because this action has been processed by the action engine.

See Also:
Constant Field Values

ERROR

static final byte ERROR
DoneError action state. The action output values are invalid because this the action engine encountered an error while processing this action.

See Also:
Constant Field Values
Method Detail

submit

Action submit()
Submit this Action for processing by the action engine. Calling submit transitions this Action to PENDING from either IDLE, DONE, or ERROR. Nothing happens if this Action is already PENDING.

Returns:
A pointer to this Action.

block

Action block()
             throws ActionException
Block an indefinite amount of time until this Action is no longer pending. Return immediately if the Action is IDLE or DONE. Return when the Action leaves the PENDING state, either through completion or cancellation. Throw ActionException if the Action is in ERROR.

Returns:
A pointer to this Action.
Throws:
ActionException

block

Action block(int timeoutMilli)
             throws ActionException
Block a defined amount of time or until the Action is no longer pending. Return immediately if the Action is IDLE or DONE. Return when the Action leaves the PENDING state, either through completion or cancellation, or until the timeout occurs, whichever comes first. Throw ActionException is the Action is in ERROR.

Parameters:
timeoutMilli - the maximum number of milliseconds to block
Returns:
A pointer to this Action.
Throws:
ActionException

cancel

Action cancel()
Cancel this Action if PENDING. If cancel successfully completes, it transitions this Action to IDLE from any state. If this Action is PENDING, a best effort is made to remove it from the underlying Action engine, and failing that, exception XXX-TODO is thrown.

Returns:
A pointer to this Action.

getActionState

byte getActionState()
Get the current state of this Action: IDLE, PENDING, DONE, or ERROR.


isDone

boolean isDone()
               throws ActionException
Return true is this Action is DONE. isDone can be used with block(timeoutMilli) to determine if the Action has completed. Calling isDone is equivalent to getActionState() == Action.DONE. Throw ActionException is getActionState() == Action.ERROR.

Throws:
ActionException


Copyright © 2007 Sentilla Corporation. All Rights Reserved.