diff options
Diffstat (limited to 'vpp-api/java/jvpp/Readme.txt')
| -rw-r--r-- | vpp-api/java/jvpp/Readme.txt | 201 |
1 files changed, 201 insertions, 0 deletions
diff --git a/vpp-api/java/jvpp/Readme.txt b/vpp-api/java/jvpp/Readme.txt new file mode 100644 index 00000000000..9b759e09a44 --- /dev/null +++ b/vpp-api/java/jvpp/Readme.txt @@ -0,0 +1,201 @@ += 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 +==== |