4.2.1 Getting, Installing, and Setting Up MySQL NDB Cluster Connector for Java

This section discusses how to obtain ClusterJ sources and binaries, and how to compile, install, and get started with ClusterJ.

Obtaining and Installing MySQL NDB Cluster Connector for Java.  You can obtain the most recent NDB Cluster release, which includes ClusterJ, from downloads.mysql.com. The installation instructions given in NDB Cluster Installation also install ClusterJ.

Building and installing MySQL NDB Cluster Connector for Java from source.  You can build and install ClusterJ as part of building and installing NDB Cluster, which always requires you to configure the build using the CMake option WITH_NDBCLUSTER_STORAGE_ENGINE (or its alias WITH_NDBCLUSTER).

A typical CMake command for configuring a build for NDB Cluster that supports ClusterJ might look like this:

cmake .. -DWITH_NDBCLUSTER=ON

The WITH_NDB_JAVA option is enabled by default, which means ClusterJ is be built together with NDB Cluster by the above command. However, if CMake cannot find the location of Java on your system, the configuration process is going to fail; use the WITH_CLASSPATH option to provide the Java classpath if needed. For information about other CMake options that can be used, see option_cmake_with_ndbcluster.

After configuring the build with CMake, run make and make install as you normally would to compile and install the NDB Cluster software.

MySQL NDB Cluster Connector for Java jar files.  Following the installation, these ClusterJ jar files can be found in the folder share/java under the MySQL installation directory (which is /usr/local/mysql by default for Linux platforms):

• clusterj-api-version.jar: This is the compile-time jar file, required for compiling ClusterJ application code.

• clusterj-version.jar: This is the runtime library required for executing ClusterJ applications.

• clusterj-test-version.jar: This is the ClusterJ test suite, required for testing your ClusterJ installation.

Building ClusterJ with Maven

The source files for ClusterJ are configured as Maven projects, allowing easy compilation and installation using Maven. Assuming you have obtained the NDB Cluster source and already compiled and installed NDB Cluster and ClusterJ following the instructions given above, these are the steps to take:

1. Add the file path for the folder that contains the NDB client library (libndbclient.so) as a property named ndbclient.lib to your local Maven settings.xml file (found in the local Maven repository, which is usually /home/username/.m2 for Linux platforms). The client library is to be found under the lib folder in the NDB Cluster's installation folder. If settings.xml does not exist in your local Maven repository, create one. This is how a simple settings.xml file containing the ndbclient.lib property looks like:

   <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                         http://maven.apache.org/xsd/settings-1.0.0.xsd">
     <profiles>
       <profile>
         <id>jni-library</id>
         <activation>
           <activeByDefault>true</activeByDefault>
         </activation> 
         <properties>
           <ndbclient.lib>/NDB_Cluster_installation_directory/lib/</ndbclient.lib>
         </properties>
       </profile>
     </profiles>
   
   </settings>

2. Go to the build directory you created when compiling NDB Cluster (which is bld in the sample steps in Build the Distribution), and then to the storage/ndb/clusterj folder under it. Run the mvn_install_ndbjtie.sh script in the folder:

   ./mvn_install_ndbjtie.sh

   It installs ndbjtie.jar, which provides the JNI layer for ClusterJ and is required for building CluterJ.

3. Install ClusterJ with Maven by running mvn install in the storage/ndb/clusterj directory:

   mvn install

   This causes ClusterJ to be built, with the resulting .jar files installed in the local Maven repository.

   Note

   You can skip the tests that takes place towards the end of the installation process by adding the option skipTests to the command:

   mvn install -DskipTests

   This prevents your installation from failing because you have not yet set up the testing environment.

Building ClusterJ with Maven in IDEs

Because the source files for ClusterJ are configured as Maven projects, you can easily import them into your favorite Maven-enabled IDEs, customize them, and rebuild them as needed by following these steps:

1. Make sure that your IDE's support for Maven is enabled. You might need to install a Maven plugin for the purpose.

2. Follow step 1 and 2 in Building ClusterJ with Maven, which make the ClusterJ source ready to be used with Maven.

3. Import ClusterJ as a Maven project. This is how to do it in some popular IDEs :

   In NetBeans:

   • In the main menu, choose File > Open Project. The Open Project dialogue box appears

   • In the Open Project dialogue box, browse to the storage/ndb folder under the build directory (see step 2 in Building ClusterJ with Maven); select the clusterj folder, which has the Maven icon () beside it, and click Open Project. The ClusterJ Aggregate project is imported, with ClusterJ API, ClusterJ Core, ClusterJ Test Suite, ClusterJ Tie, and ClusterJ Unit Test Framework imported as subprojects under Modules.

   • Work with the ClusterJ projects like you would with any other Maven projects in NetBeans. Any changes to the source code go into the source tree from which you compiled NDB Cluster to create the build directory.

   In Eclipse:

   • In the main menu, choose File > Import. The Import dialogue box appears

   • In the Import dialogue box, select Maven > Existing Maven Projects for import wizard and click Next. The Import Maven Projects dialogue box appears.

   • In the Import Maven Projects dialogue box, browse to the storage/ndb folder under the build directory (see step 2 in Building ClusterJ with Maven); select the clusterj folder and click Select Folder. The clusterj-aggregate project, as well as its subprojects clusterj-api, clusterj-core, clusterj-test, clusterj-tie and clusterj-unit, appear in the Maven Projects dialogue box. Click Select All and then Finish. All the ClusterJ projects are imported.

   • Work with the ClusterJ projects like you would with any other Maven projects in Eclipse.