vpp-api/java/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
  14 === Plugin support
  15
  16   /-------------\        /--------------\          /---------------\
  17   | JvppPlugin1 +<-------+ JVppRegistry +--------->+ VppConnection |
  18   \-------------/  inits \--+-----------/   uses   \---------------/
  19                             |
  20   /-------------\           |
  21   | JvppPlugin2 +<----------+ inits
  22   \-------------/           |
  23                             |
  24   ...                       |
  25                             |
  26   /----------\              |
  27   | JVppCore +<-------------+
  28   \----------/
  29
  30
  31 VppRegistry opens connection to vpp (VppConnection) and manages jvpp plugins.
  32 Each plugin needs to be registered in the VppRegistry. Registration involves
  33 plugin initialization (providing JNI implementation with JVppCallback reference,
  34 vpp client identifier and vpp shared memory queue address).
  35
  36 API user sends message by calling a method of appropriate plugin interface.
  37 The call is delegated to JNI implementation provided by the particular plugin.
  38 When JNI code receives reply, it invokes callback method of JVppCallback
  39 that corresponds to the received message reply.
  40
  41 === JVppCore as an example of JVpp plugin architecture
  42
  43  JVpp Java
  44
  45   /--------------\             /----------\          /------------\    /------\
  46   | JVppRegistry |             | JVppCore |          |  Callbacks |    | DTOs |
  47   \----+---------/             \----+-----/          \------+-----/    \------/
  48        ^                            ^                       ^
  49        | implements                 | implements            | implements
  50   /----+--------------\         /---+----------\      /-----+---------\
  51   | JVppRegistryImpl* +-------->+ JVppCoreImpl |      |  JVppCallback |
  52   \-------+-----------/  inits  \---+----------/      \-------+-------/
  53           |                          |                       ^
  54           |                          | uses                  | calls back
  55           |                          |                       |
  56 ----------|--------------------------|-----------------------|---------------------
  57           |                          |                       |
  58  C JNI    |                          +-------------------+   |       /-----------------\
  59           v                                              |   |   +-->+ jvpp_core_gen.h |
  60   /--------+--------\                                    |   |   |   \-----------------/
  61   | jpp_registry.c* +---+   /--------+----+----\         |   |   |
  62   \-----------------/   |   | << shared lib >> |        /-+--+---+------\
  63                         + ->+   jvpp_common*   <--------+  jvpp_core.c* |
  64                       uses  \------------------/  uses  \---------------/
  65
  66
  67 * Components marked with an asterisk contain manually crafted code, which in addition
  68 to generated classes form jvpp. Exception applies to Callbacks and DTOs, since there are
  69 manually crafted marker interfaces in callback and dto package (dto/JVppRequest, dto/JVppReply,
  70 dto/JVppDump, dto/JVppReplyDump, callback/JVppCallback)
  71
  72 Note: jvpp_core.c calls back the JVppCallback instance with every response. An instance of the
  73 JVppCallback is provided to jvpp_core.c by JVppRegistryImpl on JVppCoreImpl initialization.
  74
  75 Part of the JVpp is also Future facade. It is asynchronous API returning Future objects
  76 on top of low level JVpp. It wraps dump reply messages in one DTO using control_ping message
  77 (provided by JVppRegistry).
  78
  79
  80 Future facade
  81
  82         /----------------\          /---------------\
  83         | FutureJVppCore |      +-->+ JVppRegistry* |
  84         \-----+----------/      |   \---------------/
  85               ^                 |
  86               | implements      | uses
  87               |                 |
  88      /--------+-------------\   |    /------------------------------\
  89      | FutureJVppCoreFacade +---+--->+ FutureJVppCoreFacadeCallback |
  90      \---------+------------/  uses  \-------+----------------------/
  91                |                             |
  92 ---------------|-----------------------------|-------------------------------
  93                | uses                        | implements
  94 JVpp Java      |                             |
  95                |                             |
  96  /----------\  |                             |
  97  | JVppCore +<-+                             |
  98  \----+-----/                                |
  99       ^                                      |
 100       | implements                           v
 101  /----+---------\                   /--------+---------------\
 102  | JVppCoreImpl |                   | JVppCoreGlobalCallback |
 103  \--------------/                   \------------------------/
 104
 105
 106
 107 Another useful utility of the JVpp is Callback facade. It is asynchronous API
 108 capable of calling specific callback instance (provided when performing a call)
 109 per call.
 110
 111
 112 Callback facade
 113
 114         /------------------\          /---------------\
 115         | CallbackJVppCore |      +-->+ JVppRegistry* |
 116         \-----+------------/      |   \---------------/
 117               ^                   |
 118               | implements        | uses
 119               |                   |
 120      /--------+---------------\   |    /--------------------------\
 121      | CallbackJVppCoreFacade +---+--->+ CallbackJVppCoreCallback |
 122      \---------+--------------/  uses  \-----+--------------------/
 123                |                             |
 124 ---------------|-----------------------------|-------------------------------
 125                | uses                        | implements
 126 JVpp Java      |                             |
 127                |                             |
 128  /----------\  |                             |
 129  | JVppCore +<-+                             |
 130  \----+-----/                                |
 131       ^                                      |
 132       | implements                           v
 133  /----+---------\                   /----------+-------------\
 134  | JVppCoreImpl |                   | JVppCoreGlobalCallback |
 135  \--------------/                   \------------------------/
 136
 137
 138 == Package structure
 139
 140 * *io.fd.vpp.jvpp* - top level package for generated JVpp interface+ implementation and hand-crafted
 141 VppConnection interface + implementation - packaged as jvpp-registry-version.jar
 142
 143 * *io.fd.vpp.jvpp.[plugin]* - top level package for generated JVpp interface + implementation
 144 + plugin's API tests - packaged as jvpp-[plugin]-version.jar
 145
 146 ** *dto* - package for DTOs generated from VPP API structures + base/marker hand-crafted interfaces
 147 (in case of jvpp-registry)
 148 ** *callback* - package for low-level JVpp callbacks and a global callback interface implementing each of
 149 the low-level JVppcallbacks
 150 ** *future* - package for future based facade on top of JVpp and callbacks
 151 ** *callfacade* - package for callback based facade on top of JVpp and callbacks. Allowing
 152 users to provide callback per request
 153 ** *test* - package for JVpp standalone tests. Can also serve as samples for JVpp.
 154
 155 C code is structured into modules:
 156
 157 * *jvpp_common* - shared library that provides jvpp_main_t reference used by jvpp_registry and plugins.
 158
 159 * *jvpp_registry* - native library used by JVppRegistryImpl, responsible for:
 160
 161 ** VPP connection open/close
 162 ** Rx thread to java thread attach
 163 ** control ping message handling
 164
 165 * *jvpp_core* - native library used by jvpp core plugin:
 166 ** *jvpp_core.c* - contains hand crafted code for core plugin initialization
 167 ** *jvpp_core_gen.h* - contains generated JNI compatible handlers for all requests and replies defined in vpe.api
 168
 169 == Code generators
 170 All of the required code except the base/marker interfaces is generated using
 171 simple python2 code generators. The generators use __defs_vpp_papi.py__ input
 172 file produced by __vppapigen__ from vpe.api file.
 173
 174 === JNI compatible C code
 175 Produces __jvpp_[plugin]_gen.h__ file containing JNI compatible handlers for each VPP
 176 request and reply.
 177
 178 [NOTE]
 179 ====
 180 Source: jvpp_c_gen.py
 181 ====
 182
 183 === Request/Reply DTOs
 184 For all the structures in __defs_vpp_papi.py__ a POJO DTO is produced. Logically,
 185 there are 4 types of DTOs:
 186
 187 * Request - requests that can be sent to VPP and only a single response is expected
 188 * DumpRequest - requests that can be sent to VPP and a stream of responses is expected
 189 * Reply - reply to a simple request or a single response from dump triggered response stream
 190 * ReplyDump - collection of replies from a single dump request
 191 * Notifications/Events - Not implemented yet
 192
 193 [NOTE]
 194 ====
 195 Source: dto_gen.py
 196 ====
 197
 198 === JVpp
 199 Produces __JVpp.java__ and __JVppImpl.java__. This is the layer right above JNI compatible C
 200 code.
 201
 202 [NOTE]
 203 ====
 204 Source: jvpp_impl_gen.py
 205 ====
 206
 207 === Callbacks
 208 Produces callback interface for each VPP reply + a global callback interface called
 209 __JVpp[plugin]GlobalCallback.java__ aggregating all of the callback interfaces. The JNI
 210 compatible C code expects only a single instance of this global callback and calls
 211 it with every reply.
 212
 213 [NOTE]
 214 ====
 215 Source: callback_gen.py
 216 ====
 217
 218 === Future facade
 219 Produces an asynchronous facade on top of JVpp and callbacks, which returns a Future that provides
 220 matching reply once VPP invocation finishes. Sources produced:
 221 __FutureJVpp[plugin].java, FutureJVpp[plugin]Facade.java and FutureJVpp[plugin]Callback.java__
 222
 223 [NOTE]
 224 ====
 225 Source: jvpp_future_facade_gen.py
 226 ====
 227
 228 === Callback facade
 229 Similar to future facade, only this facade takes callback objects as part of the invocation
 230 and the callback is called with result once VPP invocation finishes. Sources produced:
 231 __CallbackJVpp[plugin].java, CallbackJVpp[plugin]Facade.java and CallbackJVpp[plugin]Callback.java__
 232
 233 [NOTE]
 234 ====
 235 Source: jvpp_callback_facade_gen.py
 236 ====