org.vishia.inspcPC.accTarget

Class InspcTargetAccessor

java.lang.Object

org.vishia.inspcPC.accTarget.InspcTargetAccessor

All Implemented Interfaces:

InspcAccess_ifc

public class InspcTargetAccessor
extends java.lang.Object
implements InspcAccess_ifc

An instance of this class accesses one target device via InterProcessCommunication, usual Ethernet-Sockets. This class gets an opened InterProcessComm from its InspcCommPort aggregate. The InspcCommPort has created a receiving thread.

Object model diagram:

• The InspcMng knows one or more InspcTargetAccessor-instances, indicated by its name. The name of the target access is the first part of the data path to a target: "name:path.in.target"
• Any of that InspcTargetAccessor handles the datagrams to and from one target.
• More as one InspcTargetAccessor or all one can handle their communication via only one instance of InspcCommPort.
• The InspcCommPort associates an InterProcessComm interface which is implemented by the InterProcessComm_SocketImpl or maybe for a serial communication or Dual-Port-RAM or other. It means the communication connection to a target can be done in several ways independent of the mission of this class.

See also:

.../vishia/Inspc/InspcComm.html or www.vishia.org/Inspc/InspcComm.html

A send requests are invoked from the environment, it is the InspcMng.

• Firstly isOrSetReady(long) is invoked to see whether a communication task is pending yet.
• If a communication is pending for this target, new requests should be deferred.
• If the communication hangs, isOrSetReady(long) clears the communication to this target and returns true if the given timeout is expired: It is possible to unplug a target - it does not answer - and plug again later. The target does not repeat the lost answers. But it is ready for new communication. The timeout should be a proper time for the target. If it is to less, the target may prepare the answer yet in the moment and it is disturbed hectically. The timeout should be acceptable for usage. About 5 seconds may be a proper value.
• If the communication is not pending, isOrSetReady(long) returns true.
• Then some requests can be prepared by invocation of the methods of the InspcAccess_ifc cmdGet/Set.... With them one or more datagrams are prepared.
• The requests contain a callback reference to a InspcAccessExecRxOrder_ifc. Thats InspcAccessExecRxOrder_ifc.execInspcRxOrder(org.vishia.communication.InspcDataExchangeAccess.Inspcitem, long, LogMessage, int) is executed if the response item is received. With the order-number-concept see InspcDataExchangeAccess.Inspcitem#getOrder() the request and the response are associated together.
• At least cmdFinit() should be invoked. That completes the one or last datagram and forces sending to the target.

The following sequence shows that. This sequence is executed in one thread for cyclic communication.

        
 InspcMng                  this                 txAccess   commPort     ipc
  |                          |                                 |            |
  ~                          ~                                 ~            ~
  +procComm():               |                                 |            |
  +--isOrSetReady(...)------>|                      |          |            | 
  +--cmdGetSet...----------->|--->addChild--------->|          |            | 
  +--isOrSetReady(...)------>|                      |          |            | 
  +--cmdGetSet...----------->|--->addChild--------->|          |            | 
  +--cmdGetSet...----------->|--->addChild--------->|          |            | 
  +                          |--completeDatagram()->|          |            | 
  +--cmdGetSet...----------->|--->addChild--------->|          |            | 
  +--cmdGetSet...----------->|--->addChild--------->|          |            | 
  +                          |                      |          |            | 
  +-->cmdFinit()------------>|--completeDatagram()->|          |            | 
  |                  [bTaskPending = true]                     |            | 
  |                          |---send(txBuffer)--------------->|--send----->| 
  |                          |                                 |            | 
  ~                          ~                                 ~            ~ 
 

Therewith up to 10 datagrams are assembled. Only the first datagram is sent yet. The target may answer:

• An answer may need more as one answer datagram. The received datagrams are checked whether they have the correct sequence and answer number. Only then they are stored in _tdata InspcTargetAccessor.TelgData.rxDatagram. This is done in evaluateRxTelg(byte[], int).
• The answer datagrams don't need to receive in the correct order. There are filled some bits InspcTargetAccessor.TelgData.rxBitsAnswerNr. An datagram which is received twice is ignored as twice.
• The last answer datagram is marked with InspcDataExchangeAccess.InspcDatagram#lastAnswer(), a special bit. With them is can be recognized that all datagrams are completely received.

 
                           this                              commPort      ipc
                             |                                 |            !
                             ~                                 ~            ~<<==
                             |                                 !            !   "
                             !                                 !<..receive..!   "
                 [rxDatagram]!<---evaluateRxTelg(datagram)-----!            !   "
                 [rxDatagram]!<---evaluateRxTelg(datagram)-----!            !   "
                             !                                 !            !   "
                             ~                                 ~            ~   "
 

