org.itsnat.core

Interface ItsNatTimer

public interface ItsNatTimer

Utility interface to manage scheduled remote tasks (timer tasks). An ItsNat scheduled or timer task is a task executed following a time based schedule, when the task must be executed the client sends an event received by a user defined listener (the task to execute).

The ItsNatTimer features and API are inspired in java.util.Timer but the main differences are that timer events are sent by the client and the server does not use any special thread to schedule the event sequence.

Note: big documentation parts of this interface are copied from java.util.Timer.

Author:

Jose Maria Arranz Santamaria

See Also:

ClientDocument.createItsNatTimer()

Method Summary

Methods

Modifier and Type	Method and Description
void	cancel() Terminates this timer manager, discarding any currently scheduled tasks.
ClientDocument	getClientDocument() Returns the parent client document this object belongs to.
ItsNatDocument	getItsNatDocument() Returns the parent document this object belongs to.
ItsNatTimerHandle	schedule(EventTarget target, EventListener task, Date time) Schedules the specified task (the EventListener object) for execution at the specified time.
ItsNatTimerHandle	schedule(EventTarget target, EventListener task, Date time, int commMode, ParamTransport[] extraParams, String preSendCode, long eventTimeout) Schedules the specified task (the EventListener object) for execution at the specified time.
ItsNatTimerHandle	schedule(EventTarget target, EventListener task, Date firstTime, long period) Schedules the specified task for repeated fixed-delay execution, beginning at the specified time.
ItsNatTimerHandle	schedule(EventTarget target, EventListener task, Date firstTime, long period, int commMode, ParamTransport[] extraParams, String preSendCode, long eventTimeout) Schedules the specified task for repeated fixed-delay execution, beginning at the specified time.
ItsNatTimerHandle	schedule(EventTarget target, EventListener task, long delay) Schedules the specified task for execution after the specified delay.
ItsNatTimerHandle	schedule(EventTarget target, EventListener task, long delay, int commMode, ParamTransport[] extraParams, String preSendCode, long eventTimeout) Schedules the specified task for execution after the specified delay.
ItsNatTimerHandle	schedule(EventTarget target, EventListener task, long delay, long period) Schedules the specified task for repeated fixed-delay execution, beginning after the specified delay.
ItsNatTimerHandle	schedule(EventTarget target, EventListener task, long delay, long period, int commMode, ParamTransport[] extraParams, String preSendCode, long eventTimeout) Schedules the specified task for repeated fixed-delay execution, beginning after the specified delay.
ItsNatTimerHandle	scheduleAtFixedRate(EventTarget target, EventListener task, Date firstTime, long period) Schedules the specified task for repeated fixed-rate execution, beginning at the specified time.
ItsNatTimerHandle	scheduleAtFixedRate(EventTarget target, EventListener task, Date firstTime, long period, int commMode, ParamTransport[] extraParams, String preSendCode, long eventTimeout) Schedules the specified task for repeated fixed-rate execution, beginning at the specified time.
ItsNatTimerHandle	scheduleAtFixedRate(EventTarget target, EventListener task, long delay, long period) Schedules the specified task for repeated fixed-rate execution, beginning after the specified delay.
ItsNatTimerHandle	scheduleAtFixedRate(EventTarget target, EventListener task, long delay, long period, int commMode, ParamTransport[] extraParams, String preSendCode, long eventTimeout) Schedules the specified task for repeated fixed-rate execution, beginning after the specified delay.

Method Detail

getClientDocument

ClientDocument getClientDocument()

Returns the parent client document this object belongs to.

Returns:

the parent client document.

getItsNatDocument

ItsNatDocument getItsNatDocument()

Returns the parent document this object belongs to.

Returns:

the parent document.

cancel

void cancel()

Terminates this timer manager, discarding any currently scheduled tasks. Does not interfere with a currently executing task (if it exists). Once a timer has been terminated no more tasks may be scheduled on it.

Note that calling this method from within the EventListener.handleEvent(Event) method of a timer task that was invoked by this timer absolutely guarantees that the ongoing task execution is the last task execution that will ever be performed by this timer.

This method may be called repeatedly; the second and subsequent calls have no effect.

schedule

ItsNatTimerHandle schedule(EventTarget target,
                         EventListener task,
                         Date time,
                         int commMode,
                         ParamTransport[] extraParams,
                         String preSendCode,
                         long eventTimeout)

