README

jni/README.md

@@ -1,92 +1,38 @@
-# jni
+# jni (experimental module)
 
-A new Flutter FFI plugin project.
+This is a utility library to access JNI from Dart / Flutter code, intended as a supplement for `jnigen` code generator, as well as provide the common base components (such as managing the JVM instance) to the code generated by `jni_gen`.
 
-## Getting Started
+This library contains:
 
-This project is a starting point for a Flutter 
-[FFI plugin](https://docs.flutter.dev/development/platform-integration/c-interop),
-a specialized package that includes native code directly invoked with Dart FFI.
+* functions to access the JNIEnv and JavaVM variables from JNI, and wrapper functions to those provided by JNI. (`Jni.getEnv`, `Jni.getJavaVM`).
 
-## Project stucture
+* Functions to spawn a JVM on desktop platforms. (`Jni.spawn`)
 
-This template uses the following structure:
+* Some utility functions to make it easier to work with JNI in Dart; eg: To convert a java string object to Dart string. (mostly as extension methods on `Pointer<JniEnv>`)
 
-* `src`: Contains the native source code, and a CmakeFile.txt file for building
-  that source code into a dynamic library.
+* Some Android-specific helpers. (get application context and current activity references).
 
-* `lib`: Contains the Dart code that defines the API of the plugin, and which
-  calls into the native code using `dart:ffi`.
+* Some helper classes and functions to simplify one-off uses. (`JniObject` and `JniClass` intended for calling functions by just specifying the name and arguments. It will reduce some boilerplate when you're debugging. That said, this API is slightly incomplete.)
 
-* platform folders (`android`, `ios`, `windows`, etc.): Contains the build files
-  for building and bundling the native code library with the platform application.
+This is intended for one-off / debugging uses of JNI, as well as providing a base library for code generated by jni_gen. 
 
-## Buidling and bundling native code
+__If you're looking to interface a complete java library, look forward for `jni_gen`.__
 
-The `pubspec.yaml` specifies FFI plugins as follows:
+## Platform support
+The focus of this project is Android, since it already has a JVM and JNI allows interop with existing code and Platform APIs. Experimental desktop support exists for Linux using the JVM invocation API.
 
-```yaml
-  plugin:
-    platforms:
-      some_platform:
-        ffiPlugin: true
-```
+## Version note
+This library is at an early stage and the public API may rapidly change based on requirements of `jni_gen`.
 
-This configuration invokes the native build for the various target platforms
-and bundles the binaries in Flutter applications using these FFI plugins.
+## Documentation
 
-This can be combined with dartPluginClass, such as when FFI is used for the
-implementation of one platform in a federated plugin:
+There are well-commented test files under `test/` directory and a flutter based example under `example/`.
 
-```yaml
-  plugin:
-    implements: some_other_plugin
-    platforms:
-      some_platform:
-        dartPluginClass: SomeClass
-        ffiPlugin: true
-```
+Using this library assumes some familiarity with JNI - it's threading model and object references, among other things.
 
-A plugin can have both FFI and method channels:
+## jni_gen
 
-```yaml
-  plugin:
-    platforms:
-      some_platform:
-        pluginClass: SomeName
-        ffiPlugin: true
-```
+This library is a part of `jni_gen` - a 2022 GSoC project.
 
-The native build systems that are invoked by FFI (and method channel) plugins are:
-
-* For Android: Gradle, which invokes the Android NDK for native builds.
-  * See the documentation in android/build.gradle.
-* For iOS and MacOS: Xcode, via CocoaPods.
-  * See the documentation in ios/jni.podspec.
-  * See the documentation in macos/jni.podspec.
-* For Linux and Windows: CMake.
-  * See the documentation in linux/CMakeLists.txt.
-  * See the documentation in windows/CMakeLists.txt.
-
-## Binding to native code
-
-To use the native code, bindings in Dart are needed.
-To avoid writing these by hand, they are generated from the header file
-(`src/jni.h`) by `package:ffigen`.
-Regenerate the bindings by running `flutter pub run ffigen --config ffigen.yaml`.
-
-## Invoking native code
-
-Very short-running native functions can be directly invoked from any isolate.
-For example, see `sum` in `lib/jni.dart`.
-
-Longer-running functions should be invoked on a helper isolate to avoid
-dropping frames in Flutter applications.
-For example, see `sumAsync` in `lib/jni.dart`.
-
-## Flutter help
-
-For help getting started with Flutter, view our
-[online documentation](https://flutter.dev/docs), which offers tutorials,
-samples, guidance on mobile development, and a full API reference.
+The broader aim of jni_gen is making Java APIs accessible from dart in an idiomatic way. The current focus is on the Android platform.