In this section, we discuss how to start ClusterJ applications and the ClusterJ application environment.
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
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:
$> java -classpath /usr/local/mysql/share/mysql/java/clusterj.jar \ -Djava.library.path=/usr/local/mysql/lib MyClusterJApp
The precise locations of the ClusterJ jar files and of
libndbclient depend on how the NDB 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 NDB Cluster software version,
ndbclient layer is
version-specific. This makes it possible to maintain a stable
API, so that applications written against it using a given NDB
Cluster version continue to run following an upgrade of the
cluster to a new version.
Getting the SessionFactory and getting a Session.
is the source of all ClusterJ sessions that use a given NDB
Cluster. Usually, there is only a single
per NDB Cluster, per Java Virtual Machine.
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:
The name of the properties file is arbitrary; however, by
convention, such files are named with a
.properties extension. For ClusterJ
applications, it is customary to name the file
After editing and saving the file, you can load its contents
into an instance of
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
and then from that a
instance. For this, you use the
method, as shown here:
SessionFactory factory = ClusterJHelper.getSessionFactory(props); Session session = factory.getSession();
It is usually sufficient to set and load the
properties (and these properties, along with
cannot be changed after starting the
For a complete list of available
properties and usual values, see
instances must not be shared among threads. Each thread in
your application should use its own instance of
we use the default NDB Cluster connection string
NDB Cluster Connection Strings, for more
information). For the value of
mydb in this example, but this value
can be the name of any database containing
NDB tables. For a listing of all
properties that can be set in this manner, see
Error Handling and Reconnection. Errors that occur while using ClusterJ 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.
Connectivity errors: These are errors like error 4009 and 4010, which indicate a network outage. There are two possible scenarios, depending on whether the automatic reconnection feature (available for NDB Cluster 7.5.7 and later) has been enabled:
Automatic reconnection is enabled : The feature is enabled when the connection property
com.mysql.clusterj.connection.reconnect.timeouthas been set to a positive number, which specifies a reconnection timeout in seconds.
When ClusterJ detects a disconnect with the NDB Cluster, it changes the
SessionFactorythen waits for the application to close all the sessions, and then attempts to reconnect the application to the NDB Cluster by closing all connections in the connection pool and recreating the pool using the original pool properties. After reestablishing all the connections, the
OPENagain, and the application can now obtain sessions.
SessionFactory.getState()method returns the
SessionFactory, which is one of
CLOSED. Trying to obtain a session when the
OPENresults in a
ClusterJUserException, with the message Session factory is not open.
If the application does not close all sessions by the end of the timeout period specified with
SessionFactorycloses any open sessions forcibly (which might result in loss of resources), and then attempts reconnection.
Automatic reconnection is not enabled: This is when the connection property
com.mysql.clusterj.connection.reconnect.timeouthas not been set, or it has been set to zero (this is also the case for older NDB Cluster releases that do not support the automatic reconnection feature).
ClusterJ does not attempt to reconnect to the NDB Cluster once the connection is lost. The application should close all sessions and then restart the
SessionFactory. The restarting of the
SessionFactorycan 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
SessionFactoryinterface returns zeros for all pooled connections). Then the
SessionFactorycan be closed and reopened, and the application can obtain sessions again.
Instead of enabling the feature and waiting for ClusterJ to detect a disconnection and attempt a reconnection, you can also have the application itself initiate the reconnection process upon the detection of a connection error by calling the
SessionFactory.reconnect(int timeout)method: that triggers the reconnection process described above, but uses the
timeoutargument of the
reconnect()method as the time limit for having all open sessions closed.
logging. Here are some default settings for the
ClusterJ logging, which are specified in the
logging.properties file and can be
Logging level is set at
INFOfor all classes.
java.util.logging.FileHandleras the handler.
Default level for
java.util.logging.FileHandleris set at
java.util.logging.SimpleFormatteras the formatter for the handler.
Log files are put inside the
targetdirectory under the current working directory, and file names are, generally, in the pattern of
Numis a unique number for resolving file name conflicts (see the Java documentation for
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