Schedules the specified task (the EventListener object) for execution at the specified time. If the time is in the past, the task is scheduled for immediate execution.

When the scheduled task is fully finished or cancelled is automatically unregistered.

Parameters:

target - optional target element usually useful along with ParamTransport objects. May be null.

task - task to be scheduled. It receives timer events.

time - time at which task is to be executed.

commMode - communication mode.

extraParams - optional client to server data transport and synchronization rules. May be null.

preSendCode - custom JavaScript code to execute before an event of this listener type is fired. May be null.

eventTimeout - the timeout of asynchronous events sent by the timer. If negative no timeout is defined.

Returns:

a timer handle, this object represents the scheduled task.

schedule

ItsNatTimerHandle schedule(EventTarget target,
                         EventListener task,
                         Date time)

Schedules the specified task (the EventListener object) for execution at the specified time. If the time is in the past, the task is scheduled for immediate execution.

The default communication mode is used.

Current implementation does the following:

        int commMode = getItsNatDocument().getCommMode();
        long eventTimeout = getItsNatDocument().getEventTimeout();
        return schedule(target,task,time,commMode,null,null,eventTimeout);
 

Parameters:

target - optional target element usually useful along with ParamTransport objects. May be null.

task - task to be scheduled. It receives timer events.

time - time at which task is to be executed.

Returns:

a timer handle, this object represents the scheduled task.

See Also:

schedule(EventTarget,EventListener,Date,int,ParamTransport[],String,long)

schedule

ItsNatTimerHandle schedule(EventTarget target,
                         EventListener task,
                         Date firstTime,
                         long period,
                         int commMode,
                         ParamTransport[] extraParams,
                         String preSendCode,
                         long eventTimeout)

Schedules the specified task for repeated fixed-delay execution, beginning at the specified time. Subsequent executions take place at approximately regular intervals, separated by the specified period.

In fixed-delay execution, each execution is scheduled relative to the actual execution time of the previous execution. If an execution is delayed for any reason, subsequent executions will be delayed as well. In the long run, the frequency of execution will generally be slightly lower than the reciprocal of the specified period.

Fixed-delay execution is appropriate for recurring activities that require "smoothness." In other words, it is appropriate for activities where it is more important to keep the frequency accurate in the short run than in the long run. This includes most animation tasks, such as blinking a cursor at regular intervals. It also includes tasks wherein regular activity is performed in response to human input, such as automatically repeating a character as long as a key is held down.

When the scheduled task is fully finished or cancelled is automatically unregistered.

Parameters:

target - optional target element usually useful along with ParamTransport objects. May be null.

task - task to be scheduled.

firstTime - first time at which task is to be executed.

period - time in milliseconds between successive task executions.

commMode - communication mode.

extraParams - optional client to server data transport and synchronization rules. May be null.

preSendCode - custom JavaScript code to execute before an event of this listener type is fired. May be null.

eventTimeout - the timeout of asynchronous events sent by the timer. If negative no timeout is defined.

Returns:

a timer handle, this object represents the scheduled task.

schedule

ItsNatTimerHandle schedule(EventTarget target,
                         EventListener task,
                         Date firstTime,
                         long period)

Schedules the specified task for repeated fixed-delay execution, beginning at the specified time. Subsequent executions take place at approximately regular intervals, separated by the specified period.

The default communication mode is used.

Current implementation does the following:

        int commMode = getItsNatDocument().getCommMode();
        long eventTimeout = getItsNatDocument().getEventTimeout();
        return schedule(target,task,firstTime,period,commMode,null,null,eventTimeout);
 

Parameters:

target - optional target element usually useful along with ParamTransport objects. May be null.

task - task to be scheduled.

firstTime - first time at which task is to be executed.

period - time in milliseconds between successive task executions.

Returns:

a timer handle, this object represents the scheduled task.

See Also:

schedule(org.w3c.dom.events.EventTarget,org.w3c.dom.events.EventListener,Date,long,int,org.itsnat.core.event.ParamTransport[],String,long)

schedule

ItsNatTimerHandle schedule(EventTarget target,
                         EventListener task,
                         long delay,
                         int commMode,
                         ParamTransport[] extraParams,
                         String preSendCode,
                         long eventTimeout)

Schedules the specified task for execution after the specified delay.

