202 lines
7.7 KiB
Plaintext
202 lines
7.7 KiB
Plaintext
|
= 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
|
||
|
====
|