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