org.vishia.event

Class EventWithDst<T_Payload extends Payload,T_PayloadOpp extends Payload>

java.lang.Object

java.util.EventObject

org.vishia.event.EventWithDst<T_Payload,T_PayloadOpp>

All Implemented Interfaces:

java.io.Serializable

public final class EventWithDst<T_Payload extends Payload,T_PayloadOpp extends Payload>
extends java.util.EventObject

This class is a universal basic for all events in the vishia Java source suite. It is derived from the Java standard EventObject. It contains a reference to its destination, which should execute this event, and optional to an instance of EventThread_ifc which is used as first destination to queue the events and forces the execution (delegates to the destination). The super class from java standard EventObject does only contain the reference to the source.

 Object <--source-+                   +---->Payload<|--T_Payload
         EventObject <|-+             |                  |
                        |             |                -more_Data
                     EventWithDst -d--+
                        |
                        |-------evDstThread--->EventTimerThread_ifc
                        |
                        |-------evDst--------->EventConsumer
                        |
                        |-------evOpp--------->EventWithDst
                     -name
                     -dateCreation 
                     -dateOrder
                     -stateOfEvent
                     -ctConsumed
                     -orderId 
 

UML Presentation see Docu_UML_simpleNotation

Usage of the event
First the event is the receiver for message data, the instance for queueing and the trigger instance for execution. It is used for trigger an action or for receive a feedback from an action.

Simple form, using only for trigger:

 Application                    evDst instance of EventConsumer
   +-->set any data               |
   |   to thisEvent payload       |
   +-->sendEvent(thisEvent)------>|
                                  +--processEvent()
 