• The cyclic InspcMng.procComm() invokes evaluateRxTelgInspcThread() cyclically. This routine checks whether all datagrams of one request datagram are received. It invokes evaluateOneDatagram(org.vishia.communication.InspcDataExchangeAccess.InspcDatagram, InspcAccessExecRxOrder_ifc, long, LogMessage, int, DebugTxRx, int) internally for each of the received datagrams.
• The data of the datagram are evaluated using the InspcDataExchangeAccess.Inspcitem for each item. That is derived from ByteDataAccessBase which converts the byte data in the datagram to user specifics.
• For each item the InspcDataExchangeAccess.Inspcitem#getOrder() is read. With them and the stored InspcAccessExecRxOrder_ifc is searched in the ordersExpected index.
• The InspcAccessExecRxOrder_ifc.execInspcRxOrder(org.vishia.communication.InspcDataExchangeAccess.Inspcitem, long, LogMessage, int) is invoked with the received datagram item. That is the callback to the users level with the received information.
• If the datagram is evaluated, the routine evaluateRxTelgInspcThread() looks whether a next datagram with assembled requests are given furthermore. Then it sends is to the target.
• With a next send() this sequence is repeated.

 InspcMng                                this                                                 "
  |                                        |                                                  "
  ~                                        ~                                                  "
  +procComm():                             |                                                  "
  +-evaluateRxTelgInspcThread()-->|[rxDatagram]                                      "
  +                                        |-evaluateOneDatagram()-+            Requestor     "
  +                                        +<----------------------+                  |       "
  +                                        +----execInspcRxOrder(datagramitem, ...)-->|       "
  +                                        +----execInspcRxOrder(datagramitem, ...)-->|       "
  +                                        +----execInspcRxOrder(datagramitem, ...)-->|       "
  +                                        +----execInspcRxOrder(datagramitem, ...)-->|       "
  +                                        +                                          |       "
  +                                        +                                                  "
  +                                        +                               commPort      ipc  "
  +                                        +                                 |            |   "
  +                                        +---send(txBuffer)--------------->|...........>|   "
  +<.......................................+                                 |            |   "
  |                                        |                                 |            |   "
  |                                        |                                 |            |   "
  ~                                        ~                                 ~            ~====
 

The communication is still pending yet. Next requests from user level are deferred till this repetition of send() and evaluateRxTelgInspcThread() is currently.

If all datagrams are sent and all answers are received:

 InspcMng                  this                                                 "
  |                          |                                                  "
  ~                          ~                                 ~            ~
  |                          |[on last datagram:    ]
  |                          |[bTaskPending = false;]
  |                          |
  ~                          ~
  |--isOrSetReady(...)------>|   //the next communication cycle
  |                             
  

The cmdGetSet routines are:

• cmdGetFields(String, InspcAccessExecRxOrder_ifc)
• cmdGetValueByPath(String, InspcAccessExecRxOrder_ifc)
• cmdRegisterHandle(String, InspcAccessExecRxOrder_ifc)
• cmdGetValueByHandle(int, InspcAccessExecRxOrder_ifc)
• cmdGetAddressByPath(String, InspcAccessExecRxOrder_ifc)
• #cmdSetValueByPath(String, double, InspcAccessExecRxOrder_ifc)
• #cmdSetValueByPath(String, float, InspcAccessExecRxOrder_ifc)
• #cmdSetValueByPath(String, int, InspcAccessExecRxOrder_ifc)
• cmdSetValueByPath(String, long, int, InspcAccessExecRxOrder_ifc)

The routines organizes the datagram. If one datagram is full, the next instance is used. There are 10 instances of InspcTargetAccessor.TxBuffer.

At least the user should invoke cmdFinit(). That command completes the only one or the last datagram and sends the first datagram to the target. With this invocation the #isReady(long) returns false because the variable bTaskPending is set to true.

The target should response with the answer with the same sequence number to associate answer and request. The commPort (InspcCommPort) gets the received telegram. On comparison of the sender address in the datagram or on comparison of the entrant in the datagram's head InspcDataExchangeAccess.InspcDatagram#getEntrant(). The answer from target can consist of more as one datagram. Any correct answer telegram invokes evaluateRxTelg(byte[], int). The answer contains some InspcDataExchangeAccess.Inspcitem. All of them has its order number. With the order number the associated #execInspcRxOrder(org.vishia.communication.InspcDataExchangeAccess.Inspcitem, long, LogMessage, int) is invoked as callback in the users space. This is organized in the aggregated #rxEval instance.

If the last answer datagram of a request is gotten, the next datagram of this task will be sent to the target. The target will be attacked only by one telegram in one time, all one after another. That is because a target may have less network resources (a cheap processor etc.). After the last receive datagram of the last send datagram the semaphore bTaskPending is set to false, a next #isReady(long) returns true for the next task of requests.

On receive the commPort (InspcCommPort) gets the received telegram. On comparison of the sender address in the datagram or on comparison of the entrant in the datagram's head InspcDataExchangeAccess.InspcDatagram#getEntrant().

Requests in multithreading
The routines cmdGetValueByPath(String, InspcAccessExecRxOrder_ifc) etc. are not threadsafe. That is because the organization of a datagram content should be controlled by one hand. Typically this only one thread runs cyclically because it requests currently data.
To support requests in more as one thread two strategies are supported:

• A thread can assemble its own datagram and then add to the cyclic communication thread.
• A thread can invoke simple request items which are stored in a ConcurrentLinkedQueue and regarded on next cyclic call.

In both cases the #execInspcRxOrder(org.vishia.communication.InspcDataExchangeAccess.Inspcitem, long, LogMessage, int) is invoked by the receiver's thread called back in the user's space. This routines can be used to notify any waiting thread or any short action can be done in the callback, especially request of some more cmd...