diff options
Diffstat (limited to 'extras/japi/java/Readme.txt')
| -rw-r--r-- | extras/japi/java/Readme.txt | 236 |
1 files changed, 0 insertions, 236 deletions
diff --git a/extras/japi/java/Readme.txt b/extras/japi/java/Readme.txt deleted file mode 100644 index 689b9b37a46..00000000000 --- a/extras/japi/java/Readme.txt +++ /dev/null @@ -1,236 +0,0 @@ -= 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 -==== |