<commit_before># Syncbase cgo bridge

The Syncbase cgo bridge exposes a C API to Syncbase. It's intended to be used on
iOS (Swift) and Android (Java), and perhaps elsewhere as well.

For the time being, we provide a `Makefile` to build C archives for all target
platforms. Eventually, we'll integrate C archive compilation with the `jiri`
tool.<commit_msg>java: Update the cgo/README.md to talk about JNI<commit_after># Syncbase cgo bridge

The Syncbase cgo bridge exposes a C API to Syncbase. It's intended to be used on
iOS (Swift) and Android (Java), and perhaps elsewhere as well.

For the time being, we provide a `Makefile` to build C archives for all target
platforms. Eventually, we'll integrate C archive compilation with the `jiri`
tool.

# JNI

Java expects functions that have names and arguments that match the `native`
declarations from the `.java` files located in `java/io/v/syncbase/internal`.

Layout:

- `jni.go`: the JNI functions expected by Java.
- `jni_util.go`: helper functions to find Java classes and retrieve IDs for
   object fields and methods.
- `jni_lib.go`: types and functions to cache the field and method IDs for all
   the classes the code needs to touch.
- `jni_types.go`: methods and functions to convert between Java and the types
   declared in `lib.h`; counterpart of `types.go`.
- `jni_wrapper.{h,c}`: trampoline functions that compensate for the fact that Go
   cannot call a function pointer.

Some design notes:

- looking up classes/interfaces, methods and field IDs is expensive. The global
  variables named like `fooClass` from `jni.go` cache all we need for a class
  `foo`. The load is done in `JNI_OnLoad`, a function that is called each time
  the our library is loaded (typically, using `System.loadLibrary()`).
- some of the `extractToJava()` methods and `newVFoo()` functions are in
  `jni.go` instead of `jni_types.go` to avoid some
  _"inconsistent definitions"_ errors.
- the `extractToJava()` methods convert from low-level types like
  `v23_syncbase_Foo` to their Java equivalents. The `extract()` methods convert
  to Go equivalents. Both `extract()` and `extractToJava()` will free all the
  pointers inside the primitive types they are extracting from.
- the `free()` methods are idempotent.
- we use `panic()` to enforce certain invariants (enough memory, existence of
  classes, methods, fields, etc) and to keep the code simple.
{'fraction_non_alphanumeric': 0.07637729549248748, 'fraction_numerical': 0.0008347245409015025, 'mean_word_length': 4.326666666666667, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7472125', 'n_tokens_mistral': 706, 'n_tokens_neox': 663, 'n_words': 347}