This section discusses the ClusterJ API and the object model used to represent the data handled by the application.

Application Programming Interface.  The ClusterJ API depends on 4 main interfaces — Session, SessionFactory, Transaction, and QueryBuilder.

Session interface.  All access to MySQL Cluster data is done in the context of a session. The Session interface represents a user's or application's individual connection to a MySQL Cluster. It contains methods for the following operations:

SessionFactory interface.  Sessions are obtained from a SessionFactory, of which there is typically a single instance for each MySQL Cluster that you want to access from the Java VM. SessionFactory stores configuration information about the cluster, such as the hostname and port number of the MySQL Cluster management server. It also stores parameters regarding how to connect to the cluster, including connection delays and timeouts. For more information about SessionFactory and its use in a ClusterJ application, see Getting the SessionFactory and getting a Session.

Transaction interface.  Transactions are not managed by the Session interface; like other modern application frameworks, ClusterJ separates transaction management from other persistence methods. Transaction demarcation might be done automatically by a container or in a web server servlet filter. Removing transaction completion methods from Session facilitates this separation of concerns.

The Transaction interface supports the standard begin, commit, and rollback behaviors required by a transactional database. In addition, it allows the user to mark a transaction as being rollback-only, which makes it possible for a component that is not responsible for completing a transaction to indicate that — due to an application or database error — the transaction must not be allowed to complete normally.

QueryBuilder interface.  The QueryBuilder interface allows users to construct criteria queries dynamically, using domain object model properties as query modeling elements. Comparisons between parameters and database column values can be specified, including equal, greater and less than, between, and in operations. These comparisons can be combined using methods corresponding to the Boolean operators AND, OR, and NOT. Comparison of values to NULL is also supported.

Data model.  ClusterJ provides access to data in MySQL Cluster using domain objects, similar in many ways to the way that JPA models data.

In ClusterJ, the domain object mapping has the following characteristics:

The user view of the application environment and domain objects is illustrated in the following diagram, which shows the logical relationships among the modeling elements of the ClusterJ interfaces:

The SessionFactory is configured by a properties object that might have been loaded from a file or constructed dynamically by the application via some other means (see Section 4.2.2.1, “Executing ClusterJ Applications and Sessions”).

The application obtains Session instances from the SessionFactory, with at most one thread working with a Session at a time. A thread can manage multiple Session instances if there is some application requirement for multiple connections to the database.

Each session has its own collection of domain objects, each of which represents the data from one row in the database. The domain objects can represent data in any of the following states: