See also FileRemote.html

1. Approach

Hint: This article is not ready yet, the event system is refactored. Wait for new information (2023-03)

1.1. Events in vishia-Java

Events are used on some positions in the Java sources of vishia especially

The events are based on Java’s standard java.util.EventObject. This gives the possibility to store events in a unique typed queue.

From this super class some Event classes are derived, see next chapter.

2. Event classes and its inheritance

java.util.EventObject
  A           +--source---------->Object
  |
  |
EventWithDst -+--evDstThread----->EventThread_ifc
  A           +--evDst----------->EventConsumer
  |           +--timeOrder---------------->TimeOrder
  |           +-stateOfEvent: char           +-timeExecution: long
  |           +-bAwaitReserve: boolean       + timeExcecutionlatest: long
  |           +-ctConsumed: int              +-bAwaiting: boolean
  |           +-orderId: long                +-bNotifyAlsoOnException: boolean
  |           +-dateCreation: AtomicLong     +-bTimeElapsed: boolean
  |           +-dateOrder: int               +-bEventException: boolean
  |                                          +-bEventExecuted: boolean
  |                                          +-bDone: boolean
  |                                          +-timerThread-->EventTimerThread_ic
  |<----------------------------------event--+
  |
EventCmdtype<CmdEnum extends Enum<CmdEnum>>
  A           +-cmde: CmdEnum
  |
EventCmdtypeWithBackEvent
  A           +--opponent-------->EventWithDstA    |
... User event deviations

2.1. EventWithDst

The org.vishia.event.EventWithDst is the base form of all vishia event classes. The importance are the elements

2.2. EventCmdtype

The org.vishia.event.EventCmdtype is a basically simple enhancement of the EventWithDst, only some specified command values stored in cmde are added. But because the event is oriented to specified command, not any desired numeric value used as command designation, but a enum, this event is typed with the enum type derived from an ordinary enum:

  public enum Answer{
    noCmd, cont, overwrite, skip, abortFile, abortDir, abortAll
  }

  public final class EventCopyCtrl extends EventCmdtype<Answer> {
    // a derived class

  • You can call sendEvent(cmd) with one of the specified enum values, not with any other. This helps get overview and avoid programming errors.

2.3. EventCmdtypeWithBackEvent

The org.vishia.event.EventCmdtypeWithBackEvent enhances the EventCmdtype with the capability to have a second event for the reverse direction. This is a possible case: One sends an event, and expect an answer. This can be done also with state machines. The received event switches a state, and the transistion can use the event, take the back event which is already prepared for back information to switch another state machine maybe in a remote hardware synchronously. Or also, there is a command to execute via event in another thread, and an answer is expected, the back message is already prepared.

You know it, you get a letter from any society or warehouse, and inside the letter is a prepared letter to send back, you should only mark somewhat, subscribe, ready. Less effort.

2.4. TimeOrder

A org.vishia.event.TimeOrder can be used for any of this events aggregated in EventWithDst. The usage can have two aspects:

  • a) The event should be created after a defined time. This is especially for a timeout in a state machine: The timeout event is planned but not executed immediately. Important: The timeout should be reseted on a state switch.

  • b) The activity in any other thread should be watched, the other thread should send some interim information about its state. This can be used for example for file access operations (copy) with a whole file tree with maybe long files in a remote network location. Such copy actions may need more as some seconds. Secondary questions can be occur. For this aspect the event is used to activate the watch operation in any specific thread whereby the file operation is done in a working thread, also maybe a specific created thread for that. The file operation can usual be done with the java.nio.file approach.

    The TimeOrder in this context is used to organize a repeated cyclically call of the event sending process independent of the executed activity. The activity should only write some informations in the event. Whether or not they are immediately sent as event, or later cyclically, is clarified by the TimeOrder. The TimeOrder is initiated by the executed activity, and repeatedly initiated. The event itself is used as last action on finishing the activity.

    The activity itself can be initiated by an event too, or by any call.

The TimeOrder refers the event, The TimeOrder contains the informations about the time and time organization. The TimeOrder does not contain any information about the event itself, because this informations should not be transferred with the event.

That are different aspects, but solved with the same approach.

  • The

  • - -timeExecution as absolute time stamp.

  • - -timerThread which is a org.vishia.event.EventTimerThread_ifc. The difference to the evDstThread is the following:

    • Both threads can be the same. Then the EventTimerThread can be used for both. The event can be used as timeout as well as also as normal event, respectively the instance is used after expiring the time as an event for this thread.

    • Both threads can be different. This gives the opportunity to have one timer thread and more execution threads, for example for state machines in different priorities.

    • The evDstThread can be given as null, then the event is executed in the timerThread immediately with expiration. The small difference in comparison to give both the same thread is: If a evDstThread is given with the same EventTimerThread, the EventTimout is enqueued firstly in the event queue of this thread. If other events are enqueued before, then firstly the other events are executed. The difference is only slightly, if the timeout comes in the same step cycle as the switching event. But in this particular case it influences the behavior for the state machine. It is not an important difference for practical use, but for test cases.

3. EventTimerThread

xxx

org.vishia.event.EventTimerThread