EventConsumerAwait

java.lang.Object
- org.vishia.event.EventConsumerAwait<T_PayloadBack,T_Payload>

All Implemented Interfaces:

EventConsumer

Direct Known Subclasses:

FileRemoteProgressEventConsumer
```
public class EventConsumerAwait<T_PayloadBack extends PayloadBack,T_Payload extends Payload>
extends java.lang.Object
implements EventConsumer
```
Base class for all event consumer, same as implementation of the simple EventConsumer interface, but the EventConsumer#awaitExecution(long) is already implemented here. The EventConsumer.processEvent(java.util.EventObject) implementation should call setDone(String) on receive and execute an event if the event succeeds the execution or succeeds with exception or error.

How the 'done' information may be gotten from the event is not able to clarify from this universal base class, the Payload of the event for EventConsumer.processEvent(java.util.EventObject) is not defined here. Hence the implementation of 'processEvent(...)' should be done in the specific kind in the inherit class.

Field Summary

Fields
Modifier and Type	Field and Description
`protected boolean`	`bDone` It is set in `setDone(String)`, should be called if the event was received with the "done" information.
`private boolean`	`bWait` Marker that `Object.wait()` was called in `awaitExecution(long, boolean)`.
`protected T_Payload`	`cmdData` This cmdData are used and reused for calling commands to the `FileRemote#device()` during walking.
`EventWithDst<T_PayloadBack,T_Payload>`	`evBack` Back event with the evCmd as opponent.
`protected EventThread_ifc`	`evThread` This reference should be used if the Consumer implementor (the inherit class) should offer a specific thread where the events are intermediately stored before execution in this consumer.
`java.lang.String`	`name`
`protected T_PayloadBack`	`progressData` Data for the progress and success back event used and reused for all back event calling, referenced from `evBack`
`protected java.lang.String`	`sError` Set in `setDone(String)` as info about error from the event.
`static java.lang.String`	`version` Version, history and license.

Fields inherited from interface org.vishia.event.EventConsumer
mEventConsumed, mEventConsumerException, mEventConsumFinished, mEventDonotRelinquish, mMaskReservedHere

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`EventConsumerAwait(java.lang.String name, T_PayloadBack backData, EventThread_ifc evThread, T_Payload cmdData, EventThread_ifc cmdThread)` Called from the inherit class.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`awaitExecution(long timeout, boolean clearDone)` Awaits for execution till "done" was set by the event which uses this destination or till the timeout is expired.
`EventConsumerAwait`	`clean()` Cleans `bDone` and also `sError`.
`boolean`	`done()` Quest whether done was coming.
`EventThread_ifc`	`evThread()` If the inherit consumer defines a specific thread, get it here.
`int`	`processEvent(java.util.EventObject evRaw)` This operation is called from `EventWithDst.sendEvent(Object)` or from `EventTimerThread.stepThread()` as overridden.
`protected int`	`processEvent(T_PayloadBack progress, EventWithDst<T_Payload,T_PayloadBack> evCmd)` This operation should be overridden and called as super.processEvent() if more should be done with the progress event.
`protected void`	`setDone(java.lang.String sError)` This operation should be called by the implementing class if an event was received with "done" information.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - version
```
public static final java.lang.String version
```
    Version, history and license.
    - 2023-07-24 The class is enhanced as own usable class with features which were implemented before in FileRemoteProgressEventConsumer:
      The Consumer contains the own event reference which should be consumed here, ready to use.
      The payload data are referenced. Whereby the PayloadBack contains the minimal necessary payload to test done and error.
      The class is no more abstract, it is usable whenever only the done or error should be tested as callback.
    - 2023-07-22 possible bug fixed: awaitExecution(long, boolean): If the event was cleaned without success this operation should be left. It is done via bWait = false test. The adequate notifyAll in clean() wakes up the 'await...'.
    - 2023-02-12 Hartmut created, because universal approach to wait till done
    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
  - cmdData
```
protected final T_Payload extends Payload cmdData
```
    This cmdData are used and reused for calling commands to the FileRemote#device() during walking. It are referenced from evBack.
  - progressData
```
protected final T_PayloadBack extends PayloadBack progressData
```
    Data for the progress and success back event used and reused for all back event calling, referenced from evBack
  - evBack
