oracle.panama.lbevent
Interface LBEventAgent

public interface LBEventAgent

A Location Event Agent class. The agent is used to activate/deactivate location based conditions, check whehter a specific condition is satisfied and process the incoming location based event by starting the location event listeners. When a location event listener receives a location based event, it invokes the location event handler to process the event.

See Also:

oracle.panana.lbevent.LBEventHandler

Field Summary

static int	MAX_AGENT_NAME_LEN The maximum length of the name of an agent.
static java.lang.String	RESULT_CONDITION_DELETED If a condition evluation result is RESULT_CONDITION_DELETED, it means the condition has been deleted.
static java.lang.String	RESULT_INVALIDMSID If a condition evaluation result is RESULT_INVALIDMSID, it means at least one target's MSID can not be recoginized by any of the working MP provider in the system.
static java.lang.String	RESULT_INVALIDREGIONID If a condition evluation result is RESULT_INVALIDREGIONID, it means at least one region id in the condition can not be recoginized by the system.
static java.lang.String	RESULT_NOT_AVAILABLE If a condition evaluation result is RESULT_NOT_AVAILABLE, it means the location event server has not generated the evaluation result for the condition.
static java.lang.String	RESULT_NOT_SATISFIED If a condition evaluation result is RESULT_NOT_SATISFIED, it means that the condition associated with the event is not satisfied.
static java.lang.String	RESULT_PRIVACYCHECK_FAILED If a condition evaluation result is RESULT_PRIVACYCHECK_FAILED, it means the condition associated with the event is no longer evaluated because the condition does not pass the location privacy checking.
static java.lang.String	RESULT_SATISFIED If the result is RESULT_STATISFIED, it means the condition associated with the event is satisfied.
static java.lang.String	RESULT_USER_SUSPENDED If a condition evaluation result is RESULT_USER_SUSPENDED, it means the location based condition is suspended because the creator or one of the target users is suspended.

Method Summary

void	activateCondition(LBCondition condition, java.lang.String evalMode, java.util.Calendar exprTime, java.lang.String recipient, boolean silent) activate a LBCondition.
java.lang.String	checkStatusNoWait(LBCondition condition) Check whether the condition is satisfied or not using the default tolerance.
java.lang.String	checkStatusNoWait(LBCondition condition, int tolerance) Check whether the condition is satisfied or not.
void	deActivateCondition(LBCondition condition) deactivate a condition.
boolean	isActive() Test whether the agent is still active.
java.lang.String	isSatisfied(LBCondition condition) Check whether the condition is satisfied or not using the default tolerance.
java.lang.String	isSatisfied(LBCondition condition, int tolerance) Check whether the condition is satisfied or not.
void	registerLBEventHandler(LBEventHandler handler) Register a handler to handle the location based event.
void	startListenerThread() Start listener threads to listen to the location based events using the default number of listeners.
void	startListenerThread(int numberOfThreads) Start listener threads to listen to the location based events.
void	stopListenerThread() Stop all the listener threads of this agent
void	terminate() terminate an agent.

Field Detail

RESULT_SATISFIED

public static final java.lang.String RESULT_SATISFIED

If the result is RESULT_STATISFIED, it means the condition associated with the event is satisfied.

See Also:

Constant Field Values

RESULT_NOT_SATISFIED

public static final java.lang.String RESULT_NOT_SATISFIED

If a condition evaluation result is RESULT_NOT_SATISFIED, it means that the condition associated with the event is not satisfied.

See Also:

Constant Field Values

RESULT_INVALIDMSID

public static final java.lang.String RESULT_INVALIDMSID

If a condition evaluation result is RESULT_INVALIDMSID, it means at least one target's MSID can not be recoginized by any of the working MP provider in the system. The MSID may be an invalid one or the provider that can process this MSID is down.

See Also:

Constant Field Values

RESULT_CONDITION_DELETED

public static final java.lang.String RESULT_CONDITION_DELETED

If a condition evluation result is RESULT_CONDITION_DELETED, it means the condition has been deleted. This can happen when the one or more objects referred by this condition are deleted.

See Also:

Constant Field Values

RESULT_INVALIDREGIONID

public static final java.lang.String RESULT_INVALIDREGIONID

If a condition evluation result is RESULT_INVALIDREGIONID, it means at least one region id in the condition can not be recoginized by the system.

See Also:

Constant Field Values

RESULT_PRIVACYCHECK_FAILED

public static final java.lang.String RESULT_PRIVACYCHECK_FAILED

If a condition evaluation result is RESULT_PRIVACYCHECK_FAILED, it means the condition associated with the event is no longer evaluated because the condition does not pass the location privacy checking.

See Also:

Constant Field Values

RESULT_NOT_AVAILABLE

public static final java.lang.String RESULT_NOT_AVAILABLE

If a condition evaluation result is RESULT_NOT_AVAILABLE, it means the location event server has not generated the evaluation result for the condition. This result may be returned when the no wait pull query is issued and the server does not have a result ready.

See Also:

Constant Field Values

RESULT_USER_SUSPENDED

