Documentation Home
MySQL Cluster API Developer Guide
Download this Manual
PDF (US Ltr) - 5.2Mb
PDF (A4) - 5.2Mb
EPUB - 2.2Mb
HTML Download (TGZ) - 2.1Mb
HTML Download (Zip) - 2.2Mb


MySQL Cluster API Developer Guide  /  ...  /  Executing ClusterJ Applications and Sessions

4.2.2.1 Executing ClusterJ Applications and Sessions

In this section, we discuss how to start ClusterJ applications and the ClusterJ application environment as of MySQL Cluster NDB 7.1.2.

These requirements were somewhat different for MySQL Cluster NDB 7.1.1, as the implementation had not yet completely stabilized in that version. See Building and executing ClusterJ applications in MySQL Cluster NDB 7.1.1, at the end of this section, for more information.

Executing a ClusterJ application.  All of the ClusterJ jar files are normally found in share/mysql/java/ in the MySQL installation directory. When executing a ClusterJ application, you must set the classpath to point to these files. In addition, you must set java.library.path variable to point to the directory containing the Cluster ndbclient library, normally found in lib/mysql (also in the MySQL installation directory). Thus you might execute a ClusterJ program MyClusterJApp in a manner similar to what is shown here:

shell> java -classpath /usr/local/mysql/share/mysql/java/clusterj.jar \
              -Djava.library.path=/usr/local/mysql/lib MyClusterJApp
Note

The precise locations of the ClusterJ jar files and of libndbclient depend on how the MySQL Cluster software was installed. See Installation Layouts, for more information.

ClusterJ encourages you to use different jar files at compile time and runtime. This is to remove the ability of applications to access implementation artifacts accidentally. ClusterJ is intended to be independent of the MySQL Cluster software version, whereas the ndbclient layer is version-specific. This makes it possible to maintain a stable API, so that applications written against it using a given MySQL Cluster version continue to run following an upgrade of the cluster to a new version.

Building and executing ClusterJ applications in MySQL Cluster NDB 7.1.1.  As in later versions, only clusterj-api.jar is required in your classpath to compile a ClusterJ application. However, in order to run ClusterJ applications in MySQL Cluster NDB 7.1.1, several jar files are needed: clusterj-core.jar, clusterj-tie.jar, jtie.jar, and ndbjtie.jar; in addition, libndbjtie must be in your java.library.path.

Beginning with MySQL Cluster NDB 7.1.2, the runtime jar files just named have been combined as clusterj.jar, and libndbjtie has been made part of libndbclient.

Getting the SessionFactory and getting a Session.  SessionFactory is the source of all ClusterJ sessions that use a given MySQL Cluster. Usually, there is only a single SessionFactory per MySQL Cluster, per Java Virtual Machine.

SessionFactory can be configured by setting one or more properties. The preferred way to do this is by putting these in a properties file, like this:

com.mysql.clusterj.connectstring=localhost:1186
com.mysql.clusterj.database=mydb

The name of the properties file is arbitrary; howver, by convention, such files are named with a .properties extension. For ClusterJ applications, it is customary to name the file clusterj.properties.

After editing and saving the file, you can load the its contents into an instance of Properties, as shown here:

    
File propsFile = new File("clusterj.properties");
InputStream inStream = new FileInputStream(propsFile);
Properties props = new Properties();
props.load(inStream);

It is also possible to set these properties directly, without the use of a properties file:

Properties props = new Properties();

props.put("com.mysql.clusterj.connectstring", "localhost:1186");
props.put("com.mysql.clusterj.database", "mydb");

Once the properties have been set and loaded (using either of the techniques just shown), you can obtain a SessionFactory, and then from that a Session instance. For this, you use the SessionFactory's getSession() method, as shown here:

SessionFactory factory = ClusterJHelper.getSessionFactory(props);

Session session = factory.getSession();

It is usually sufficient to set and load the com.mysql.clusterj.connectstring and com.mysql.clusterj.database properties (and these properties, along with com.mysql.clusterj.max.transactions, cannot be changed after starting the SessionFactory). For a complete list of available SessionFactory properties and usual values, see com.mysql.clusterj.Constants.

Note

Session instances must not be shared among threads. Each thread in your application should use its own instance of Session.

For com.mysql.clusterj.connectstring, we use the default MySQL Cluster connection string localhost:1186 (see MySQL Cluster Connection Strings, for more information). For the value of com.mysql.clusterj.database, we use mydb in this example, but this value can be the name of any database containing NDB tables. For a listing of all SessionFactory properties that can be set in this manner, see com.mysql.clusterj.Constants.

Reconnecting to a MySQL Cluster.  ClusterJ does not attempt to reconnect to a MySQL Cluster once the connection is lost (error 4009) due to, for example, a network outage or the cluster going down. This, together with other errors, should be handled by the application with a common error handler. The handler needs to be able to detect and distinguish among three types of errors, and handle them accordingly:

  • Normal errors: These are errors at the application level (for example, those to deal with duplicate key, foreign key constraint, or timeout). They should be handled in application-specific ways, and, if resolved, the application can continue with the transaction.

  • Unexpected errors: These are failures to work with the cluster that cannot be accounted for by the conditions of the application, but are nonfatal. The application should close the ClusterJ session and reopen a new one.

  • Fatal errors: These are fatal errors like, for example, error 4009, Cluster Failure, which indicates a network outage or the cluster going down. The application should close the session and notify the rest of the application to shut down and then restart the SessionFactory.

    The restarting of the SessionFactory can be an automatic application function or a manual intervention. In either case, the code should wait until all sessions have been closed (that is, the public method getConnectionPoolSessionCounts() in the SessionFactory interface returns zeros for all pooled connections). Then the SessionFactory can be closed and reopened, and applications can start to get sessions again.

Logging.  ClusterJ uses Java logging. Here are some default settings for the ClusterJ logging, which are specified in the logging.properties file and can be modified there:

  • Logging level is set at INFO for all classes.

  • Using java.util.logging.FileHandler as the handler.

  • Default level for java.util.logging.FileHandler is set at FINEST

  • Using java.util.logging.SimpleFormatter as the formatter for the handler.

  • Log files are put inside the target directory under the current working directory, and file names are, generally, in the pattern of logNum, where Num is a unique number for resolving file name conflicts (see the Java documentation for java.util.logging.FileHandler for details).

The logging.properties file is located by default in the current working directory, but the location can be changed by specifying the system property java.util.logging.config.file when you start Java.


User Comments
Sign Up Login You must be logged in to post a comment.