• sendEvent(Object): emit the event to the dedicated evDst() instance (given by construction or occupy(EventSource, EventConsumer, EventThread_ifc, boolean)
• processEvent() is called immediately in the same thread, it calls in the evDst instance: EventConsumer.processEvent(EventObject). This can evaluate the data of the event.

Here no thread change is done. The event is only used to transport the immediately call. Examples for this usage are some operations of FileRemote such as FileRemote.mkdir(boolean, EventWithDst). If the 'make dir' operation is executed in the same thread because it is a cheap operation on the local file system, the 'Application' of the above sequence diagram is the 'mkdir' operation. The EventConsumer should be given with the event. It is only an instance, not related to another thread.

The application should call:

 EventConsumer 
 

 

 More simple form, only using the payload:
 
 Application
   +-->do any which uses the event 
              +-->set any data
   +<---------+   to thisEvent payload
   +<--read data
   |   from the events payload
 
 In this also sensible case the event is only used to store some data. 
 The called operation which uses the event fills some feedback data but don't send the event.
 The event instance is only used as data transporter. 
 This is for example done if some operations of FileRemote such as FileRemote.mkdir(boolean, EventWithDst)
 and the operation is executed in the same 
 

 ... no the using operation should call anyway sendEvent and a #evDst should be available.
 

 Note: If the message for this event was transferred via for example socket connection, 
   its data of the derived "UserEvent" should be received as payload and reconstructed.
   The aggregated data evDstThread and evDst() are set by initialization
   in the received environment.

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
(package private) boolean	bAwaitReserve
protected int	ctConsumed
(package private) T_Payload	d All data to this event, should be transferred via InterProcessComm.
protected java.util.concurrent.atomic.AtomicLong	dateCreation Timestamp of the request.
(package private) int	dateOrder Order of time stamps created in the same millisec of #dateCreation.
(package private) EventConsumer	evDst The destination instance for the Event.
(package private) EventThread_ifc	evDstThread The queue for events of the EventThread_ifc if this event should be used in a really event driven system (without directly callback).
(package private) EventWithDst<T_PayloadOpp,T_Payload>	evOpp This is an associated event which can be used for the back direction.
(package private) EventSource	evOwner
java.lang.String	name The current owner of the event.
protected long	orderId The commission number for the request, which may be answered by this event.
private static long	serialVersionUID
char	stateOfEvent State of the event: 0 or '
(package private) static java.text.SimpleDateFormat	toStringDateFormat
static java.lang.String	version Version, history and license.

Fields inherited from class java.util.EventObject

source

Constructor Summary

Constructors

Modifier	Constructor and Description
	EventWithDst(java.lang.String name, EventSource source, EventConsumer consumer, EventThread_ifc evThread, T_Payload d) Creates an event as static or dynamic object for usage.
private	EventWithDst(java.lang.String name, EventSource source, EventConsumer consumer, EventThread_ifc evThread, T_Payload d, EventWithDst<T_PayloadOpp,T_Payload> evOpp) Only used in EventWithDst(String, EventSource, EventConsumer, EventThread_ifc, Payload, String, EventSource, EventConsumer, EventThread_ifc, Payload) to create the opponent itself with this as reference.
	EventWithDst(java.lang.String name, EventSource source, EventConsumer consumer, EventThread_ifc evThread, T_Payload d, java.lang.String nameOpp, EventSource sourceOpp, EventConsumer consumerOpp, EventThread_ifc evThreadOpp, T_PayloadOpp dOpp) Creates an event as static or dynamic object for usage with its opponent event with a given opponent event.
	EventWithDst(java.lang.String name, EventSource source, EventConsumer consumer, EventThread_ifc evThread, T_Payload d, T_PayloadOpp dOpp) Creates an event as static or dynamic object for usage with its opponent event.
	EventWithDst(java.lang.String name, java.lang.Object source, T_Payload data)
	EventWithDst(java.lang.String name, java.lang.Object source, T_Payload data, EventWithDst<T_PayloadOpp,T_Payload> evOpp)
	EventWithDst(java.lang.String name, T_Payload data) Creates an event as a static object for re-usage.
	EventWithDst(java.lang.String name, T_Payload data, EventWithDst<T_PayloadOpp,T_Payload> evOpp)

Method Summary

Modifier and Type	Method and Description
void	clean()
protected void	cleanData() This is an empty operation for the basic event.
T_Payload	data()
java.util.Date	dateCreation() Returns the time stamp of creation or occupying the event.
EventConsumer	evDst() This method should only be called if the event should be processed.
EventConsumer	getDst() Returns the destination.
EventThread_ifc	getDstThread() Returns the stored destination thread for queuing the event.
EventWithDst<T_PayloadOpp,T_Payload>	getOpponent()
boolean	hasDst()
boolean	isOccupied() Returns true if the event is occupied.
(package private) void	notifyDequeued() Informs the EventSource.notifyDequeued(), invoked on dequeuing.
private void	notifyShouldOccupyButInUse()
boolean	occupy(EventSource source, boolean expect)
boolean	occupy(EventSource source, EventConsumer dst, EventThread_ifc thread, boolean expect) Check whether this event is free and occupies it.
boolean	occupy(int timeout, EventSource evSrc, EventConsumer dst, EventThread_ifc thread) Try to occupy the event.
boolean	occupyRecall(EventSource source, boolean expect)
boolean	occupyRecall(EventSource source, EventConsumer dst, EventThread_ifc thread, boolean expect) Try to occupy the event for usage, recall it if it is in stored in an event queue.
int	occupyRecall(int timeout, EventSource source, boolean expect) Try to occupy the event for usage, recall it if it is in stored in an event queue, wait till it is available, occupy a hanging event.
int	occupyRecall(int timeout, EventSource source, EventConsumer dst, EventThread_ifc thread, boolean expect) Try to occupy the event for usage, recall a stored event in queue, wait till it is available and force occupying on hanging.
int	processEvent() Applies the event to its evDst() to processes it (EventConsumerprocessEvent()) On #sendEvent() this operation is called immediately if the #evDstThread is not set.
void	relinquish() Relinquishes the event object.
boolean	removeFromQueue() Try to remove the event from the queue of the destination thread.
boolean	sendEvent(java.lang.Object source) Sends the event to the given destination.
void	setDst(EventConsumer dst)
void	setOrderId(long order)
(package private) void	setSource(java.lang.Object src)
void	XXXdonotRelinquish() Deprecated.

Methods inherited from class java.util.EventObject

getSource, toString

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, history and license.

• 2023-07-22 Hartmut enhancement: More ctor versions. The evOpp was not used till now.
• 2023-03-20 Hartmut The payload d is now typed with the new interface Payload. For serialize of the payload some thinking should be done.
• 2023-03-20 Hartmut chg the role of EventObject.source: originally it should be the creator of the event. But intrinsic it should be the instance which emits the event. The last one is only important on debugging. It is interesting on receiving from a queue, from where comes the event. Intrinsically it should show a __FILE__ and __LINE__ (as in C) to see where the event was emitted. That may be possible with StackTrace entries. Yet only sometimes a string is stored for that reason. The source is filled as argument now on sendEvent(Object). The up to now usage of source as the owner of the event is now stored in evOwner in this class.
• 2023-03-12 Hartmut chg The org.vishia.event is refactored:
  • Only the final EventWithDst is existent.
  • The data of the event are not defined by derivation, now they are defined by a aggregated payload.
  • The payload should be Serializable, because exact this are all data to transfer an event.
  • The classes EventCmdtype and EventCmdtypeWithBackEvent are dissolved. The Cmd is part of Payload. The aggregation evOpp is now contained here. It is null if a back event is not given.
  • TimeOrder is no more aggregated, but the TimeOrder aggregates its event.
  • EventConsumer can decide about the thread.
  • occupy(EventSource, EventConsumer, EventThread_ifc, boolean) is related only to the dateCreation and not to the evDst The evDst() can be determined by construction, as well as the EventObject.source.
• 2023-02-07 Hartmut chg #timeOrder as possible aggreation (on construction) with the proper ctor: #EventWithDst(String, EventTimerThread_ifc, EventSource, EventConsumer, EventThread_ifc)
• 2023-02-07 Hartmut chg now the event has a name, helps on debug
• 2023-02-07 Hartmut refactor the evDstThread is not a EventTimerThread, it is a common possible EventThread_ifc. this has less impact on usage.
• 2023-02-07 Hartmut new #bStaticOccupied: now eventually clarified, necessary using occupy or not.
• 2015-01-03 Hartmut chg: Separated in 2 classes: EventCmdtypeWithBackEvent with opponent and this class. A simple event has not an opponent per default. This class is named EventWithDst yet because the destination is the significant difference to its base class EventObject.
• 2015-01-03 Hartmut chg: Renamed to EventMsg: more significant name. Derived from EventObject: A basicly Java concept.
• 2013-10-06 Hartmut chg: Some checks for thread safety.
• 2013-10-06 Hartmut chg: occupy(int, EventSource, EventConsumer, EventThread_ifc) with timeout
• 2013-10-06 Hartmut chg: occupyRecall(EventSource, boolean) return 0,1,2, not boolean. The state whether the recalled event is processed or it is only removed from the queued, may be important for usage.
• 2013-05-11 Hartmut new: #Event(Enum) to create an event for direct usage. #cmde does not need to be an Atomic, because dateCreation is Atomic to designate the occupy-state of the event.
• 2013-04-12 Hartmut chg: Gardening. The attributes data1, data2, oData, refData are removed. Any special data should be defined in any derived instance of the event. A common universal data concept may be error-prone because unspecified types and meanings.
• 2013-04-07 Hartmut chg: The Event class has 2 generic parameters up to now, the second for the opponent Event.
• 2012-11-16 Hartmut chg: An event is not occupied on construction if either the src or the dst is null. Only if both references are given, it is occupied by construction.
• 2012-09-12 Hartmut new: #sendEventAgain() for deferred events.
• 2012-09-03 Hartmut chg: using DateOrder to log the date in milliseconds and the order as fine number. The order of events should be known. The timestamp is imprecise!
• 2012-08-30 Hartmut new: Some substantial enhancements for usage:
  • re-engineering for occupy(EventSource, boolean)
  • Test and simplification of some use cases.
  • Meaning of the source of events, debug helping
  • documentation
• 2012-08-03 Hartmut chg: Usage of Event in FileRemote. The event has more elements for forward and backward now.
• 2012-07-28 renamed src, now #refData. It is not the source (creator) of the event but a value reference which may be used especially in the callback (#callback). Because it is private and the getter method #getRefData() is duplicated, the old routine #getSrc() is deprecated, it is downward compatible still.
• 2012-03-10 Hartmut new: #owner, #forceRelease(). It is a problem if a request may be crashed in a remote device, but the event is reserved for answer in the proxy. It should be freed. Events may be re-used.
• 2012-01-22 Hartmut chg: #use(long, int, Object, EventConsumer) needs the dst as parameter.
• 2012-01-05 Hartmut improved: #callbackThread, #commisionId instead order, more #data2
• 2011-12-27 Hartmut created, concept of event queue, callback need for remote copy and delete of files (in another thread too). A adequate universal class in java.lang etc wasn't found.

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 intent 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 current owner of the event. It is that instance, which has gotten the event instance.

evOwner

EventSource evOwner

evDstThread

EventThread_ifc evDstThread

The queue for events of the EventThread_ifc if this event should be used in a really event driven system (without directly callback). If it is null, the dst. EventConsumer#processEvent(EventMsg) should be called immediately.

evDst

EventConsumer evDst

The destination instance for the Event. If the event is stored in a common queue, the dst is invoked while polling the queue. Elsewhere the dst is the callback instance.

d

T_Payload extends Payload d

All data to this event, should be transferred via InterProcessComm. Also the type of the event should be transferred, for events without payload. It means Payload can be null, if the type is sufficient to regocnize the event.

evOpp

final EventWithDst<T_PayloadOpp extends Payload,T_Payload extends Payload> evOpp

This is an associated event which can be used for the back direction. Often a pair of events for back communication is necessary. It is null if unused.

stateOfEvent

public char stateOfEvent

State of the event:

• 0 or '.': unused.
• a: requested or allocated. The EventConsumer and the EventThread_ifc is set, but the event is not in send to the consumer. It is not in a queue and not in process.
• q: queued in dstThread
• e: executing
• B: queued for callback
• b: callback invoked

bAwaitReserve

boolean bAwaitReserve

ctConsumed

protected int ctConsumed

orderId

protected long orderId

The commission number for the request, which may be answered by this event.

dateCreation

protected final java.util.concurrent.atomic.AtomicLong dateCreation

Timestamp of the request. It is atomic because the timestamp may be an identification that the event instance is occupied, see occupy(EventSource, boolean). It is for new-obviating usage.

dateOrder

int dateOrder

Order of time stamps created in the same millisec of #dateCreation. Only used if necessary, usual not. Maybe for debugging approaches.

toStringDateFormat

static final java.text.SimpleDateFormat toStringDateFormat

Constructor Detail

EventWithDst

public EventWithDst(java.lang.String name,
                    T_Payload data)

Creates an event as a static object for re-usage. Use #occupy(Object, EventConsumer, EventThread_ifc) before first usage. relinquish() will be called on release the usage.

Parameters:

name - of the event used only for debug.

EventWithDst

public EventWithDst(java.lang.String name,
                    T_Payload data,
                    EventWithDst<T_PayloadOpp,T_Payload> evOpp)

EventWithDst

public EventWithDst(java.lang.String name,
                    java.lang.Object source,
                    T_Payload data)

EventWithDst

public EventWithDst(java.lang.String name,
                    java.lang.Object source,
                    T_Payload data,
                    EventWithDst<T_PayloadOpp,T_Payload> evOpp)

EventWithDst

public EventWithDst(java.lang.String name,
                    EventSource source,
                    EventConsumer consumer,
                    EventThread_ifc evThread,
                    T_Payload d)

Creates an event as static or dynamic object for usage.

Parameters:

name - of the event used only for debug.

source - Source of the event.

consumer - If null then the event should be occupied before usage. If given occupy(EventSource, boolean) is not necessary for usage but possible.

thread - an optional thread to store the event in an event queue, maybe null. If null but the EventConsumer.evThread() returns not null, it is used. It means the EventConsumer can decide about the event thread. But this argument is used if given.

d - the instance for the payload for this event. If the event is transmitted via a medium, the payload will be serialized.

EventWithDst

public EventWithDst(java.lang.String name,
                    EventSource source,
                    EventConsumer consumer,
                    EventThread_ifc evThread,
                    T_Payload d,
                    T_PayloadOpp dOpp)

Creates an event as static or dynamic object for usage with its opponent event. The opponent event is created without a specified EventConsumer and without a specified event thread. It means the opponent event can be used in a specific kind (for example to transmit the data) or this information should be given using occupy(EventSource, EventConsumer, EventThread_ifc, boolean). But the payload for the opponent is referenced if the dOpp argument is not null.

Parameters:

name - of the event used only for debug. The opponent gets the name + "~".

source - Source of the event. Can be null, then a default source is used, or can be also a string literal.

consumer - If null then the event should be occupied before usage. If given occupy(EventSource, boolean) is not necessary for usage but possible.

thread - an optional thread to store the event in an event queue, maybe null. If null but the EventConsumer.evThread() returns not null, it is used. It means the EventConsumer can decide about the event thread. But this argument is used if given.

d - the instance for the payload for this event. If the event is transmitted via a medium, the payload will be serialized.

dOpp - the instance for the payload for the opponent of the event. If the event is transmitted via a medium, the payload will be serialized. This instance is then used as destination for deserialize.

EventWithDst

private EventWithDst(java.lang.String name,
                     EventSource source,
                     EventConsumer consumer,
                     EventThread_ifc evThread,
                     T_Payload d,
                     EventWithDst<T_PayloadOpp,T_Payload> evOpp)

Only used in EventWithDst(String, EventSource, EventConsumer, EventThread_ifc, Payload, String, EventSource, EventConsumer, EventThread_ifc, Payload) to create the opponent itself with this as reference. If this class would be used in an application the opponent would not refer its mutual opponent. Hence it is private.

Parameters:

name - fed with the nameOpp

source -

consumer -

evThread -

d -

evOpp - this

EventWithDst

public EventWithDst(java.lang.String name,
                    EventSource source,
                    EventConsumer consumer,
                    EventThread_ifc evThread,
                    T_Payload d,
                    java.lang.String nameOpp,
                    EventSource sourceOpp,
                    EventConsumer consumerOpp,
                    EventThread_ifc evThreadOpp,
                    T_PayloadOpp dOpp)

Creates an event as static or dynamic object for usage with its opponent event with a given opponent event. The opponent event should be created without this as opponent of course. But this event is referenced in the opponent also as opponent by this constructor. The opponent can be created with a specific EventConsumer, EventThread_ifc and Payload. The implementation type of Payload should match the T_PayloadOpp in this class and vice versa.

Parameters:

name - of the event used only for debug. The opponent gets the name + "~".

source - Source of the event. Can be null, then a default source is used, or can be also a string literal.

consumer - If null then the event should be occupied before usage. If given occupy(EventSource, boolean) is not necessary for usage but possible.

thread - an optional thread to store the event in an event queue, maybe null. If null but the EventConsumer.evThread() returns not null, it is used. It means the EventConsumer can decide about the event thread. But this argument is used if given.

d - the instance for the payload for this event. If the event is transmitted via a medium, the payload will be serialized.

opponent - Already created opponent first as event without opponent. The type of Payload (generic types of this class) should match.

Method Detail

setSource

void setSource(java.lang.Object src)

setOrderId

public void setOrderId(long order)

XXXdonotRelinquish

@Deprecated
public void XXXdonotRelinquish()

Deprecated.

Prevent that the event is relinquished after processing. This method should be called in the processing routine of an event only if the event is stored in another queue to execute delayed.

evDst

public EventConsumer evDst()

This method should only be called if the event should be processed. The #donotRelinquish() will be set to false, so that the event will be relinquished except #donotRelinquish() is called while processing the event.

Returns:

The event consumer to call EventConsumer#processEvent(EventMsg).

data

public T_Payload data()

dateCreation

public java.util.Date dateCreation()

Returns the time stamp of creation or occupying the event.

Returns:

null if the event is not occupied, a free static object.

hasDst

public boolean hasDst()

setDst

public void setDst(EventConsumer dst)

cleanData

protected void cleanData()

This is an empty operation for the basic event. It is intent to override for derived events to clean the event data.

clean

public void clean()

occupy

public boolean occupy(EventSource source,
                      EventConsumer dst,
                      EventThread_ifc thread,
                      boolean expect)

Check whether this event is free and occupies it. An event instance can be re-used. If the dateCreation() is set, the event is occupied. In a target communication with embedded devices often the communication resources are limited. It means that only one order can be requested at one time, and the execution should be awaited. The usage of an re-used event for such orders can be help to organize the requests step by step. If the answer-event instance is in use, a request is pending.

Parameters:

source - Source instance able to use for monitoring the event life cycle. null is admissible.

dst - The destination instance which should receive this event. If null, the dst given by constructor or the last given dst is used.

thread - A thread which queues the event, stored in evDstThread . If null, then the given thread by constructor or the last given thread is used. If null and dst !=null then the EventConsumer.evThread() is used, but it can be also null. If the evDstThread remains null, then the event is used as callback, the EventConsumer.processEvent(EventObject) is immediately called on #sendEvent().

expect - If true and the event is not able to occupy, then the method EventSource.notifyShouldOccupyButInUse() from the given source is invoked. It may cause an exception for example.

Returns:

true if the event instance is occupied and ready to use.

occupy

public boolean occupy(int timeout,
                      EventSource evSrc,
                      EventConsumer dst,
                      EventThread_ifc thread)

Try to occupy the event. If it is in use yet, the thread waits the given timeout. This waiting is used for thread switch, process the event and release it. An event may be used only as a transport data from one thread to another. The event is relinquished usual in a less time after the other thread has processed it. The event can be re-used after them for another request. But it should wait a moment to force thread switching.

Parameters:

timeout -

evSrc -

dst -

thread -

Returns:

true if occupied, false if the other thread which should process the event hangs.

occupy

public boolean occupy(EventSource source,
                      boolean expect)

occupyRecall

public boolean occupyRecall(EventSource source,
                            EventConsumer dst,
                            EventThread_ifc thread,
                            boolean expect)

Try to occupy the event for usage, recall it if it is in stored in an event queue.

• If the event is free, then it is occupied, the method returns immediately with true.
• If it is not free, but stored in any queue, it will be removed from the queue, then occupied for this new usage. The method returns imediately with true.
• If it is used and not found in any queue, then it is processed in this moment. Then this method returns false. The method doesn't wait. See #occupyRecall(int, Object, EventConsumer, EventThread_ifc).

Parameters:

source - Source instance able to use for monitoring the event life cycle. null is admissible.

dst - The destination instance which should receive this event. If null, the dst given by constructor or the last given dst is used.

thread - A thread which queues the event. If null and dst !=null then the dst method EventConsumer#processEvent(EventMsg) is invoked in the current thread. If dst ==null this parameter is not used.

expect - If true and the event is not able to occupy, then the method EventSource.notifyShouldOccupyButInUse() from the given source is invoked. It may cause an exception for example.

Returns:

true if the event is occupied.

occupyRecall

public boolean occupyRecall(EventSource source,
                            boolean expect)

occupyRecall

public int occupyRecall(int timeout,
                        EventSource source,
                        EventConsumer dst,
                        EventThread_ifc thread,
                        boolean expect)

Try to occupy the event for usage, recall a stored event in queue, wait till it is available and force occupying on hanging. This method may block if the event is yet processing. The method blocks only for the given timeout.

An event is a container for a message. If it is send to a queue but it is not executed yet and the sender knows that a re-fill is better, it should use this method. For example a progress message can be send to a queue. If that progress message is not used and a newer progress message is better to have, the event may be recalled.

If the event was send, it is not queued yet but it is occupied though, It is possible that the consumer has not invoked relinquish() because the consumer process was aborted especially by an exception or there is any other error. If the event was occupied a longer time before it is relinquished by this method and occupied newly.

The only one reason that this method returns 0 and does not occupy is: The event was occupied newly in the timeout period after this method was started by any other process. It means the event does not hang but it is used by any other.

• If the event is free, then it is occupied, the method returns immediately with 1. The last usage of the event is processed in this case.
• If it is not free, but stored in any queue, it will be removed from the queue, then occupied for this new usage. The method returns immediately with 2. It means the last cmd is not processed.
• If the event is occupied already and not found in any queue, then it seems to be processed in this moment. This method waits the given timeout till the event is free. If it will be free in the timeout period, the method occupies it and returns 1.
• If the timeout is expired, it is checked whether the timestamp of the occupying of the event is lesser than the timestamp on starting wait. If it is so, the event hangs. That is especially if the event process has thrown an exception and the event was not relinquished therefore. The event would hang forever. Therefore the dateCreation() is forced to 0, so the event is free now. Then it is occupied from this routine.
• If that occupying fails too, it is only possible that another process has occupied it too.
• If the event cannot be occupied the method returns 0. That may be an unexpected situation, because the processing of an event should be a short non-blocking algorithm. It may be a hint to an software error. one may try again occupy with an increased timeout. The processing may need more time. It is possible that the processing of the event hangs (deadlock).

See #occupyRecall(Object, EventConsumer, EventThread_ifc).

Parameters:

timeout - maximal millisecond to wait if the event is yet in processing.

source - Source instance able to use for monitoring the event life cycle. null is admissible.

dst - The destination instance which should receive this event. If null, the dst given by constructor or the last given dst is used.

thread - A thread which queues the event. If null and dst !=null then the dst method EventConsumer#processEvent(EventMsg) is invoked in the current thread. If dst ==null this parameter is not used.

expect - If true and the event is not able to occupy, then the method EventSource.notifyShouldOccupyButInUse() from the given source is invoked. It may cause an exception for example.

Returns:

• 0 if the event is blocked because it is in process for the timeout time,
• != 0 if the event is occupied:
• 1 if the event was free.
• 2 if the event is removed from another queue. It means the last one request is not done.
• 3 if the event is forced relinquish because it was hanging.

occupyRecall

public int occupyRecall(int timeout,
                        EventSource source,
                        boolean expect)

Try to occupy the event for usage, recall it if it is in stored in an event queue, wait till it is available, occupy a hanging event. Same as occupyRecall(int, EventSource, EventConsumer, EventThread_ifc, boolean) but left the destination unchanged.

Parameters:

timeout - maximal millisecond to wait if the event is yet in processing.

source - Source instance able to use for monitoring the event life cycle. null is admissible.

expect - If true and the event is not able to occupy, then the method EventSource.notifyShouldOccupyButInUse() from the given source is invoked. It may cause an exception for example.

Returns:

0 if the event is blocked because it is in process for the timeout time, != 0 if the event is occupied. 1 if the event was free. 2 if the event is removed from another queue. It means the last one request is not done.

isOccupied

public boolean isOccupied()

Returns true if the event is occupied. Events may be re-used. That may be necessary if a non-dynamic memory organization may be need, for example in C-like programming. It is possible anyway if actions are done only one after another. In that kind the event instance is created one time, and re-used whenever it is needed. If the answer hangs, occupyRecall(int, EventSource, boolean) may be called to occupy it though.

Returns:

false if it is ready to re-use.

getDstThread

public EventThread_ifc getDstThread()

Returns the stored destination thread for queuing the event.

getDst

public EventConsumer getDst()

Returns the destination.

Returns:

getOpponent

public EventWithDst<T_PayloadOpp,T_Payload> getOpponent()

removeFromQueue

public boolean removeFromQueue()

Try to remove the event from the queue of the destination thread.

Returns:

true if it was in the queue and it is removed successfully. false if the event was not found in the queue or the destination thread is not set.

relinquish

public void relinquish()

Relinquishes the event object. It is the opposite to the #occupy(Object, EventConsumer, EventThread_ifc) method. The dateCreation is set to 0 especially to designate the free-state of the Event instance. The #refData, evDst(), evDstThread and #opponent are not changed because the event may be reused in the same context. All other data are reseted, so no unused references are hold.

If any thread waits for this Event object, a Object.notify() is called. See #occupyRecall(int) and #occupyRecall(int, Object, EventConsumer, EventThread_ifc).

If #donotRelinquish() was called inside the EventConsumer#processEvent(EventMsg) for this event, this method return without effect. This is helpfully if the event was stored in another queue for any reason.

sendEvent

public boolean sendEvent(java.lang.Object source)

Sends the event to the given destination. If the evDstThread is given on construction or on occupy(int, EventSource, EventConsumer, EventThread_ifc) then the event is stored in the queue of this thread to execute it using EventThread_ifc.storeEvent(EventObject).
If the thread is not given, EventConsumer.processEvent(EventObject) is called to execute the event in the current thread.
Generally, the event is relinquished and the EventSource is informed if the event is processed, see description of EventConsumer.processEvent(EventObject). It means, if the event is applied or processed, it is free for further usage or it can contain back information, then it should be evaluated and freed by the application. This is decided with the return value of the processEvent operation.
The evDst() must no == null, should be given by construction with EventWithDst#EventWithDst(String, EventSource, EventConsumer, EventThread_ifc) or by occupy(EventSource, EventConsumer, EventThread_ifc, boolean). If it is null, an exception is thrown.

Returns:

true if the event is already processed, false if it is stored in a queue, not processed yet.

processEvent

public int processEvent()

Applies the event to its evDst() to processes it (EventConsumerprocessEvent()) On #sendEvent() this operation is called immediately if the #evDstThread is not set. For callback like events. This operation should not be called immediately from the user, call #sendEvent(), but it is equal to #sendEvent() if no thread is given. It is called from EventTimerThread and it is intent to call from other event queue organizations.

notifyDequeued

void notifyDequeued()

Informs the EventSource.notifyDequeued(), invoked on dequeuing.

notifyShouldOccupyButInUse

private void notifyShouldOccupyButInUse()