The Elastos Carrier Java SDK allows access to the Elastos Carrier Native API (written in C programming language) through Java Native Interface (JNI).
The Elastos Carrier Java SDK functionalities are dependent on the Elastos Carrier Native SDK. Major changes to the coding of the Carrier Native SDK most often result in the need to adjust the Carrier Java SDK.
Well tested, compatible versions of both the Carrier Native SDK and the Carrier Java SDK can be downloaded as Releases .
If any issues are found, please report it here . In case you also know how to correct the coding or documentation, please submit a Pull Request .
To see the current status of the Elastos Carrier Java SDK, please see our Project Roadmap.
To read more about the Elastos Carrier Java SDK, please see the Wiki .
Note: The Java SDK is a work in progress and is not intended for productive use.
- Elastos Carrier Java SDK
- Build from source on Ubuntu / Debian / Linux host
- Build from source on Windows host
- Current limitations
- Contribution
- Acknowledgments
- License
To explore the features of the Carrier and the Java SDK, please see the Elastos Messenger which is implemented using Java and JavaFX for the Graphical User Interface (GUI). See Screenshots.
An executable .jar file of the Messenger can be downloaded from the '/demo' folder which does not require any compilation. After testing, it is recommended to build your own from the source code provided.
Please note, building and running of the messenger demo application is currently only possible on a Ubuntu / Debian / Linux and Windows hosts. MacOS will be added in the near future.
To generate Makefiles by using configure or cmake and manage dependencies of the Carrier project, certain packages must be installed on the host before compilation.
Run the following commands to install the prerequisite utilities:
$ sudo apt-get update
$ sudo apt-get install -f default-jre openjdk-8-jdk openjfx maven build-essential autoconf automake autopoint libtool flex bison libncurses5-dev cmakeNote: In case Java is already installed, please check the version with the 'java -version' command, Java version 8 is recommended. Java 11 does not contain the JavaFX SDK and must be additionally installed.
Download the Elastos.NET.Carrier.Native.SDK (not Elastos.Carrier.Java.SDK) repository using Git:
$ git clone https://github.com/elastos/Elastos.NET.Carrier.Native.SDKTo compile the project from source code for the target to run on Ubuntu / Debian / Linux, carry out the following steps:
Open a new terminal window.
Navigate to the previously downloaded folder that contains the source code of the Carrier project.
$ cd YOUR-PATH/Elastos.NET.Carrier.Native.SDKEnter the 'build' folder.
$ cd buildCreate a new folder with the target platform name, then change directory.
$ mkdir linux
$ cd linuxGenerate the Makefile in the current directory:
Note: Please see custom options below.
$ cmake ../..Optional (Generate the Makefile): To be able to build a distribution with a specific build type Debug/Release, as well as with customized install location of distributions, run the following commands:
$ cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=YOUR-INSTALL-PATH ../..Build the program:
Note: If "make" fails due to missing permissions, use "sudo make" instead.
$ makeInstall the program:
Note: If "make install" fails due to missing permissions, use "sudo make install" instead.
$ make installCreate distribution package:
Note: If "make dist" fails due to missing permissions, use "sudo make dist" instead.
$ make dist
Extract and open the distribution package of the Carrier Native SDK (not the Java SDK) previously created in a visual file manager, and open the 'include' folder.
Copy the files ela_carrier.h and ela_session.h .
In the downloaded Carrier Java SDK, navigate to the 'c_jni_src/linux/include' folder and paste the ela_carrier.h and ela_session.h header files into the c_jni_src/linux/include folder.
Open the 'lib' folder of the distribution package of the Carrier Native SDK (not the Java SDK) and copy the files libcrystal.so, libelacarrier.so and libelasession.so .
In the downloaded Carrier Java SDK, open src/main/resources/lib/linux and paste the files libcrystal.so, libelacarrier.so and libelasession.so into the lib folder.
Open a new terminal window.
Note: To make sure all Java related packages are installed as described in the prerequisites section, run the following commands:
$ sudo apt-get update
$ sudo apt-get install default-jre openjdk-8-jdk openjfx maven
Please make sure you have source $JAVA_HOME set. You can check with the command 'echo $JAVA_HOME' in the terminal. If you configure JAVA_HOME now, please restart the computer (or virtual machine) to update the configuration.
Change directory to the Elastos.Carrier.Java.SDK/c_jni_src/linux folder where the CMakeLists.txt is present.
$ cd YOUR-PATH/Elastos.NET.Carrier.Java.SDK/c_jni_src/linux
Generate the required Makefile in the current directory:
$ sudo cmake .
Build the program:
$ sudo make
Package the project with Maven:
$ mvn clean package assembly:single
The output will be a .jar file (messenger.jar) which is placed in the folder '/target'.
Note: For easy access, it is recommended to move the previously generated messenger.jar file to a different location. Create a new folder and place the .jar file inside. When running the application, it will create two additional folders. The messenger.jar file must be started from the terminal.
Open a new terminal.
Execute the command where the messenger.jar file has been placed:
$ java -jar messenger.jar
The messenger application will start and a new address will be automatically created. The loading indicator will disappear when the node has successfully joined the network.
Note: Please do not close the terminal in the background when the messenger is running. It is technically possible to hide it, but currently it may be used for debugging.
With CMake, Elastos Carrier can be cross-compiled to run only on Windows as target platform, while compilation is carried out on a Windows host. Both 32-bit and 64-bit target versions are supported.
Prerequisites:
- Visual Studio IDE is required. The Community version can be downloaded at https://visualstudio.microsoft.com/downloads/ for free.
- Download and install "Visual Studio Command Prompt (devCmd)" from https://marketplace.visualstudio.com/items?itemName=ShemeerNS.VisualStudioCommandPromptdevCmd .
- Install 'Desktop development with C++' Workload
Note: In case Java is already installed, please check the version with the 'java -version' command, Java version 8 is recommended. Java 11 does not contain the JavaFX SDK and must be additionally installed. (https://www.oracle.com/technetwork/java/javafx2-archive-download-1939373.html).
Start the program 'Visual Studio Installer'.
Alternative: Start Visual Studio IDE. In the menu, go to "Tools >> Get Tools and Features", it will open the Visual Studio Installer.
Make sure 'Desktop development with C++' Workload is installed.
On the right side, make sure in the 'Installation details' all of the following are installed:
"Windows 8.1 SDK and UCRT SDK" <- might have to be selected additionally
"Windows 10 SDK (10.0.17134.0)" <- might have to be selected additionally
"VC++ 2017 version 15.9 ... tools"
"C++ Profiling tools"
"Visual C++ tools for CMake"
"Visual C++ ATL for x86 and x64"
Additional tools are optional, some additional ones are installed by default with the Workload.
After modifications, restarting of Visual Studio might be required.
To compile the project from source code for the target to run on Windows, carry out the following steps:
Open a new Windows Command Line. Note: The command line should be started as a Windows Desktop App, NOT from Visual Studio.
Navigate to the Visual Studio Build tools in command line:
Note: The path might be different with custom Visual Studio installation path.
$ cd C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build
Run:
$ vcvars64.bat
Carry out the following commands in the same command prompt window!
Navigate to the previously downloaded folder that contains the source code of the Carrier project.
$ cd YOUR-PATH/Elastos.NET.Carrier.Native.SDKEnter the 'build' folder.
$ cd buildCreate a new folder with the target platform name, then change directory.
$ mkdir win
$ cd winGenerate the Makefile in the current directory:
$ cmake -G "NMake Makefiles" -DCMAKE_INSTALL_PREFIX=outputs ..\..Build the program:
$ nmakeInstall the program:
$ nmake installCreate distribution package:
$ nmake dist
Close the command line.
Extract and open the distribution package of the Carrier Native SDK (not the Java SDK) previously created in a visual file manager, and open the 'include' folder.
Copy the files ela_carrier.h and ela_session.h .
In the downloaded Carrier Java SDK, navigate to the 'c_jni_src/windows/include' folder and paste the ela_carrier.h and ela_session.h header files into the c_jni_src/windows/include folder.
Open the '/bin' folder of the distribution package of the Carrier Native SDK (not the Java SDK) and copy the files crystal.dll, elacarrier.dll, elasession.dll and pthreadVC2.dll.
In the downloaded Carrier Java SDK, open src/main/resources/lib/windows and paste the files crystal.dll, elacarrier.dll, elasession.dll and pthreadVC2.dll into the lib folder.
Prerequisites
- Java JDK (https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html)
- Maven (https://maven.apache.org/download.cgi)
- CMake (https://cmake.org/download/)
- C compiler (https://mingw-w64.org/doku.php/start -> 'Downloads' -> 'Sources' section (Download hosted on SourceForge) )
Note: Please make sure you have source $JAVA_HOME set. You can check with the command 'echo %JAVA_HOME%' in the terminal. If you configure JAVA_HOME now, please restart the computer (or virtual machine) to update the configuration.
Open a new Windows Command Line. Note: The command line should be started as a Windows Desktop App, NOT from Visual Studio.
Change directory to the Elastos.Carrier.Java.SDK/c_jni_src/windows folder where the CMakeLists.txt is present.
$ cd YOUR-PATH/Elastos.NET.Carrier.Java.SDK/c_jni_src/windows
Generate the required Makefile in the current directory:
$ cmake -G "MinGW Makefiles" .
Build the program:
$ mingw32-make
Note: The mingw32-make command will build both the 32 bit and the 64 bit versions.
Move up two directories to the Elastos.NET.Carrier.Java.SDK folder.
$ cd ../..
Package the project with Maven:
$ mvn clean package assembly:single
The output will be a .jar file (messenger.jar) which is placed in the folder '/target'.
Note: For easy access, it is recommended to move the previously generated messenger.jar file to a different location. Create a new folder and place the .jar file inside. When running the application, it will create two additional folders. The messenger.jar file must be started from the terminal.
Open a new terminal.
Execute the command where the messenger.jar file has been placed:
$ java -jar messenger.jar
The messenger application will start and a new address will be automatically created. The loading indicator will disappear when the node has successfully joined the network.
Note: Please do not close the terminal in the background when the messenger is running. It is technically possible to hide it, but currently it may be used for debugging.
Not yet accepted incoming friend requests cannot be listed by command In case a friend request is sent by someone to our address while us being offline, the pending request cannot be listed by command to force an instant check. However, pending requests are updated by the network with some latency and are then displayed when us being online for a while. The Carrier Native library does not (yet) support this function.
Sent, but not yet accepted friend requests cannot be sorted as 'Pending' When an invitation is sent, the user is added to the list of friends instantly and their status is kept as 'offline' until they accept the request (and are online). The Carrier Native library does not (yet) support this function.
Messages are not stored offline When a conversation window is closed, the content of the conversation is not stored anywhere. The Carrier Native library does not (yet) support this function.
We welcome contributions to the Elastos Carrier Java SDK Project.
A sincere thank you to all teams and projects that we rely on directly or indirectly.
This project is licensed under the terms of the MIT license.