feat(jni): add a jni readme

Author: dorotaphanSiili

README.md

@@ -38,3 +38,4 @@ The template offers the following feature switches which can be enabled during c
 * `plugin`: create a fully functional plugin with including the stub implementations and tests
 * `monitor`: create a thin decorator class which can be used to log traffic going through API layer
 * `olink`: create the adaption layer for the [OLink](https://docs.apigear.io/docs/advanced/protocols/objectlink/intro) protocol. This can be used to connect to the simulation.
+* `jni`: create the jni adaption layer for the android messenger communication provided by apigear java template. Please read more on a separate document readme_jni.

readme_jni.md

@@ -0,0 +1,102 @@
+# Unreal Jni Adapter
+
+The feature "jni" provides the jni adaption layer for the android messenger communication, which for each interface must be generated with ApiGear java template.
+The android build requires the modules provided with the java template. They are compiled within an unreal application with its build system. <br/> 
+Make also sure that your unreal app has proper settings selected to make it available to run on android devices (like allowing large obb files or some android permissions enabled). 
+
+## Code generation
+
+Java template provides features:
+**api, stub, android, jnibridge** - which a required for the unreal jni feature to work. <br>
+You can also take a look at the **testclientapp** and **testserviceapp** features which generates a simple example of client or service android app. Those apps only serve first defined interface, and require user to fill partially code for buttons - you need to provide the arguments values. You may use those apps as a starting point to test your unreal side app.
+
+The code generated by java template starting form the top-level folder for the module should be placed in your modules Jni plugin under android folder.
+For example for the module named `"HelloWorld"` the generated folder `helloworld` the path should be:
+```
+YourProject/Plugins/HelloWorld/Source/HelloWorldJni/android
+```
+You can achieve this by configuring your `*.solution.yaml` file e.g. like that
+
+```
+schema: "apigear.solution/1.0"
+name: helloworld
+version: "0.1.0"
+
+layers:
+  - name: unreal
+    inputs:
+      - myhelloworld.module.yaml
+    output: ../relative-path-to/YourProject
+    template: apigear-io/template-unreal //TODO MINIMAL VERSION
+    features: ["api","jni","stubs"]
+  - name: java
+    inputs:
+      - myhelloworld.module.yaml
+    output: ../relative-path-to/YourProject/Plugins/HelloWorld/Source/HelloWorldJni/android
+    template: apigear-io/template-java
+    features: ["api","android","stubs","jnibridge"]
+```
+Remember that re-generation may overwrite all your manual changes to generated files.
+
+### Versions
+Currently minimum supported sdk version for android is 33. <br>
+Currently tested UE version is 5.5.
+
+## How to use
+
+Generated code provides:
+* Jni Service Adapter
+* Jni Client
+
+Have in mind the most probably you'll need only one side in your app. The generated objects are a *game subssystems*  and they are always started. Moreover the android service starts during the Service Adapter initialization. It will not collide with your client trying to connect other implementation of the service as you need to specify package from which you'd like to use the service, but still may be not wanted overhead in your app.
+
+### Jni Service Adapter
+
+The Jni Service Adapter treats exposes your Local Implementation of the api (requires setting a backend) as an android service. It is generated per interface described in your `*.module.yaml` <br>
+When the Jni Service Adapter is initialized it creates an android service, with a jni backend implemented by that Jni Service Adapter.
+Notice that there will be as many `andorid services` as the interfaces declared in the `*.module.yaml` file. When it comes to threads - no extra thread is spawned for each service, they are all in the applications thread. <br>
+All the services are already exposed in the unreal app `AndroidManifest.xml`. 
+
+### Jni Client
+Jni Client adapter is generated per interface. It uses the same interfaces as other ApiGear generated versions (OlinkClient, MessageBusClient or the local implementation).<br>
+It is recommended to use it through that interface, which allows you to easy change of the "data input" and test your application first on your desktop e.g. using OLink simulation.<br>
+To make your client work you need to bind to a **running service**. <br>
+The client does not start any service while trying to bind. The re-connection is not automated neither when service died nor when it wasn't started at all.<br>
+The binding may be performed from the blueprints. It requires the package name of the app that provides (and starts) the requested android service and a unique connection Id (among the this service).<br>
+The client unbinds automatically on deinitialization.
+All the necessary queries and permissions are configured in the unreal app` AndroidManifest.xml`.
+
+## Application permissions
+
+Here is a suggested configuration of the unreal project for automotive.
+You can use settings in unreal editor or you can change your DefaultEngine.ini file.
+
+/***
+
+[/Script/AndroidRuntimeSettings.AndroidRuntimeSettings]
+PackageName=your.pacakge.[PROJECT]
+...
+MinSDKVersion=33
+TargetSDKVersion=33
+...
+bDisableVerifyOBBOnStartUp=False
+bForceSmallOBBFiles=False
+bAllowLargeOBBFiles=True
+...
+ExtraApplicationNodeTags=android:requestLegacyExternalStorage="true"
+ExtraPermissions=android.permission.READ_MEDIA_IMAGES
+ExtraPermissions=android.permission.WRITE_EXTERNAL_STORAGE
+ExtraPermissions=android.permission.READ_MEDIA_VIDEO
+ExtraPermissions=android.permission.READ_MEDIA_AUDIO
+ExtraPermissions=android.permission.READ_EXTERNAL_STORAGE
+ExtraPermissions=android.permission.MANAGE_EXTERNAL_STORAGE
+
+***/
+
+Remember to fill the `PackageName` field with `your.pacakge.[PROJECT]` especially when providing the service side. `your.package` is the package name that all the client should provide on binding to bind this service.
+
+The minimum target version should not be lower than the one that is required for java template.
+
+The OBB settings allow the unreal app to start on android device. By default android does not allow large OBB files, but unreal apps usually have them large.
+
+Unreal app also requires some extra permissions.