com.vodafone360.people.engine
Class BaseEngine

java.lang.Object
  com.vodafone360.people.engine.BaseEngine

Direct Known Subclasses:

ActivitiesEngine, ContactSyncEngine, ContentEngine, GroupsEngine, IdentityEngine, LoginEngine, PresenceEngine, SyncMeEngine, UpgradeEngine

public abstract class BaseEngine
extends java.lang.Object

Base-class for all Engines implemented by the People Client.

Nested Class Summary

static interface	BaseEngine.IEngineEventCallback Interface which must be implemented by engine client.
private static class	BaseEngine.UiQueueItem Class to encapsulate client request information.

Field Summary

private java.lang.Integer	mActiveRequestId Set by the setReqId(int) function to store the request ID when a engine makes a request to the server.
protected ServiceUiRequest	mActiveUiRequest Current UI Request if one is active, otherwise null.
private java.lang.Boolean	mCommsResponseOutstanding true if a Comms response is waiting in the comms response queue for processing, false otherwise.
protected java.lang.Long	mCurrentTimeout Current timeout based on current time in milliseconds if one is pending, otherwise null.
private boolean	mDeactivated true if the engine is deactivated (for test purposes), false otherwise.
protected EngineManager.EngineId	mEngineId All engines must set this field to a unique ID
protected BaseEngine.IEngineEventCallback	mEventCallback Callback provided by EngineManager
private java.lang.Object	mMutex mutex for thread synchronization
private java.util.concurrent.ConcurrentLinkedQueue<BaseEngine.UiQueueItem>	mUiQueue Used to implement the UI request queue.
private boolean	mUiRequestOutstanding true if a UI request is waiting in the UI request queue for processing, false otherwise.
private boolean	resetDone Flag set when a request to reset the engine is made and the engine has performed its reset tasks.

Constructor Summary

BaseEngine(BaseEngine.IEngineEventCallback eventCallback)
Public constructor.

Method Summary

void	addUiRequestToQueue(ServiceUiRequest request, java.lang.Object data) Helper function for use by the derived engine class to add a UI request to the queue.
(package private) void	clearReset() Clears the reset flag.
protected void	clearTimeout() Cancels the current timer (has no effect if the timer was not active).
protected void	completeUiRequest(ServiceStatus status) A helper function that can be called by the derived engine implementation to complete the current UI request.
protected void	completeUiRequest(ServiceStatus status, java.lang.Object data) A helper function that can be called by the derived engine implementation to complete the current UI request.
protected void	deactivateEngine() Called by the framework to deactivate the engine.
protected void	emptyUiRequestQueue() Called by engines in the UI thread to cancel all UI requests.
EngineManager.EngineId	engineId() Return id for this engine.
private BaseEngine.UiQueueItem	fetchNextUiRequest() Helper function for use by the derived engine class to fetch the next UI request from the queue.
static ServiceStatus	genericHandleResponseType(java.lang.String requiredResp, java.util.List<BaseDataType> data) A helper function for the derived engine implementation to use.
protected long	getCurrentTimeout() The result of this function must be returned by getNextRunTime() instead of -1 for the timer to work.
abstract long	getNextRunTime() Return the absolute time in milliseconds when the engine needs to run (based on System.currentTimeMillis).
(package private) boolean	getReset() Gets the reset flag.
protected boolean	isCommsResponseOutstanding() Should be called by the getNextRunTime() and run() functions to check if there are any comms responses waiting to be processed.
boolean	isDeactivated() Called by the framework to determine if the engine should run.
protected boolean	isUiRequestOutstanding() Helper function to determine if there is any work outstanding in the UI request queue.
void	onCommsInMessage() Called by the EngineManager when a comms response is received.
abstract void	onCreate() This will be called immediately after creation.
abstract void	onDestroy() This will be called just before the engine is shutdown.
protected abstract void	onRequestComplete() This function must be implemented in the derived engine implementation.
void	onReset() Engines can override this function to do any special handling when a reset is needed.
protected abstract void	onTimeoutEvent() The derived engine implementation must call the processTimeout() function (normally from within the run() implementation), otherwise this will not be called.
private void	onUiRequestComplete(ServiceUiRequest request, ServiceStatus status, java.lang.Object data) Helper function which must be called to complete a UI request.
protected boolean	processCommsInQueue() Should be called by the run() function to process the comms in queue.
protected abstract void	processCommsResponse(ResponseQueue.Response resp) The derived engine implementation must call the processCommsInQueue() function (normally from within the run() implementation), otherwise this will not be called.
protected boolean	processTimeout() This function must be called by run() in the derived engine implementation for the timer to work.
protected boolean	processUiQueue() Should be called by the run() function to process the UI request queue.
protected abstract void	processUiRequest(ServiceUiRequest requestId, java.lang.Object data) The derived engine implementation must call the processUiQueue() function (normally from within the run() implementation), otherwise this will not be called.
abstract void	run() Do some work but anything that takes longer than 1 second must be broken up.
protected boolean	setReqId(int reqId) Called by engines when an API call is made to ensure that the response processed matches the request.
private void	setReset(boolean value) Sets the reset flag.
protected void	setTimeout(long timeoutVal) Helper function that can be called by the derived engine implementation to start an asynchronous timer.