```
public final EventWithDst<T_PayloadBack extends PayloadBack,T_Payload extends Payload> evBack
```
    Back event with the evCmd as opponent. Because the opponent has no thread and no Consumer as event destination, only its payload is used as T_Payload for internal commands which are executed if possible in the same thread. The back event is used for check success, and also necessary if the device uses communication and/or an own thread. The EventConsumer for this evBack is this own class. It offers awaitExecution(long, boolean) in its base class FileRemoteProgressEventConsumer.
  - name
```
public final java.lang.String name
```
  - bDone
```
protected boolean bDone
```
    It is set in setDone(String), should be called if the event was received with the "done" information. It is used to continue after awaitExecution(long, boolean).
  - bWait
```
private boolean bWait
```
    Marker that Object.wait() was called in awaitExecution(long, boolean).
  - sError
```
protected java.lang.String sError
```
    Set in setDone(String) as info about error from the event.
  - evThread
```
protected final EventThread_ifc evThread
```
    This reference should be used if the Consumer implementor (the inherit class) should offer a specific thread where the events are intermediately stored before execution in this consumer. It should be set on construction of the inherit consumer instance or set to null if not used.
- Constructor Detail
  - EventConsumerAwait
```
protected EventConsumerAwait(java.lang.String name,
                             T_PayloadBack backData,
                             EventThread_ifc evThread,
                             T_Payload cmdData,
                             EventThread_ifc cmdThread)
```
    Called from the inherit class.
    
    Parameters:
    
    evThread - maybe null if not used here.
- Method Detail
  - evThread
```
public EventThread_ifc evThread()
```
    If the inherit consumer defines a specific thread, get it here. Else returns null.
    
    Specified by:
    
    evThread in interface EventConsumer
    
    Returns:
    
    null possible if no specific thread was associated.
  - processEvent
```
protected int processEvent(T_PayloadBack progress,
                           EventWithDst<T_Payload,T_PayloadBack> evCmd)
```
    This operation should be overridden and called as super.processEvent() if more should be done with the progress event. It is sufficient if only success or error is expected.
    
    Parameters:
    
    progress - progress data to inform
    
    evCmd - The command event may be given as opponent of the progress event for feedback, for example if a quest is given ("skip/override" etc.) This can be used in the overridden operations.
    
    Returns:
  - processEvent
```
public int processEvent(java.util.EventObject evRaw)
```
    This operation is called from EventWithDst.sendEvent(Object) or from EventTimerThread.stepThread() as overridden. It prepares and calls {@link #processEvent(T_PayloadBack, EventWithDst) which is overridden by the application.
    
    Specified by:
    
    processEvent in interface EventConsumer
    
    Parameters:
    
    evRaw - The event. It contains some data. The type of the event is not specified here. Any events can be processed.
    
    Returns:
    
    0 or EventConsumer.mEventConsumed or EventConsumer.mEventDonotRelinquish etc. see list above. This value is forwarded to EventSource.notifyConsumed(int) and can be evaluated by the application in the calling thread or in any other thread which have access to implementation of EventSource.
  - setDone
```
protected final void setDone(java.lang.String sError)
```
    This operation should be called by the implementing class if an event was received with "done" information.
    
    Parameters:
    
    sError - If the event contains an error string, it may be helpfully.
  - done
```
public boolean done()
```
    Quest whether done was coming.
    
    Returns:
    
    bDone
  - awaitExecution
```
public final boolean awaitExecution(long timeout,
                                    boolean clearDone)
```
    Awaits for execution till "done" was set by the event which uses this destination or till the timeout is expired. or more exact, till setDone(String) was called.
    
    Parameters:
    
    timeout - milliseconds timeout
    
    clearDone - clear the done flag again before return (not on entry!). Use clean() to clean done before entry.
    
    Returns:
    
    true if done was detected, false on timeout or if the event was cleaned.
  - clean
```
public EventConsumerAwait clean()
```
    Cleans bDone and also sError. It should be called on initializing the event, in any case before awaitExecution(long, boolean) was called.

Class EventConsumerAwait<T_PayloadBack extends PayloadBack,T_Payload extends Payload>

Field Summary

Fields inherited from interface org.vishia.event.EventConsumer

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

version

cmdData

progressData

evBack

name

bDone

bWait

sError

evThread

Constructor Detail

EventConsumerAwait

Method Detail

evThread

processEvent

processEvent

setDone

done

awaitExecution

clean