com.kuka.roboticsAPI.controllerModel.sunrise
Class Primitive

java.lang.Object
  com.kuka.roboticsAPI.controllerModel.sunrise.Primitive

Direct Known Subclasses:

SprPrimitive

public abstract class Primitive
extends Object

A Primitive represents a Sunrise-specific controller command. The command has a specific life cycle and tracks its execution on the controller. The Primitive state always reflects the execution state of the command on the controller.

A Primitive is not meant to be passed on to the user of the API. Each Primitive belongs to a SunriseExecutionContainer that the user can use to track the execution of commands.

!!! CAUTION implementers !!!

If the Primitive hierarchy is extended so that there is can be a primitive that contain of more than one consecutive SPRs or SPR stacks you have to make sure that all the SPRs will be cancelled if one of them goes into error state.

For now this function is implemented in SunriseExecutionContainer.primitiveStateChanged(Primitive, ExecutionState, String)!

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

Constructor Summary

protected

Primitive(SunriseExecutionContainer container) Creates a new Primitive instance.

Method Summary

void	addStateListener(IPrimitiveStateListener listener) Adds a listener for this primitive.
abstract void	cancel() Cancels the primitive.
protected FiredConditionInfo	createFiredConditionInfo(SPR spr, SunriseStopCondition stopCondition) Creates the fired condition information.
abstract Collection<SPR>	getAllSprs() Returns all SPRs that this Primitive consists of.
SunriseExecutionContainer	getContainer() Returns the container to which this Primitive belongs.
static IRedundancyCollection	getRedundancy(int status, int turn, Double alpha) Returns the correct redundancy collection depending on the specifying an alpha value or not.
ExecutionState	getState() Returns the current state of the Primitive.
protected void	handleSprCompoundEvent(SPR spr, Message msg) Called when one of the SPR compounds has thrown an event.
protected void	handleSprStateChanged(SPR eventSpr, SPRState newState) Called when the state of the given SPR changed.
protected static ExecutionState	mapSunriseStateToCommandState(SPRState sprState) Utility method: Maps a Sunrise SPR state to an ExecutionState.
protected void	registerAsSprListener(SPR spr) Registers this primitive for SPR state events.
void	removeStateListener(IPrimitiveStateListener listener) Removes the listener from this primitive.
protected void	setState(ExecutionState newState, String errorMessage) Sets the state of this Primitive and notifies its ExecutionContainer of the state change.
protected com.kuka.common.Pair<ExecutionState,String>	stateFromSpr(SPR spr, SPRState newState) Utility method: Examines the given SPR and the given state for error conditions and maps them to an ExecutionState.
protected abstract void	unregisterAllSprListener() Unregisters this primitive from ALL SPR state events.
protected void	unregisterAsSprListener(SPR spr) Unregisters this primitive from SPR state events.

Methods inherited from class java.lang.Object

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

Constructor Detail

Primitive

protected Primitive(SunriseExecutionContainer container)

Creates a new Primitive instance.

Parameters:

container - the container to which this Primitive belongs.

Method Detail

registerAsSprListener

protected void registerAsSprListener(SPR spr)

Registers this primitive for SPR state events. SPR state events will be forwarded to handleSprStateChanged(SPR, SPRState) and handleSprCompoundEvent(SPR, Message).

Parameters:

spr - the SPR

unregisterAsSprListener

protected void unregisterAsSprListener(SPR spr)

Unregisters this primitive from SPR state events. SPR state events will no longer be forwarded to handleSprStateChanged(SPR, SPRState) and handleSprCompoundEvent(SPR, Message).

Parameters:

spr - the SPR

unregisterAllSprListener

protected abstract void unregisterAllSprListener()

Unregisters this primitive from ALL SPR state events. SPR state events will no longer be forwarded to handleSprStateChanged(SPR, SPRState) and handleSprCompoundEvent(SPR, Message).

getAllSprs

public abstract Collection<SPR> getAllSprs()

Returns all SPRs that this Primitive consists of.

Returns:

all SPRs that this Primitive consists of

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

cancel

public abstract void cancel()

Cancels the primitive.

Cancels all SPRs belonging to the primitive.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

getContainer

public SunriseExecutionContainer getContainer()

Returns the container to which this Primitive belongs.

Returns:

the container to which this Primitive belongs

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

mapSunriseStateToCommandState

protected static ExecutionState mapSunriseStateToCommandState(SPRState sprState)

Utility method: Maps a Sunrise SPR state to an ExecutionState.

Parameters:

sprState - The Sunrise SPR state.

Returns:

The new execution state of a mapping is found or the old one.

getState

public ExecutionState getState()

Returns the current state of the Primitive.

Returns:

the current state of the Primitive

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

setState

protected void setState(ExecutionState newState,
                        String errorMessage)

Sets the state of this Primitive and notifies its ExecutionContainer of the state change. Counts down latches for reaching states. This is necessary for a few test cases where we have to wait until a specific state is set.

Parameters:

newState - the new state

errorMessage - an error message, may be null

stateFromSpr

protected com.kuka.common.Pair<ExecutionState,String> stateFromSpr(SPR spr,
                                                                   SPRState newState)

Utility method: Examines the given SPR and the given state for error conditions and maps them to an ExecutionState.

Parameters:

spr - the SPR to examine.

newState - The state of the SPR to consider. This is a separate parameter for this method because the state of the SPR can change asynchronously.

Returns:

a Pair consisting of a corresponding ExecutionState and an error string. The string can be null.

createFiredConditionInfo

protected FiredConditionInfo createFiredConditionInfo(SPR spr,
                                                      SunriseStopCondition stopCondition)

Creates the fired condition information.

Parameters:

spr - The SPR which contains the stop condition which has fired.

stopCondition - The stop condition which has fired.

Returns:

A new instance of FiredConditionInfo.

getRedundancy

public static IRedundancyCollection getRedundancy(int status,
                                                  int turn,
                                                  Double alpha)

Returns the correct redundancy collection depending on the specifying an alpha value or not.

Parameters:

status - status value

turn - turn value

alpha - alpha value or null if not existing.

Returns:

redundancy collection containing the redundancy values.

handleSprStateChanged

protected void handleSprStateChanged(SPR eventSpr,
                                     SPRState newState)

Called when the state of the given SPR changed.

Parameters:

eventSpr - The SPR which changed it's state.

newState - The new state of the SPR.

handleSprCompoundEvent

protected void handleSprCompoundEvent(SPR spr,
                                      Message msg)

Called when one of the SPR compounds has thrown an event.

Parameters:

spr - The SPR whose compound has thrown an event.

msg - compound event message.

addStateListener

public final void addStateListener(IPrimitiveStateListener listener)

Adds a listener for this primitive.

Parameters:

listener - The state listener for this primitive's state. null is not allowed.

Throws:

IllegalArgumentException - if listener is null or the same listener is already registered

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

removeStateListener

public final void removeStateListener(IPrimitiveStateListener listener)

Removes the listener from this primitive.

Parameters:

listener - The state listener for this primitive's state. null is not allowed.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.