| = JVpp |
| |
| JVpp is JNI based Java API for VPP. |
| |
| == Features |
| It is: |
| |
| * Asynchronous |
| * Fully generated |
| * Lightweight |
| |
| == Architecture |
| |
| === Plugin support |
| |
| /-------------\ /--------------\ /---------------\ |
| | JvppPlugin1 +<-------+ JVppRegistry +--------->+ VppConnection | |
| \-------------/ inits \--+-----------/ uses \---------------/ |
| | |
| /-------------\ | |
| | JvppPlugin2 +<----------+ inits |
| \-------------/ | |
| | |
| ... | |
| | |
| /----------\ | |
| | JVppCore +<-------------+ |
| \----------/ |
| |
| |
| VppRegistry opens connection to vpp (VppConnection) and manages jvpp plugins. |
| Each plugin needs to be registered in the VppRegistry. Registration involves |
| plugin initialization (providing JNI implementation with JVppCallback reference, |
| vpp client identifier and vpp shared memory queue address). |
| |
| API user sends message by calling a method of appropriate plugin interface. |
| The call is delegated to JNI implementation provided by the particular plugin. |
| When JNI code receives reply, it invokes callback method of JVppCallback |
| that corresponds to the received message reply. |
| |
| === JVppCore as an example of JVpp plugin architecture |
| |
| JVpp Java |
| |
| /--------------\ /----------\ /------------\ /------\ |
| | JVppRegistry | | JVppCore | | Callbacks | | DTOs | |
| \----+---------/ \----+-----/ \------+-----/ \------/ |
| ^ ^ ^ |
| | implements | implements | implements |
| /----+--------------\ /---+----------\ /-----+---------\ |
| | JVppRegistryImpl* +-------->+ JVppCoreImpl | | JVppCallback | |
| \-------+-----------/ inits \---+----------/ \-------+-------/ |
| | | ^ |
| | | uses | calls back |
| | | | |
| ----------|--------------------------|-----------------------|--------------------- |
| | | | |
| C JNI | +-------------------+ | /-----------------\ |
| v | | +-->+ jvpp_core_gen.h | |
| /--------+--------\ | | | \-----------------/ |
| | jpp_registry.c* +---+ /--------+----+----\ | | | |
| \-----------------/ | | << shared lib >> | /-+--+---+------\ |
| + ->+ jvpp_common* <--------+ jvpp_core.c* | |
| uses \------------------/ uses \---------------/ |
| |
| |
| * Components marked with an asterisk contain manually crafted 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_core.c calls back the JVppCallback instance with every response. An instance of the |
| JVppCallback is provided to jvpp_core.c by JVppRegistryImpl on JVppCoreImpl initialization. |
| |
| Part of the JVpp is also Future facade. It is asynchronous API returning Future objects |
| on top of low level JVpp. It wraps dump reply messages in one DTO using control_ping message |
| (provided by JVppRegistry). |
| |
| |
| Future facade |
| |
| /----------------\ /---------------\ |
| | FutureJVppCore | +-->+ JVppRegistry* | |
| \-----+----------/ | \---------------/ |
| ^ | |
| | implements | uses |
| | | |
| /--------+-------------\ | /------------------------------\ |
| | FutureJVppCoreFacade +---+--->+ FutureJVppCoreFacadeCallback | |
| \---------+------------/ uses \-------+----------------------/ |
| | | |
| ---------------|-----------------------------|------------------------------- |
| | uses | implements |
| JVpp Java | | |
| | | |
| /----------\ | | |
| | JVppCore +<-+ | |
| \----+-----/ | |
| ^ | |
| | implements v |
| /----+---------\ /--------+---------------\ |
| | JVppCoreImpl | | JVppCoreGlobalCallback | |
| \--------------/ \------------------------/ |
| |
| |
| |
| 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 |
| |
| /------------------\ /---------------\ |
| | CallbackJVppCore | +-->+ JVppRegistry* | |
| \-----+------------/ | \---------------/ |
| ^ | |
| | implements | uses |
| | | |
| /--------+---------------\ | /--------------------------\ |
| | CallbackJVppCoreFacade +---+--->+ CallbackJVppCoreCallback | |
| \---------+--------------/ uses \-----+--------------------/ |
| | | |
| ---------------|-----------------------------|------------------------------- |
| | uses | implements |
| JVpp Java | | |
| | | |
| /----------\ | | |
| | JVppCore +<-+ | |
| \----+-----/ | |
| ^ | |
| | implements v |
| /----+---------\ /----------+-------------\ |
| | JVppCoreImpl | | JVppCoreGlobalCallback | |
| \--------------/ \------------------------/ |
| |
| |
| == Package structure |
| |
| * *io.fd.vpp.jvpp* - top level package for generated JVpp interface+ implementation and hand-crafted |
| VppConnection interface + implementation - packaged as jvpp-registry-version.jar |
| |
| * *io.fd.vpp.jvpp.[plugin]* - top level package for generated JVpp interface + implementation |
| + plugin's API tests - packaged as jvpp-[plugin]-version.jar |
| |
| ** *dto* - package for DTOs generated from VPP API structures + base/marker hand-crafted interfaces |
| (in case of jvpp-registry) |
| ** *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 modules: |
| |
| * *jvpp_common* - shared library that provides jvpp_main_t reference used by jvpp_registry and plugins. |
| |
| * *jvpp_registry* - native library used by JVppRegistryImpl, responsible for: |
| |
| ** VPP connection open/close |
| ** Rx thread to java thread attach |
| ** control ping message handling |
| |
| * *jvpp_core* - native library used by jvpp core plugin: |
| ** *jvpp_core.c* - contains hand crafted code for core plugin initialization |
| ** *jvpp_core_gen.h* - contains generated JNI compatible handlers for all requests and replies defined in vpe.api |
| |
| == 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_[plugin]_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 |
| __JVpp[plugin]GlobalCallback.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[plugin].java, FutureJVpp[plugin]Facade.java and FutureJVpp[plugin]Callback.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[plugin].java, CallbackJVpp[plugin]Facade.java and CallbackJVpp[plugin]Callback.java__ |
| |
| [NOTE] |
| ==== |
| Source: jvpp_callback_facade_gen.py |
| ==== |