org.vishia.event

Class TimeOrder

java.lang.Object

java.util.EventObject

org.vishia.event.EventWithDst

org.vishia.event.EventTimeout

org.vishia.event.TimeOrder

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

FileRemoteProgressTimeOrder, OrderForList

public abstract class TimeOrder
extends EventTimeout

This is the base class for time orders. To define a time order a derived class of this should be written which overrides the method executeOrder(). An instance of this class can be created statically as persistent reference or on demand with new TimeOrder#TimeOrder(String, EventTimerThread). The EventTimerThread should be existing as instance before an instance of this class is created.

Pattern for application:

 EventThread thread = new EventThread("name");
 ...
 //a time order as inner anonymous class:
 EventTimeOrder order = new EventTimeOrder("name", thread) {
   QOverride protected void executeOrder(){
     ...code for time order
   }
 }
 ...
 thread.start();
 order.activate(100); //the order will be executed in the thread in 100 ms.
 

An EventTimeOrder can be enqueued in the EventThread but executed in another thread. It uses an EventConsumer, see TestTimeOrder, with the following pattern:

  
 private static class EnqueueInGraphicThread implements EventConsumer {
   QOverride public int processEvent(EventObject ev)
   { execThread.queueOrders.put((< EventTimeOrder >)ev);  //casting admissible because special using.
     return mEventConsumed;
   }
 }
 

This class is designated as EventObject because it can be used as event immediately after or independent whether it is handled by the timer.

• Constructors: TimeOrder#TimeOrder(String, EventTimerThread), TimeOrder#TimeOrder(String, EventConsumer, EventTimerThread), TimeOrder(String) .
• methods to activate from EventTimeout: EventTimeout.activate(int), EventTimeout.activateAt(long), EventTimeout.activateAt(long, long)
• Remove a currently timeout: EventTimeout.deactivate()
• Check from EventTimeout: EventTimeout.timeExecution(), EventTimeout.timeExecutionLatest(), EventTimeout.timeToExecution() EventTimeout.used()
• Check: getCtDone(int)
• Execute: doExecute() will be called from the EventTimerThread, only call by application in a special thread.
• Wait for execution in another thread: awaitExecution(int, int).
• see EventTimeout.
• see EventTimerThread
• see StateMachine

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
private int	ctDone
int	dbgctDone It is counted only.
java.lang.String	name The name of the dispatch worker, used for debug at least.
private boolean	reqCtDone True if a thread waits, see awaitExecution(int, int).
private static long	serialVersionUID
static java.lang.String	version Version and history.

Fields inherited from class org.vishia.event.EventTimeout

dbgctWindup, timeExecution, timeExecutionLatest

Fields inherited from class org.vishia.event.EventWithDst

bAwaitReserve, ctConsumed, dateCreation, dateOrder, evDst, evDstThread, orderId, stateOfEvent, toStringDateFormat

Fields inherited from class java.util.EventObject

source

Constructor Summary

Constructors

Constructor and Description
TimeOrder(java.lang.String name)
TimeOrder(java.lang.String name, EventConsumer dst, EventTimerThread_ifc thread) Initializes an time order for usage.
TimeOrder(java.lang.String name, EventTimerThread_ifc thread) Initializes an time order for usage.

Method Summary

Modifier and Type	Method and Description
boolean	awaitExecution(int ctDoneRequested, int timeout) Waits for execution in any other thread.
void	doExecute() Executes and sets the execute state to false.
protected abstract void	executeOrder() Executes the order.
int	getCtDone(int setCtDone) Gets the information, how many times the routine is executed.
java.lang.String	getStateInfo() Returns the state of the consumer in a manual readable form.
java.lang.String	toString() Returns the name of this to show it for debugging.

Methods inherited from class org.vishia.event.EventTimeout

activate, activateAt, activateAt, deactivate, doTimeElapsed, timeExecution, timeExecutionLatest, timeToExecution, used

Methods inherited from class org.vishia.event.EventWithDst

consumed, dateCreation, evDst, getDst, getDstThread, hasDst, isOccupied, notifyDequeued, occupy, occupy, occupy, occupyRecall, occupyRecall, occupyRecall, occupyRecall, relinquish, removeFromQueue, sendEvent, setDst, setOrderId, XXXdonotRelinquish

Methods inherited from class java.util.EventObject

getSource

Methods inherited from class java.lang.Object

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

Field Detail

serialVersionUID

private static final long serialVersionUID

See Also:

Constant Field Values

version

public static final java.lang.String version

Version and history.

