StatePlugin interface

This is the main interfaces of the state development.

Syntax

public interface StatePlugin

Derived classes

Remarks

States need to implement this interface so that: it can be displayed on the Application Composer and State Editor, and invoked by the "Processing Engine" at application runtime. As such it should be regarded as the 'external' API. Any classes that extend this interface will be referred to as State for the purpose of this API documentations. Some methods are used only by the state editor or the processing engine, others may be used by both, as stated in each methods description.

INTRODUCTION

An Application defines the process flow in the form of interconnected states. An application usually has more than one states, and can include more than one types of state. Therefore, states are the building blocks for composing an application. This StatePlugin is the interface that needs to be implemented by the states.

LIFE CYCLE

At runtime, the processing engine will step through the application flow based on the matched transition logic (called follow-up transition) and execute the corresponding state. The processing engine will execute the application and state based on the following life cycle.
  1. Application can be invoked by many different external activation mechanisms, such as: incoming SMS message, scheduled event, or web service invocation. The first state in any applications is the "Application Start" state, that is automatically created by default and cannot be removed. So immediately after invoking the application, the first state, the "Application Start" state will be executed.
  2. When executing a state, the processing engine will call one of the following processing methods: the processMessage(SmappStateProcessingContext) and the processState(SmappStateProcessingContext, SmappStateProcessingAction), based on the activation mechanism, described in details below (see ACTIVATION).The method(s) need to be implemented by each state to encapsulate the business logic that the state represents.
  3. The state can be invoked by two methods: external activation or follow-up transition. The <u>external</u> occurs when the state processing has been temporarily paused (or hibernated) waiting for an external event, and the state is re-activated by the arrival of the external event. In this case, the processMessage() will be called.If the state is invoked by the follow-up transition, in this case from another state, the second method or processState() will be called.
  4. The first method (i.e., processMessage()) returns the follow-up transition object (SmappState) that will become the current state for the subsequent method (i.e., processState()).For example, let's say the application flow looks like the following: state1 ->Send SMS state -> state2 ->state3 When the flow reaches the Send SMS state, a message will be sent out and the flow will be paused waiting for a response. The current state remains as the Send SMS state. On arrival of the response message, first the processMessage() method will be called. This method will find the follow-up transition that match the incoming message, and return the corresponding state. Let's say it's "state2". Next, the processing engine will make "state2" as the current state and then call the processState() method of "state2".
  5. The processState() method does not return the follow-up transition object (or SmappState), but instead setting the input parameter (SmappStateProcessingAction), by calling the appropriate method, to communicate to the processing engine the intended follow-up transition.
  6. Using the above application flow example, the processState() method of "state2" specify "state3" as the follow-up transition state. So the processing engine will continue the process by calling the processState() method of "state3".
  7. This process of stepping through the flow will continue until one of the following conditions:
    • reaching a state that set the processing engine to the waitForMessage status, such as after sending SMS out. The process will re-start on arrival of the message, and it will invoke the processMessage() method. The process then repeat from step 4 again.
    • the state has no follow-up transition, so the processing engine will terminate

STATE ACTIVATION

The state can be activated by two methods: external or follow-up. In most cases, the state is activated by the follow-up method. The <u>follow-up activation</u> occurs as a result of a follow-up transition from the previous connected state. In addition, the follow-up activation can also occur when the state performs the loop-back mechanism from the one of the processing methods: processMessage(SmappStateProcessingContext) or processState(SmappStateProcessingContext, SmappStateProcessingAction) methods, by conditionally returning the current state (or context.currentState). NOTE: please use the loop-back mechanism with caution because it could easily resulting in an infinite loop in the state processing. The follow-up activation calls the processState(SmappStateProcessingContext, SmappStateProcessingAction) method, and the state implements the required business logic in this method.

The <u>external activation</u> occurs when the state processing has been temporarily paused (or hibernated) waiting for an external event, and the state is re-activated by the arrival of the external event by invoking the the processMessageLogic(SmappStateProcessingContext) method. The external activation mechanism is used by states that support the Send SMS, such as: the base "Send SMS" state and the states that extend the com.sybase365.mobiliser.brand.plugins.smapp.state.AbstractDynamicMenu. For example, the "Send SMS" state sends an SMS message to the mobile device, and then goes into hibernation. When a reply message arrives, this will re-activate state using the external activation method that calls the processMessage(SmappStateProcessingContext) method. In addition, any state that implements the calls to the SmappStateProcessingAction - waitForMessage() in the processing methods will also need to ensure that external activation will happen and it can handle the external activation in the processMessage(SmappStateProcessingContext) method. Otherwise, the application will never continue and it will be terminated when the session timeout.

The processMessage(SmappStateProcessingContext) and processState(SmappStateProcessingContext, SmappStateProcessingAction) methods are referred to as the processing methods.

RETURNING FLOW BACK TO PROCESING ENGINE

There are two mechanisms to return the process back to the processing engine:
  • Follow-up transition - the state returns the SmappState from the (processMessage(SmappStateProcessingContext) method, that tells the processing engine which follow-up transition to follow and hence the corresponding follow-up state.
  • Follow-up action - by setting the SmappStateProcessingAction object provided by processing engine as an input parameter to the processing methods. The SmappStateProcessingAction provides methods for setting the needed actions. For example, calling action.waitForMessage() tells the processing engine to wait for external activation before proceeding.The processState(SmappStateProcessingContext, SmappStateProcessingAction) does not return SmappState object. So it needs to use the input parameter SmappStateProcessingAction to tell the processing engine which follow-up transition to follow.When the follow-up action is used, the processing methods should return null.

Parent topic: smapp package