3 JVpp is JNI based Java API for VPP.
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
23 /----------\ /--------\ /------------\ /------\
24 | VppConn* | | JVpp | | Callbacks | | DTOs |
25 \----+-----/ \----+---/ \------+-----/ \------/
27 | implements | implements | implements
28 /----+---------\ /----+-------\ /------+-----------\
29 | VppConnImpl* +<--------+ JVppImpl | | GlobalCallback |
30 \--------------/ uses \---+--------/ \-------+----------/
34 -------------------------------|-----------------------|---------------------
39 /---+-------+--\ +---->+ jvpp.h* |
40 | +-----+ \------------/
42 | +-----+ /------------\
43 \--------------/ +---->+ jvpp_gen.h |
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)
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.
54 Part of the JVpp is also Future facade. It is asynchronous API returning Future objects
55 on top of low level JVpp.
60 /-------------\ /--------------------\
61 | FutureJVpp* | +-->+ FutureJVppRegistry |
62 \-----+-------/ | \----------+---------/
64 | implements | uses | uses
66 /--------+----------\ | /----------+---------\
67 | FutureJVppFacade* +----+ | FutureJVppCallback |
68 \---------+---------/ \----------+---------/
70 ---------------|-----------------------------|-------------------------------
79 /----+-------\ /----------+-------\
80 | JVppImpl | | GlobalCallback |
81 \------------/ \------------------/
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)
92 /--------------\ /----------------------\
93 | CallbackJVpp | +-->+ CallbackJVppRegistry |
94 \-----+--------/ | \----------+-----------/
96 | implements | uses | uses
98 /--------+-----------\ | /----------+-----------\
99 | CallbackJVppFacade +-----+ | CallbackJVppCallback |
100 \---------+----------/ \----------+-----------/
102 ---------------|-----------------------------|-------------------------------
111 /----+-------\ /----------+-------\
112 | JVppImpl | | GlobalCallback |
113 \------------/ \------------------/
119 * *org.openvpp.jvpp* - top level package for generated JVpp interface+ implementation and hand-crafted
120 VppConnection interface + implementation
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.
129 C code is structured into 3 files:
131 * *jvpp.c* - includes jvpp.h and jvpp_gen.h + contains hand crafted code for:
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
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.
144 === JNI compatible C code
145 Produces __jvpp_gen.h__ file containing JNI compatible handlers for each VPP
150 Source: jvpp_c_gen.py
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:
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
169 Produces __JVpp.java__ and __JVppImpl.java__. This is the layer right above JNI compatible C
174 Source: jvpp_impl_gen.py
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
185 Source: callback_gen.py
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__
195 Source: jvpp_future_facade_gen.py
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__
205 Source: jvpp_callback_facade_gen.py