Parameters:

target - optional target element usually useful along with ParamTransport objects. May be null.

task - task to be scheduled.

delay - delay in milliseconds before task is to be executed.

commMode - communication mode.

extraParams - optional client to server data transport and synchronization rules. May be null.

preSendCode - custom JavaScript code to execute before an event of this listener type is fired. May be null.

eventTimeout - the timeout of asynchronous events sent by the timer. If negative no timeout is defined.

Returns:

a timer handle, this object represents the scheduled task.

schedule

ItsNatTimerHandle schedule(EventTarget target,
                         EventListener task,
                         long delay)

Schedules the specified task for execution after the specified delay.

The default communication mode is used.

Current implementation does the following:

        int commMode = getItsNatDocument().getCommMode();
        long eventTimeout = getItsNatDocument().getEventTimeout();
        return schedule(target,task,delay,commMode,null,null,eventTimeout);
 

Parameters:

target - optional target element usually useful along with ParamTransport objects. May be null.

task - task to be scheduled.

delay - delay in milliseconds before task is to be executed.

Returns:

a timer handle, this object represents the scheduled task.

See Also:

schedule(org.w3c.dom.events.EventTarget,org.w3c.dom.events.EventListener,long,int,org.itsnat.core.event.ParamTransport[],String,long)

schedule

ItsNatTimerHandle schedule(EventTarget target,
                         EventListener task,
                         long delay,
                         long period,
                         int commMode,
                         ParamTransport[] extraParams,
                         String preSendCode,
                         long eventTimeout)

Schedules the specified task for repeated fixed-delay execution, beginning after the specified delay. Subsequent executions take place at approximately regular intervals separated by the specified period.

In fixed-delay execution, each execution is scheduled relative to the actual execution time of the previous execution. If an execution is delayed for any reason, subsequent executions will be delayed as well. In the long run, the frequency of execution will generally be slightly lower than the reciprocal of the specified period.

Fixed-delay execution is appropriate for recurring activities that require "smoothness." In other words, it is appropriate for activities where it is more important to keep the frequency accurate in the short run than in the long run. This includes most animation tasks, such as blinking a cursor at regular intervals. It also includes tasks wherein regular activity is performed in response to human input, such as automatically repeating a character as long as a key is held down.

When the scheduled task is fully finished or cancelled is automatically unregistered.

Parameters:

target - optional target element usually useful along with ParamTransport objects. May be null.

task - task to be scheduled.

delay - delay in milliseconds before task is to be executed.

period - time in milliseconds between successive task executions.

commMode - communication mode.

extraParams - optional client to server data transport and synchronization rules. May be null.

preSendCode - custom JavaScript code to execute before an event of this listener type is fired. May be null.

eventTimeout - the timeout of asynchronous events sent by the timer. If negative no timeout is defined.

Returns:

a timer handle, this object represents the scheduled task.

schedule

ItsNatTimerHandle schedule(EventTarget target,
                         EventListener task,
                         long delay,
                         long period)

Schedules the specified task for repeated fixed-delay execution, beginning after the specified delay. Subsequent executions take place at approximately regular intervals separated by the specified period.

The default communication mode is used.

Current implementation does the following:

        int commMode = getItsNatDocument().getCommMode();
        long eventTimeout = getItsNatDocument().getEventTimeout();
        return schedule(target,task,delay,period,commMode,null,null,eventTimeout);
 

Parameters:

target - optional target element usually useful along with ParamTransport objects. May be null.

task - task to be scheduled.

delay - delay in milliseconds before task is to be executed.

period - time in milliseconds between successive task executions.

Returns:

a timer handle, this object represents the scheduled task.

scheduleAtFixedRate

ItsNatTimerHandle scheduleAtFixedRate(EventTarget target,
                                    EventListener task,
                                    Date firstTime,
                                    long period,
                                    int commMode,
                                    ParamTransport[] extraParams,
                                    String preSendCode,
                                    long eventTimeout)

Schedules the specified task for repeated fixed-rate execution, beginning at the specified time. Subsequent executions take place at approximately regular intervals, separated by the specified period.

In fixed-rate execution, each execution is scheduled relative to the scheduled execution time of the initial execution. If an execution is delayed for any reason, two or more executions will occur in rapid succession to "catch up." In the long run, the frequency of execution will be exactly the reciprocal of the specified period.

