vpp-api/java/jvpp/Readme.txt

   1 = JVpp
   2
   3 JVpp is JNI based Java API for VPP.
   4
   5 == Features
   6 It is:
   7
   8 * Asynchronous
   9 * Fully generated
  10 * Lightweight
  11
  12 == Architecture
  13 JVpp and JNI
  14
  15
  16  JVpp Java
  17
  18   /----------\             /--------\          /------------\    /------\
  19   | VppConn* |             |  JVpp  |          |  Callbacks |    | DTOs |
  20   \----+-----/             \----+---/          \------+-----/    \------/
  21        ^                        ^                     ^
  22        | implements             | implements          | implements
  23   /----+---------\         /----+-------\      /------+-----------\
  24   | VppConnImpl* +<--------+  JVppImpl  |      |  GlobalCallback  |
  25   \--------------/   uses  \---+--------/      \-------+----------/
  26                                |                       ^
  27                                | uses                  | calls back
  28                                |                       |
  29 -------------------------------|-----------------------|---------------------
  30                                |                       |
  31                                |       +---------------+
  32  C JNI                         |       |
  33                                v       |              /------------\
  34                            /---+-------+--\     +---->+   jvpp.h*  |
  35                            |              +-----+     \------------/
  36                            |    jvpp.c*   |
  37                            |              +-----+     /------------\
  38                            \--------------/     +---->+ jvpp_gen.h |
  39                                                       \------------/
  40
  41 * Components marked with an asterisk contain manually crafted Java code, which in addition
  42 to generated classes form jvpp. Exception applies to Callbacks and DTOs, since there are
  43 manually crafted marker interfaces in callback and dto package (dto/JVppRequest, dto/JVppReply,
  44 dto/JVppDump, dto/JVppReplyDump, callback/JVppCallback)
  45
  46 Note: jvpp.c calls back the GlobalCallback instance with every response. An instance of the
  47 GlobalCallback is provided to jvpp.c by VppConnImpl while connecting to VPP.
  48
  49 Part of the JVpp is also Future facade. It is asynchronous API returning Future objects
  50 on top of low level JVpp.
  51
  52
  53 Future facade
  54
  55         /-------------\           /--------------------\
  56         | FutureJVpp* |       +-->+ FutureJVppRegistry |
  57         \-----+-------/       |   \----------+---------/
  58               ^               |              ^
  59               | implements    | uses         | uses
  60               |               |              |
  61      /--------+----------\    |   /----------+---------\
  62      | FutureJVppFacade* +----+   | FutureJVppCallback |
  63      \---------+---------/        \----------+---------/
  64                |                             |
  65 ---------------|-----------------------------|-------------------------------
  66                | uses                        | implements
  67 JVpp Java      |                             |
  68                |                             |
  69  /---------\   |                             |
  70  |   JVpp  +<--+                             |
  71  \----+----/                                 |
  72       ^                                      |
  73       | implements                           v
  74  /----+-------\                   /----------+-------\
  75  |  JVppImpl  |                   |  GlobalCallback  |
  76  \------------/                   \------------------/
  77
  78
  79
  80 Another useful utility of the JVpp is Callback facade. It is asynchronous API
  81 capable of calling specific callback instance (provided when performing a call)
  82 per call.
  83
  84
  85 Callback facade
  86
  87         /--------------\            /----------------------\
  88         | CallbackJVpp |        +-->+ CallbackJVppRegistry |
  89         \-----+--------/        |   \----------+-----------/
  90               ^                 |              ^
  91               | implements      | uses         | uses
  92               |                 |              |
  93      /--------+-----------\     |   /----------+-----------\
  94      | CallbackJVppFacade +-----+   | CallbackJVppCallback |
  95      \---------+----------/         \----------+-----------/
  96                |                             |
  97 ---------------|-----------------------------|-------------------------------
  98                | uses                        | implements
  99 JVpp Java      |                             |
 100                |                             |
 101  /---------\   |                             |
 102  |   JVpp  +<--+                             |
 103  \----+----/                                 |
 104       ^                                      |
 105       | implements                           v
 106  /----+-------\                   /----------+-------\
 107  |  JVppImpl  |                   |  GlobalCallback  |
 108  \------------/                   \------------------/
 109
 110
 111
 112 == Package structure
 113
 114 * *org.openvpp.jvpp* - top level package for generated JVpp interface+ implementation and hand-crafted
 115 VppConnection interface + implementation
 116
 117 ** *dto* - package for DTOs generated from VPP API structures + base/marker hand-crafted interfaces
 118 ** *callback* - package for low-level JVpp callbacks and a global callback interface implementing each of the low-level JVppcallbacks
 119 ** *future* - package for future based facade on top of JVpp and callbacks
 120 ** *callfacade* - package for callback based facade on top of JVpp and callbacks. Allowing
 121 users to provide callback per request
 122 ** *test* - package for JVpp standalone tests. Can also serve as samples for JVpp.
 123
 124 C code is structured into 3 files:
 125
 126 * *jvpp.c* - includes jvpp.h and jvpp_gen.h + contains hand crafted code for:
 127
 128 ** VPP connection open/close
 129 ** Rx thread to java thread attach
 130 ** Callback instance store
 131 * *jvpp.h* - contains hand-crafted macros and structures used by jvpp.c
 132 * *jvpp_gen.h* - contains JNI compatible handlers for each VPP request and reply
 133
 134 == Code generators
 135 All of the required code except the base/marker interfaces is generated using
 136 simple python2 code generators. The generators use __defs_vpp_papi.py__ input
 137 file produced by __vppapigen__ from vpe.api file.
 138
 139 === JNI compatible C code
 140 Produces __jvpp_gen.h__ file containing JNI compatible handlers for each VPP
 141 request and reply.
 142
 143 [NOTE]
 144 ====
 145 Source: jvpp_c_gen.py
 146 ====
 147
 148 === Request/Reply DTOs
 149 For all the structures in __defs_vpp_papi.py__ a POJO DTO is produced. Logically,
 150 there are 4 types of DTOs:
 151
 152 * Request - requests that can be sent to VPP and only a single response is expected
 153 * DumpRequest - requests that can be sent to VPP and a stream of responses is expected
 154 * Reply - reply to a simple request or a single response from dump triggered response stream
 155 * ReplyDump - collection of replies from a single dump request
 156 * Notifications/Events - Not implemented yet
 157
 158 [NOTE]
 159 ====
 160 Source: dto_gen.py
 161 ====
 162
 163 === JVpp
 164 Produces __JVpp.java__ and __JVppImpl.java__. This is the layer right above JNI compatible C
 165 code.
 166
 167 [NOTE]
 168 ====
 169 Source: jvpp_impl_gen.py
 170 ====
 171
 172 === Callbacks
 173 Produces callback interface for each VPP reply + a global callback interface called
 174 __JVppGlobalCallback.java__ aggregating all of the callback interfaces. The JNI
 175 compatible C code expects only a single instance of this global callback and calls
 176 it with every reply.
 177
 178 [NOTE]
 179 ====
 180 Source: callback_gen.py
 181 ====
 182
 183 === Future facade
 184 Produces an asynchronous facade on top of JVpp and callbacks, which returns a Future that provides
 185 matching reply once VPP invocation finishes. Sources produced:
 186 __FutureJVpp.java, FutureJVppFacade.java and FutureJVppCallback.java__
 187
 188 [NOTE]
 189 ====
 190 Source: jvpp_future_facade_gen.py
 191 ====
 192
 193 === Callback facade
 194 Similar to future facade, only this facade takes callback objects as part of the invocation
 195 and the callback is called with result once VPP invocation finishes. Sources produced:
 196 __CallbackJVpp.java, CallbackJVppFacade.java and CallbackJVppCallback.java__
 197
 198 [NOTE]
 199 ====
 200 Source: jvpp_callback_facade_gen.py
 201 ====