Java Bindings
=============

The Java content in ``examples/language_bindings/java`` is a reference
integration over the CosmicSDK C API. It demonstrates one way to integrate
from Java, but it is not an official Java SDK package.

Example Layout
--------------

The Java examples mirror the native C/C++ blocking examples:

.. code-block:: text

   examples/language_bindings/java/
   |- src/main/java/com/binho/cosmicsdk/
   |- src/main/java/com/binho/cosmicsdk/examples/system/
   |- src/main/java/com/binho/cosmicsdk/examples/i2c/
   |- src/main/java/com/binho/cosmicsdk/examples/spi/
   |- src/main/java/com/binho/cosmicsdk/examples/uart/
   |- src/main/java/com/binho/cosmicsdk/examples/gpio/
   |- src/main/java/com/binho/cosmicsdk/examples/i3c/basic/
   |- src/main/java/com/binho/cosmicsdk/examples/i3c/daa/
   |- src/main/java/com/binho/cosmicsdk/examples/i3c/ccc/
   |- src/main/java/com/binho/cosmicsdk/examples/i3c/hdrddr/
   |- src/main/java/com/binho/cosmicsdk/examples/i3c/hjibi/
   |- pom.xml

Windows
-------

1. **Navigate to the Java binding directory**

.. code-block:: powershell

   cd /path/to/CosmicSDK/examples/language_bindings/java

2. **Set `COSMICSDK_LIB_PATH`**

Point it either to the directory containing the shared library, or to the
full path of the library itself.

- Command Prompt

.. code-block:: bat

   set COSMICSDK_LIB_PATH=<path-to-CosmicSDK-library-or-lib-folder>

- PowerShell

.. code-block:: powershell

   $env:COSMICSDK_LIB_PATH="<path-to-CosmicSDK-library-or-lib-folder>"

3. **Build the Java bindings**

.. code-block:: powershell

   mvn compile

4. **Run one example**

.. code-block:: powershell

   mvn -q exec:java -Dexec.mainClass=com.binho.cosmicsdk.examples.system.SystemExample
   mvn -q exec:java -Dexec.mainClass=com.binho.cosmicsdk.examples.i2c.I2cExample
   mvn -q exec:java -Dexec.mainClass=com.binho.cosmicsdk.examples.i3c.basic.I3cBasicExample

macOS
-----

1. **Navigate to the Java binding directory**

.. code-block:: bash

   cd /path/to/CosmicSDK/examples/language_bindings/java

2. **Set `COSMICSDK_LIB_PATH` and run one example**

.. code-block:: bash

   export COSMICSDK_LIB_PATH=/path/to/cosmicsdk/lib
   mvn compile
   mvn -q exec:java -Dexec.mainClass=com.binho.cosmicsdk.examples.i2c.I2cExample

If loading fails because of missing transitive ``.dylib`` dependencies, set:

.. code-block:: bash

   export DYLD_LIBRARY_PATH=$COSMICSDK_LIB_PATH:$DYLD_LIBRARY_PATH

Linux
-----

1. **Navigate to the Java binding directory**

.. code-block:: bash

   cd /path/to/CosmicSDK/examples/language_bindings/java

2. **Set `COSMICSDK_LIB_PATH` and `LD_LIBRARY_PATH`, then run one example**

.. code-block:: bash

   export COSMICSDK_LIB_PATH=/path/to/cosmicsdk/lib
   export LD_LIBRARY_PATH=$COSMICSDK_LIB_PATH:$LD_LIBRARY_PATH
   mvn compile
   mvn -q exec:java -Dexec.mainClass=com.binho.cosmicsdk.examples.i2c.I2cExample

Notes
-----

- This Java wrapper uses JNA to bind directly to the CosmicSDK shared library.
- On Linux, ``LD_LIBRARY_PATH`` may be required so the runtime can resolve
  transitive native dependencies (for example ``libhidapi-libusb.so.0``).
- On macOS, if dependency resolution fails, use ``DYLD_LIBRARY_PATH``.
- Notification-driven examples (for example ``i3c/hjibi``, ``uart`` and
  ``gpio``) register Java callbacks through the C notification API.
- This code is maintained as integration reference material and should be
  treated as a starting point for custom Java solutions.