diff options
Diffstat (limited to 'vpp-api/java/jvpp/Readme.txt')
| -rw-r--r-- | vpp-api/java/jvpp/Readme.txt | 201 |
1 files changed, 0 insertions, 201 deletions
diff --git a/vpp-api/java/jvpp/Readme.txt b/vpp-api/java/jvpp/Readme.txt deleted file mode 100644 index 9b759e09a44..00000000000 --- a/vpp-api/java/jvpp/Readme.txt +++ /dev/null @@ -1,201 +0,0 @@ -= JVpp - -JVpp is JNI based Java API for VPP. - -== Features -It is: - -* Asynchronous -* Fully generated -* Lightweight - -== Architecture -JVpp and JNI - - - JVpp Java - - /----------\ /--------\ /------------\ /------\ - | VppConn* | | JVpp | | Callbacks | | DTOs | - \----+-----/ \----+---/ \------+-----/ \------/ - ^ ^ ^ - | implements | implements | implements - /----+---------\ /----+-------\ /------+-----------\ - | VppConnImpl* +<--------+ JVppImpl | | GlobalCallback | - \--------------/ uses \---+--------/ \-------+----------/ - | ^ - | uses | calls back - | | --------------------------------|-----------------------|--------------------- - | | - | +---------------+ - C JNI | | - v | /------------\ - /---+-------+--\ +---->+ jvpp.h* | - | +-----+ \------------/ - | jvpp.c* | - | +-----+ /------------\ - \--------------/ +---->+ jvpp_gen.h | - \------------/ - -* Components marked with an asterisk contain manually crafted Java code, which in addition -to generated classes form jvpp. Exception applies to Callbacks and DTOs, since there are -manually crafted marker interfaces in callback and dto package (dto/JVppRequest, dto/JVppReply, -dto/JVppDump, dto/JVppReplyDump, callback/JVppCallback) - -Note: jvpp.c calls back the GlobalCallback instance with every response. An instance of the -GlobalCallback is provided to jvpp.c by VppConnImpl while connecting to VPP. - -Part of the JVpp is also Future facade. It is asynchronous API returning Future objects -on top of low level JVpp. - - -Future facade - - /-------------\ /--------------------\ - | FutureJVpp* | +-->+ FutureJVppRegistry | - \-----+-------/ | \----------+---------/ - ^ | ^ - | implements | uses | uses - | | | - /--------+----------\ | /----------+---------\ - | FutureJVppFacade* +----+ | FutureJVppCallback | - \---------+---------/ \----------+---------/ - | | ----------------|-----------------------------|------------------------------- - | uses | implements -JVpp Java | | - | | - /---------\ | | - | JVpp +<--+ | - \----+----/ | - ^ | - | implements v - /----+-------\ /----------+-------\ - | JVppImpl | | GlobalCallback | - \------------/ \------------------/ - - - -Another useful utility of the JVpp is Callback facade. It is asynchronous API -capable of calling specific callback instance (provided when performing a call) -per call. - - -Callback facade - - /--------------\ /----------------------\ - | CallbackJVpp | +-->+ CallbackJVppRegistry | - \-----+--------/ | \----------+-----------/ - ^ | ^ - | implements | uses | uses - | | | - /--------+-----------\ | /----------+-----------\ - | CallbackJVppFacade +-----+ | CallbackJVppCallback | - \---------+----------/ \----------+-----------/ - | | ----------------|-----------------------------|------------------------------- - | uses | implements -JVpp Java | | - | | - /---------\ | | - | JVpp +<--+ | - \----+----/ | - ^ | - | implements v - /----+-------\ /----------+-------\ - | JVppImpl | | GlobalCallback | - \------------/ \------------------/ - - - -== Package structure - -* *org.openvpp.jvpp* - top level package for generated JVpp interface+ implementation and hand-crafted -VppConnection interface + implementation - -** *dto* - package for DTOs generated from VPP API structures + base/marker hand-crafted interfaces -** *callback* - package for low-level JVpp callbacks and a global callback interface implementing each of the low-level JVppcallbacks -** *future* - package for future based facade on top of JVpp and callbacks -** *callfacade* - package for callback based facade on top of JVpp and callbacks. Allowing -users to provide callback per request -** *test* - package for JVpp standalone tests. Can also serve as samples for JVpp. - -C code is structured into 3 files: - -* *jvpp.c* - includes jvpp.h and jvpp_gen.h + contains hand crafted code for: - -** VPP connection open/close -** Rx thread to java thread attach -** Callback instance store -* *jvpp.h* - contains hand-crafted macros and structures used by jvpp.c -* *jvpp_gen.h* - contains JNI compatible handlers for each VPP request and reply - -== Code generators -All of the required code except the base/marker interfaces is generated using -simple python2 code generators. The generators use __defs_vpp_papi.py__ input -file produced by __vppapigen__ from vpe.api file. - -=== JNI compatible C code -Produces __jvpp_gen.h__ file containing JNI compatible handlers for each VPP -request and reply. - -[NOTE] -==== -Source: jvpp_c_gen.py -==== - -=== Request/Reply DTOs -For all the structures in __defs_vpp_papi.py__ a POJO DTO is produced. Logically, -there are 4 types of DTOs: - -* Request - requests that can be sent to VPP and only a single response is expected -* DumpRequest - requests that can be sent to VPP and a stream of responses is expected -* Reply - reply to a simple request or a single response from dump triggered response stream -* ReplyDump - collection of replies from a single dump request -* Notifications/Events - Not implemented yet - -[NOTE] -==== -Source: dto_gen.py -==== - -=== JVpp -Produces __JVpp.java__ and __JVppImpl.java__. This is the layer right above JNI compatible C -code. - -[NOTE] -==== -Source: jvpp_impl_gen.py -==== - -=== Callbacks -Produces callback interface for each VPP reply + a global callback interface called -__JVppGlobalCallback.java__ aggregating all of the callback interfaces. The JNI -compatible C code expects only a single instance of this global callback and calls -it with every reply. - -[NOTE] -==== -Source: callback_gen.py -==== - -=== Future facade -Produces an asynchronous facade on top of JVpp and callbacks, which returns a Future that provides -matching reply once VPP invocation finishes. Sources produced: -__FutureJVpp.java, FutureJVppFacade.java and FutureJVppCallback.java__ - -[NOTE] -==== -Source: jvpp_future_facade_gen.py -==== - -=== Callback facade -Similar to future facade, only this facade takes callback objects as part of the invocation -and the callback is called with result once VPP invocation finishes. Sources produced: -__CallbackJVpp.java, CallbackJVppFacade.java and CallbackJVppCallback.java__ - -[NOTE] -==== -Source: jvpp_callback_facade_gen.py -==== |