• 2015-05-03 Hartmut on awaitExecution(int, int) wait if the thread is busy. It should be done especially if the order is in debug. Not ready checked yet whether it is well running.
• 2015-01-10 Hartmut renamed from OrderForList
• 2014-02-23 Hartmut removed from the component srcJava_vishiaGui to the srcJava_vishiaBase because it is commonly able to use.
• 2012-02-14 Hartmut corr: #addToList(GralGraphicThread, int): For time saving: If an instance is added already and its new execution time is up to 5 ms later, nothing is done. It saves time for more as one call of this routine in a fast loop.
• 2012-02-14 Hartmut corr: It was happen that an instance was designated with #bAdded==true but it wasn't added, Therefore on #addToList(GralGraphicThread, int) it is removed from list and added newly. It is more save.
• 2012-01-26 Hartmut chg: rename removeFromGraphicThread(GralGraphicThread) to #removeFromList(GralGraphicThread). It is a better naming because it is removed from the queue in the graphic thread. This class is only used in that queue.
• 2012-01-15 Hartmut new: name to identify, proper for debugging
• 2012-01-08 Hartmut new: #addToList(GralGraphicThread, int) and #removeFromList(GralGraphicThread) as thread-safe functions which marks the instance as added (for delayed execution, for re-using).
• 2010-06-00 Hartmut created.

Copyright/Copyleft: For this source the LGPL Lesser General Public License, published by the Free Software Foundation is valid. It means:

1. You can use this source without any restriction for any desired purpose.
2. You can redistribute copies of this source to everybody.
3. Every user of this source, also the user of redistribute copies with or without payment, must accept this license for further using.
4. But the LPGL is not appropriate for a whole software product, if this source is only a part of them. It means, the user must publish this part of source, but don't need to publish the whole source of the own product.
5. You can study and modify (improve) this source for own using or for redistribution, but you have to license the modified sources likewise under this LGPL Lesser General Public License. You mustn't delete this Copyright/Copyleft inscription in this source file.

If you are indent to use this sources without publishing its usage, you can get a second license subscribing a special contract with the author.

See Also:

Constant Field Values

name

public final java.lang.String name

The name of the dispatch worker, used for debug at least.

ctDone

private int ctDone

dbgctDone

public int dbgctDone

It is counted only. Used for debug. Possible to set.

reqCtDone

private boolean reqCtDone

True if a thread waits, see awaitExecution(int, int).

Constructor Detail

TimeOrder

public TimeOrder(java.lang.String name)

TimeOrder

public TimeOrder(java.lang.String name,
                 EventTimerThread_ifc thread)

Initializes an time order for usage. The time order can be created dynamically on demand or as permanent instance. Use EventTimeout.activate(int) etc. to activate it.

If the time is expired after EventTimeout.activateAt(long, long) then the executeOrder() is invoked in the thread. Note: Use TimeOrder#EventTimeOrderBase(String, EventConsumer, EventTimerThread) if you want to execute the executeOrder() routine in another thread.

Parameters:

name - the TimeOrder should have a name for debugging.

thread - thread to handle the time order. It is obligatory.

TimeOrder

public TimeOrder(java.lang.String name,
                 EventConsumer dst,
                 EventTimerThread_ifc thread)

Initializes an time order for usage. The time order can be created dynamically on demand or as permanent instance. Use EventTimeout.activate(int) etc. to activate it.

If the time is expired after EventTimeout.activateAt(long, long) then the EventConsumer.processEvent(EventObject) is invoked in the thread. This routine can store this instance in another queue of any other thread to execute the executeOrder() in any other thread.

Parameters:

name - the TimeOrder should have a name for debugging.

dst - The destination object for the event. If it is null then the overridden executeOrder() will be executed if the time is expired. If given then EventConsumer.processEvent(EventObject) is invoked in the given dst instance. The #executeOrder is not invoked. It can be used in the dst for own things.

thread - thread to handle the time order. It is obligatory.

Method Detail

getStateInfo

public java.lang.String getStateInfo()

Returns the state of the consumer in a manual readable form.

executeOrder

protected abstract void executeOrder()

Executes the order. This abstract method should be implemented in a user's instance. This method should not be called directly. It is called from doExecute().

doExecute

public final void doExecute()

Executes and sets the execute state to false. A user should not invoke this method. Use EventTimeout.activate(int) etc. to activate the time order for execution.
This routine is invoked instead executeOrder(), it wraps it. It is called inside the package private EventTimerThread or from a special derived instance which will be invoke executeOrder() in any other thread.
If this routine is started then it is added newly on new invocation of EventTimeout.activate(int) etc.

getCtDone

public int getCtDone(int setCtDone)

Gets the information, how many times the routine is executed. Especially it is for quest, whether it is executed 1 time if it is a single-execution-routine.

Parameters:

setCtDone - set the count for a new execution-counting. For example 0.

Returns:

The number of times of execution after initializing or after last call of this method.

awaitExecution

public boolean awaitExecution(int ctDoneRequested,
                              int timeout)

Waits for execution in any other thread. This method can be called in any thread, especially in that thread, which initializes the request. Note that doExecute() should be invoked to execute the time order and notify this waiting routine. That is done if the EventTimerThread is used.

Parameters:

ctDoneRequested - Number of executions requested.

timeout - maximal waiting time in milliseconds, 0 means wait forever.

Returns:

true if it is executed the requested number of.

toString

public java.lang.String toString()

Returns the name of this to show it for debugging.

Overrides:

toString in class java.util.EventObject