summaryrefslogtreecommitdiffstats
path: root/vpp-api/java/Readme.txt
diff options
context:
space:
mode:
authorMarek Gradzki <mgradzki@cisco.com>2016-07-26 15:28:22 +0200
committerDave Wallace <dwallacelf@gmail.com>2016-08-16 21:26:19 +0000
commit66ea26b1bc7bbc8d54a3498dbd3d0919c4712fa8 (patch)
tree16c46e75723099ad859128af6069055e68897300 /vpp-api/java/Readme.txt
parentf4691cd7befd4cf31a63adffc204d71b1f1548e1 (diff)
VPP-205: jvpp plugin support.
Splits jvpp into two jars jvpp-registry.jar - base jvpp functionality jvpp-core.jar - Java wrapper for vpe.api Plugins can be generated the same way jvpp-core.jar is. Example (nsh): https://gerrit.fd.io/r/#/c/2118/ Change-Id: I2254f90b2c3e423563bb91bf70877979f1e90a7d Signed-off-by: Marek Gradzki <mgradzki@cisco.com>
Diffstat (limited to 'vpp-api/java/Readme.txt')
-rw-r--r--vpp-api/java/Readme.txt206
1 files changed, 206 insertions, 0 deletions
diff --git a/vpp-api/java/Readme.txt b/vpp-api/java/Readme.txt
new file mode 100644
index 00000000000..be540b0c7b4
--- /dev/null
+++ b/vpp-api/java/Readme.txt
@@ -0,0 +1,206 @@
+= JVpp
+
+JVpp is JNI based Java API for VPP.
+
+== Features
+It is:
+
+* Asynchronous
+* Fully generated
+* Lightweight
+
+== Architecture
+
+FIXME: update the file after plugin support is merged
+Current architecture is documented on the wiki page:
+https://wiki.fd.io/view/VPP/Java_API/Plugin_support
+
+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
+====