Methods inherited from class java.lang.Object

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

Field Detail

mEngineId

protected EngineManager.EngineId mEngineId

All engines must set this field to a unique ID

mEventCallback

protected BaseEngine.IEngineEventCallback mEventCallback

Callback provided by EngineManager

mActiveUiRequest

protected ServiceUiRequest mActiveUiRequest

Current UI Request if one is active, otherwise null.

See Also:

ServiceUiRequest

mCurrentTimeout

protected volatile java.lang.Long mCurrentTimeout

Current timeout based on current time in milliseconds if one is pending, otherwise null.

mCommsResponseOutstanding

private java.lang.Boolean mCommsResponseOutstanding

true if a Comms response is waiting in the comms response queue for processing, false otherwise.

mActiveRequestId

private java.lang.Integer mActiveRequestId

Set by the setReqId(int) function to store the request ID when a engine makes a request to the server. All responses received will then be filtered by this value automatically inside the processCommsInQueue() function.

mUiRequestOutstanding

private boolean mUiRequestOutstanding

true if a UI request is waiting in the UI request queue for processing, false otherwise.

mDeactivated

private boolean mDeactivated

true if the engine is deactivated (for test purposes), false otherwise.

mMutex

private java.lang.Object mMutex

mutex for thread synchronization

resetDone

private boolean resetDone

Flag set when a request to reset the engine is made and the engine has performed its reset tasks.

mUiQueue

private final java.util.concurrent.ConcurrentLinkedQueue<BaseEngine.UiQueueItem> mUiQueue

Used to implement the UI request queue.

Constructor Detail

BaseEngine

public BaseEngine(BaseEngine.IEngineEventCallback eventCallback)

Public constructor.

Parameters:

eventCallback - This interface must be implemented by the engine client

Method Detail

getNextRunTime

public abstract long getNextRunTime()

Return the absolute time in milliseconds when the engine needs to run (based on System.currentTimeMillis). (Maybe add currentTime in the future to use as the current time, to enable JUnit tests to validate timeout functionality).

Returns:

-1 never needs to run, 0 needs to run as soon as possible, CurrentTime + 60000 to run in 1 minute, etc.

run

public abstract void run()

Do some work but anything that takes longer than 1 second must be broken up. (Maybe add currentTime as parameter, to enable JUnit tests to validate timeout functionality)

onCreate

public abstract void onCreate()

This will be called immediately after creation.

onDestroy

public abstract void onDestroy()

This will be called just before the engine is shutdown.

addUiRequestToQueue

public void addUiRequestToQueue(ServiceUiRequest request,
                                java.lang.Object data)

Helper function for use by the derived engine class to add a UI request to the queue. This will be run from the UI thread

engineId

public EngineManager.EngineId engineId()

Return id for this engine.

Returns:

EngineId identifying concrete engine

fetchNextUiRequest

private BaseEngine.UiQueueItem fetchNextUiRequest()

Helper function for use by the derived engine class to fetch the next UI request from the queue. Returns null if the queue is empty.

isUiRequestOutstanding

protected boolean isUiRequestOutstanding()

Helper function to determine if there is any work outstanding in the UI request queue. Returns false if the queue is empty.

onUiRequestComplete

private void onUiRequestComplete(ServiceUiRequest request,
                                 ServiceStatus status,
                                 java.lang.Object data)

Helper function which must be called to complete a UI request. Normally this will not be called directly by the derived engine implementation. Instead the completeUiRequest function should be used.

Parameters:

request - The request Id to complete

status - The ServiceStatus code

data - Response data (object type is request specific)

processCommsResponse

protected abstract void processCommsResponse(ResponseQueue.Response resp)

The derived engine implementation must call the processCommsInQueue() function (normally from within the run() implementation), otherwise this will not be called. This function is called for each Comms response that arrives on the in queue.

Parameters:

resp - The comms response

processUiRequest

protected abstract void processUiRequest(ServiceUiRequest requestId,
                                         java.lang.Object data)

