EventWithDst

java.lang.Object
- java.util.EventObject
- - org.vishia.event.EventWithDst

All Implemented Interfaces:: java.io.Serializable

Direct Known Subclasses:: EventCmdtype, EventTimeout

public class EventWithDst
extends java.util.EventObject

This class is the basic class for all events of this package. It is derived from the Java standard EventObject. It contains a reference to its destination, which should execute this event, and to an instance which queues and forces the execution of the event (delegates to the destination).

                                      +----UserEvent
                                      |        |
                                      |     -more_Data
                     EventWithDst<|---+
  Object<---source------|
                        |-------evDstThread--->EventTimerThread_ifc
                        |
                        |-------------evdst--->EventConsumer
                        |
                 -dateCreation 
                 -dateOrder
                 -stateOfEvent
                 -ctConsumed
                 -orderId

UML Presentation see Docu_UML_simpleNotation

See Also:: Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`(package private) boolean`	`bAwaitReserve`
`protected int`	`ctConsumed`
`protected java.util.concurrent.atomic.AtomicLong`	`dateCreation` Timestamp of the request.
`(package private) int`	`dateOrder`
`(package private) EventConsumer`	`evDst` The destination instance for the Event.
`(package private) EventTimerThread_ifc`	`evDstThread` The queue for events of the `EventTimerThread` if this event should be used in a really event driven system (without directly callback).
`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
Constructor and Description
`EventWithDst()` Creates an event as a static object for re-usage.
`EventWithDst(EventSource source, EventConsumer consumer, EventTimerThread_ifc thread)` Creates an event as static or dynamic object for usage.
`EventWithDst(java.lang.Object source)`

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`void`	`consumed()` This routine should be called after consuming the event.
`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.
`EventTimerThread_ifc`	`getDstThread()` Returns the stored destination thread for queuing the event.
`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, EventTimerThread thread, boolean expect)` Check whether this event is free and occupies it.
`boolean`	`occupy(int timeout, EventSource evSrc, EventConsumer dst, EventTimerThread thread)` Try to occupy the event.
`boolean`	`occupyRecall(EventSource source, boolean expect)`
`boolean`	`occupyRecall(EventSource source, EventConsumer dst, EventTimerThread 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, EventTimerThread 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.
`void`	`relinquish()` Relinquishes the event object.
`boolean`	`removeFromQueue()` Try to remove the event from the queue of the destination thread.
`boolean`	`sendEvent()` Sends the event again to the same destination with the same command.
`void`	`setDst(EventConsumer dst)`
`void`	`setOrderId(long order)`
`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.
    - 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, EventTimerThread) 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
  - evDstThread
```
EventTimerThread_ifc evDstThread
```
    The queue for events of the EventTimerThread 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.
  - stateOfEvent
```
public char stateOfEvent
```
    State of the event:
    - 0 or '.': unused.
    - a: requested or allocated. The EventConsumer and the EventTimerThread 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
```
  - toStringDateFormat
```
static final java.text.SimpleDateFormat toStringDateFormat
```
- Constructor Detail
  - EventWithDst
```
public EventWithDst(java.lang.Object source)
```
  - EventWithDst
```
public EventWithDst()
```
    Creates an event as a static object for re-usage. Use #occupy(Object, EventConsumer, EventTimerThread) before first usage. relinquish() will be called on release the usage.
  - EventWithDst
```
public EventWithDst(EventSource source,
                    EventConsumer consumer,
                    EventTimerThread_ifc thread)
```
    Creates an event as static or dynamic object for usage.
    
    Parameters:
    
    source - Source of the event. If null then the event is not occupied, especially the dateCreation() is set to 0. Use occupy(EventSource, boolean) before usage. That is for a static instance.
    
    refData - Associated data to the event. It is the source of the event.
    
    consumer - The destination object for the event.
    
    thread - an optional thread to store the event in an event queue, maybe null.
- Method Detail
  - 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).
  - 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)
```
  - occupy
```
public boolean occupy(EventSource source,
                      EventConsumer dst,
                      EventTimerThread 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. 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 instance is occupied and ready to use.
  - occupy
```
public boolean occupy(int timeout,
                      EventSource evSrc,
                      EventConsumer dst,
                      EventTimerThread 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,
                            EventTimerThread 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, EventTimerThread).
    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,
                        EventTimerThread 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, EventTimerThread).
    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, EventTimerThread, 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 EventTimerThread_ifc getDstThread()
```
    Returns the stored destination thread for queuing the event.
  - getDst
```
public EventConsumer getDst()
```
    Returns the destination.
    
    Returns:
  - 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, EventTimerThread) 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, EventTimerThread).
    
    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()
```
    Sends the event again to the same destination with the same command. This method can be used by an application if an Event is received but stored for deferred usage.
    
    Returns:
    
    true
  - consumed
```
public void consumed()
```
    This routine should be called after consuming the event. It counts the number of consuming and invokes EventSource.notifyConsumed(int) with this number if a source is given. Usual that is helpfully for debugging.
  - notifyDequeued
```
void notifyDequeued()
```
    Informs the EventSource.notifyDequeued(), invoked on dequeuing.
  - notifyShouldOccupyButInUse
```
private void notifyShouldOccupyButInUse()
```

Class EventWithDst

Field Summary

Fields inherited from class java.util.EventObject

Constructor Summary

Method Summary

Methods inherited from class java.util.EventObject

Methods inherited from class java.lang.Object

Field Detail

serialVersionUID

version

evDstThread

evDst

stateOfEvent

bAwaitReserve

ctConsumed

orderId

dateCreation

dateOrder

toStringDateFormat

Constructor Detail

EventWithDst

EventWithDst

EventWithDst

Method Detail

setOrderId

XXXdonotRelinquish

evDst

dateCreation

hasDst

setDst

occupy

occupy

occupy

occupyRecall

occupyRecall

occupyRecall

occupyRecall

isOccupied

getDstThread

getDst

removeFromQueue

relinquish

sendEvent

consumed

notifyDequeued

notifyShouldOccupyButInUse