MySQL NDB Cluster API Developer Guide
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 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
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,
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 NDB
Cluster version continue to run following an upgrade of the
cluster to a new version.
Getting the SessionFactory and getting a Session.
SessionFactory
is the source of all ClusterJ sessions that use a given NDB
Cluster. Usually, there is only a single
SessionFactory
per NDB 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; however, 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 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.
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 NDB Cluster connection string
localhost:1186
(see
NDB 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.
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, 7.6.3, and for later releases in the 7.5 and 7.6 series) has been enabled:
Automatic reconnection is enabled
: The feature is enabled when the
connection property
com.mysql.clusterj.connection.reconnect.timeout
has 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 State
of the
SessionFactory
from OPEN
to
RECONNECTING
; the
SessionFactory
then 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 State
of
the
SessionFactory
becomes OPEN
again, and the
application can now obtain sessions.
The SessionFactory.getState()
method returns the State
of the
SessionFactory
,
which is one of OPEN
,
RECONNECTING
, or
CLOSED
. Trying to obtain a
session when the State
is not
OPEN
results 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
com.mysql.clusterj.connection.reconnect.timeout
,
the
SessionFactory
closes 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.timeout
has 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
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 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 timeout
argument
of the reconnect()
method as the time
limit for having all open sessions closed.
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
log
,
where Num
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.