The derived engine implementation must call the processUiQueue() function (normally from within the run() implementation), otherwise this will not be called. This function is called for each UI request that arrives on the queue. It should start processing the request. If this function takes longer than 1 second to complete, it should be broken up. Once a request is finished the processUiRequest function must be called.

Parameters:

requestId - The UI request ID

data - Request data (object type is request specific)

onTimeoutEvent

protected abstract void onTimeoutEvent()

The derived engine implementation must call the processTimeout() function (normally from within the run() implementation), otherwise this will not be called. This function will be called when a timeout occurs (started by setTimeout and cancelled by clearTimeout). If this function takes longer than 1 second to complete it should be broken up.

onCommsInMessage

public void onCommsInMessage()

Called by the EngineManager when a comms response is received. Will set the response outstanding flag and kick the worker thread.

isCommsResponseOutstanding

protected boolean isCommsResponseOutstanding()

Should be called by the getNextRunTime() and run() functions to check if there are any comms responses waiting to be processed.

Returns:

true if there are 1 or more responses to process.

processCommsInQueue

protected boolean processCommsInQueue()

Should be called by the run() function to process the comms in queue. Calling this function will result in the processCommsResponse function being called once. The derived engine implementation should do its processing of each response in that function. If the engine set the request ID using the setReqId function then messages which don't match will be taken off the queue and deleted.

Returns:

true if a response was taken from the queue and processed.

genericHandleResponseType

public static ServiceStatus genericHandleResponseType(java.lang.String requiredResp,
                                                      java.util.List<BaseDataType> data)

A helper function for the derived engine implementation to use. It checks the returned comms response data against the expected type and handles all common error cases.

Parameters:

requiredResp - The expected type name

data - The data received from the comms response

Returns:

SUCCESS if the first element in the list is of the expected type, ERROR_COMMS if the first element in the list is an unexpected type, ERROR_COMMS_BAD_RESPONSE if data is not valid for specyfied type or null otherwise if the data is of type ZError, a suitable error code.

processUiQueue

protected boolean processUiQueue()

Should be called by the run() function to process the UI request queue. Calling this function will result in the processUiRequest function being called once and this will be set to the active request. The derived engine implementation should do its processing of each request in that function. Note the engine must not process any more requests until the current one has been completed.

Returns:

true if a response was taken from the queue and processed.

completeUiRequest

protected void completeUiRequest(ServiceStatus status)

A helper function that can be called by the derived engine implementation to complete the current UI request.

Parameters:

status - The result of the request

onRequestComplete

protected abstract void onRequestComplete()

This function must be implemented in the derived engine implementation. It can do any post-request complete cleanup.

completeUiRequest

protected void completeUiRequest(ServiceStatus status,
                                 java.lang.Object data)

A helper function that can be called by the derived engine implementation to complete the current UI request.

Parameters:

status - The result of the request

data - Response data (object type is request specific)

setTimeout

protected void setTimeout(long timeoutVal)

Helper function that can be called by the derived engine implementation to start an asynchronous timer. This will only work when: 1) getCurrentTimeout() is called inside the getNextRunTime() function. 2) The processTimeout() is called in the run() function 3) The onTimeoutEvent() is implemented to handle the timeout event.

Parameters:

timeoutVal - The timeout value (in milliseconds)

clearTimeout

protected void clearTimeout()

Cancels the current timer (has no effect if the timer was not active).

getCurrentTimeout

protected long getCurrentTimeout()

The result of this function must be returned by getNextRunTime() instead of -1 for the timer to work.

Returns:

The required next run time (in milliseconds) or -1 if no timer is active

processTimeout

protected boolean processTimeout()

This function must be called by run() in the derived engine implementation for the timer to work.

Returns:

true if the timeout was processed

deactivateEngine

protected void deactivateEngine()

Called by the framework to deactivate the engine. This allows engines to be deactivated by modifying the Settings (so features can be disabled in the build).

isDeactivated

public boolean isDeactivated()

Called by the framework to determine if the engine should run.

setReqId

protected boolean setReqId(int reqId)

Called by engines when an API call is made to ensure that the response processed matches the request. If this function is not called the framework will send all responses to the engine.

emptyUiRequestQueue

protected void emptyUiRequestQueue()

Called by engines in the UI thread to cancel all UI requests. The engine should ensure that the active UI request is completed (if necessary) before calling this function.

onReset

public void onReset()

Engines can override this function to do any special handling when a reset is needed. Note: if overriden, the engine shall call the super implementation when the reset is done.

setReset

private void setReset(boolean value)

Sets the reset flag.

Parameters:

value - the reset state of the engine, true if reset, false if not.

getReset

boolean getReset()

Gets the reset flag.

Returns:

true if the engine is reset, false if not

clearReset

void clearReset()

Clears the reset flag.