public static final java.lang.String RESULT_USER_SUSPENDED

If a condition evaluation result is RESULT_USER_SUSPENDED, it means the location based condition is suspended because the creator or one of the target users is suspended.

See Also:

Constant Field Values

MAX_AGENT_NAME_LEN

public static final int MAX_AGENT_NAME_LEN

The maximum length of the name of an agent.

See Also:

Constant Field Values

Method Detail

activateCondition

public void activateCondition(LBCondition condition,
                              java.lang.String evalMode,
                              java.util.Calendar exprTime,
                              java.lang.String recipient,
                              boolean silent)
                       throws LBEventException

activate a LBCondition. If the agent is no longer active, a LBEventException is thrown.

Parameters:

condition - the condition to be activated

evalMode - the evaluation mode for this activation. If evalMode is null, the default evaluation mode is used. If evalMode is null and default evaluation mode is not set, an IllegalArgumentException is thrown.

exprTime - the expiration time for this evaluation. If the evalMode is LBCondition.MODE_REPEAT either exprTime or the default expiration time for the condition should be set, otherwise an IllegalArgumentException is thrown.

recipient - the name of the recipient agent

silent - if silent is true, the evaluation of this condition does not generate any event

LBEventException

deActivateCondition

public void deActivateCondition(LBCondition condition)
                         throws LBEventException

deactivate a condition. If the agent is no longer active or the condition is not activated, a LBEventException is thrown.

Parameters:

condition - the condition to be deactived

LBEventException

isSatisfied

public java.lang.String isSatisfied(LBCondition condition)
                             throws LBEventException

Check whether the condition is satisfied or not using the default tolerance. The method will block the calling thread until a result is obtained or an exception is thrown.

Parameters:

condition - the condition whose evaluation result is to be obtained.

Returns:

The currentcondition evaluation result. @see LBCondition for possible results

Throws:

if - an agent with the same agent name has already issued the poll request on the same condition and is waiting for the result, a new request will cause a LBEventException thrown. If the agent has been terminated, a LBEventException is thrown.

LBEventException

isSatisfied

public java.lang.String isSatisfied(LBCondition condition,
                                    int tolerance)
                             throws LBEventException

Check whether the condition is satisfied or not. The method will block the calling thread until a result is obtained or an exception is thrown.

Parameters:

condition - The condition whose evaluation result is to be obtained.

tolerance - Specifies the requirements on the freshness of the result. The value is specified in SECONDs. For example, if tolerance is 60, it means that the result generated during the previous minute is acceptable.

Returns:

The currentcondition evaluation result. @see LBCondition for possible results

Throws:

if - an agent with the same agent name has already issued the poll request on the same condition and is waiting for the result, a new request will cause a LBEventException thrown. If the agent has been terminated, a LBEventException is thrown.

LBEventException

checkStatusNoWait

public java.lang.String checkStatusNoWait(LBCondition condition)
                                   throws LBEventException

Check whether the condition is satisfied or not using the default tolerance. The method will not wait for the result if there is no result ready.

Parameters:

condition - The condition whose evaluation result is to be obtained.

Returns:

if the condition is satisfied, RESULT_SATISFIED is returned. if the condition is not satisfied,RESULT_NOT_SATISFIED is returned. if there is no result availabe,RESULT_NOT_AVAILABLE is returned.

Throws:

If - the agent has been terminated, a LBEventException is thrown.

LBEventException

checkStatusNoWait

public java.lang.String checkStatusNoWait(LBCondition condition,
                                          int tolerance)
                                   throws LBEventException

Check whether the condition is satisfied or not. The method will not wait for the result if there is no result ready.

Parameters:

condition - The condition whose evaluation result is to be obtained.

tolerance - Specifies the requirements on the freshness of the result. The value is specified in SECONDs. For example, if tolerance is 60, it means that the result generated during the previous minute is acceptable. Tolerance should not be 0.

Returns:

if the condition is satisfied, RESULT_SATISFIED is returned. if the condition is not satisfied,RESULT_NOT_SATISFIED is returned. if there is no result availabe,RESULT_NOT_AVAILABLE is returned.

Throws:

If - the agent has been terminated, a LBEventException is thrown.

LBEventException

registerLBEventHandler

public void registerLBEventHandler(LBEventHandler handler)

Register a handler to handle the location based event.

startListenerThread

public void startListenerThread(int numberOfThreads)
                         throws LBEventException

Start listener threads to listen to the location based events.

LBEventException

startListenerThread

public void startListenerThread()
                         throws LBEventException

Start listener threads to listen to the location based events using the default number of listeners.

LBEventException

stopListenerThread

public void stopListenerThread()

Stop all the listener threads of this agent

terminate

public void terminate()
               throws LBEventException

terminate an agent. The agent will be comes inactive and can no longer be used. The terminate method release the resources held by the agent. It frees the name used by the agent so that the name can be used by other agents. It is recommended that the terminate method is called when the agent is no longer needed.

LBEventException

isActive

public boolean isActive()

Test whether the agent is still active.