Fixed-rate execution is appropriate for recurring activities that are sensitive to absolute time, such as ringing a chime every hour on the hour, or running scheduled maintenance every day at a particular time. It is also appropriate for recurring activities where the total time to perform a fixed number of executions is important, such as a countdown timer that ticks once every second for ten seconds. Finally, fixed-rate execution is appropriate for scheduling multiple repeating timer tasks that must remain synchronized with respect to one another.

When the scheduled task is fully finished or cancelled is automatically unregistered.

Parameters:

target - optional target element usually useful along with ParamTransport objects. May be null.

task - task to be scheduled.

firstTime - First time at which task is to be executed.

period - time in milliseconds between successive task executions.

commMode - communication mode.

extraParams - optional client to server data transport and synchronization rules. May be null.

preSendCode - custom JavaScript code to execute before an event of this listener type is fired. May be null.

eventTimeout - the timeout of asynchronous events sent by the timer. If negative no timeout is defined.

Returns:

a timer handle, this object represents the scheduled task.

scheduleAtFixedRate

ItsNatTimerHandle scheduleAtFixedRate(EventTarget target,
                                    EventListener task,
                                    Date firstTime,
                                    long period)

Schedules the specified task for repeated fixed-rate execution, beginning at the specified time. Subsequent executions take place at approximately regular intervals, separated by the specified period.

The default communication mode is used.

Current implementation does the following:

        int commMode = getItsNatDocument().getCommMode();
        long eventTimeout = getItsNatDocument().getEventTimeout();
        return scheduleAtFixedRate(target,task,firstTime,period,commMode,null,null,eventTimeout);
 

Parameters:

target - optional target element usually useful along with ParamTransport objects. May be null.

task - task to be scheduled.

firstTime - First time at which task is to be executed.

period - time in milliseconds between successive task executions.

Returns:

a timer handle, this object represents the scheduled task.

scheduleAtFixedRate

ItsNatTimerHandle scheduleAtFixedRate(EventTarget target,
                                    EventListener task,
                                    long delay,
                                    long period,
                                    int commMode,
                                    ParamTransport[] extraParams,
                                    String preSendCode,
                                    long eventTimeout)

Schedules the specified task for repeated fixed-rate execution, beginning after the specified delay. Subsequent executions take place at approximately regular intervals, separated by the specified period.

In fixed-rate execution, each execution is scheduled relative to the scheduled execution time of the initial execution. If an execution is delayed for any reason, two or more executions will occur in rapid succession to "catch up." In the long run, the frequency of execution will be exactly the reciprocal of the specified period.

Fixed-rate execution is appropriate for recurring activities that are sensitive to absolute time, such as ringing a chime every hour on the hour, or running scheduled maintenance every day at a particular time. It is also appropriate for recurring activities where the total time to perform a fixed number of executions is important, such as a countdown timer that ticks once every second for ten seconds. Finally, fixed-rate execution is appropriate for scheduling multiple repeating timer tasks that must remain synchronized with respect to one another.

When the scheduled task is fully finished or cancelled is automatically unregistered.

Parameters:

task - task to be scheduled.

delay - delay in milliseconds before task is to be executed.

period - time in milliseconds between successive task executions.

commMode - communication mode.

extraParams - optional client to server data transport and synchronization rules. May be null.

preSendCode - custom JavaScript code to execute before an event of this listener type is fired. May be null.

eventTimeout - the timeout of asynchronous events sent by the timer. If negative no timeout is defined.

Returns:

a timer handle, this object represents the scheduled task.

scheduleAtFixedRate

ItsNatTimerHandle scheduleAtFixedRate(EventTarget target,
                                    EventListener task,
                                    long delay,
                                    long period)

Schedules the specified task for repeated fixed-rate execution, beginning after the specified delay. Subsequent executions take place at approximately regular intervals, separated by the specified period.

The default communication mode is used.

Current implementation does the following:

        int commMode = getItsNatDocument().getCommMode();
        long eventTimeout = getItsNatDocument().getEventTimeout();
        return scheduleAtFixedRate(target,task,delay,period,commMode,null,null,eventTimeout);
 

Parameters:

task - task to be scheduled.

delay - delay in milliseconds before task is to be executed.

period - time in milliseconds between successive task executions.

Returns:

a timer handle, this object represents the scheduled task.