Provides classes and interfaces for using MySQL Cluster directly from Java.
This package contains three main groups of classes and interfaces:
- A class for bootstrapping
- Interfaces for use in application programs
- Classes to define exceptions
Major Interfaces
ClusterJ provides these major interfaces for use by application programs:
{@link com.mysql.clusterj.SessionFactory},
{@link com.mysql.clusterj.Session},
{@link com.mysql.clusterj.Transaction},
{@link com.mysql.clusterj.query.QueryBuilder},
and
{@link com.mysql.clusterj.Query}.
Bootstrapping
The helper class {@link com.mysql.clusterj.ClusterJHelper} contains methods
for creating the {@link com.mysql.clusterj.SessionFactory}.
Bootstrapping is the process of identifying a MySQL Cluster and
obtaining the SessionFactory for use with the cluster. There is one
SessionFactory per cluster per Java VM.
SessionFactory
The {@link com.mysql.clusterj.SessionFactory} is configured via properties, which identify the
MySQL Cluster that the application connects to:
- com.mysql.clusterj.connectstring identifies the ndb_mgmd host name and port
- com.mysql.clusterj.connect.retries is the number of retries when connecting
- com.mysql.clusterj.connect.delay is the delay in seconds between connection retries
- com.mysql.clusterj.connect.verbose tells whether to display a message
to System.out while connecting
- com.mysql.clusterj.connect.timeout.before is the number of seconds to wait
until the first node responds to a connect request
- com.mysql.clusterj.connect.timeout.after is the number of seconds to wait
until the last node responds to a connect request
- com.mysql.clusterj.connect.database is the name of the database to use
File propsFile = new File("clusterj.properties");
InputStream inStream = new FileInputStream(propsFile);
Properties props = new Properties();
props.load(inStream);
SessionFactory sessionFactory = ClusterJHelper.getSessionFactory(props);
Session
The {@link com.mysql.clusterj.Session} represents the user's individual connection to
the cluster. It contains methods for:
- finding persistent instances by primary key
- persistent instance factory (newInstance)
- persistent instance life cycle management (persist, remove)
- getting the QueryBuilder
- getting the Transaction (currentTransaction)
Session session = sessionFactory.getSession();
Employee existing = session.find(Employee.class, 1);
if (existing != null) {
session.remove(existing);
}
Employee newemp = session.newInstance(Employee.class);
newemp.initialize(2, "Craig", 15, 146000.00);
session.persist(newemp);
Transaction
The {@link com.mysql.clusterj.Transaction} allows users to combine multiple operations
into a single database transaction. It contains methods to:
- begin a unit of work
- commit changes from a unit of work
- roll back all changes made since the unit of work was begun
- mark a unit of work for rollback only
- get the rollback status of the current unit of work
Transaction tx = session.currentTransaction();
tx.begin();
Employee existing = session.find(Employee.class, 1);
Employee newemp = session.newInstance(Employee.class);
newemp.initialize(2, "Craig", 146000.00);
session.persist(newemp);
tx.commit();
QueryBuilder
The {@link com.mysql.clusterj.query.QueryBuilder} allows users to build queries.
It contains methods to:
- define the Domain Object Model to query
- compare properties with parameters using:
- equal
- lessThan
- greaterThan
- lessEqual
- greaterEqual
- between
- in
- combine comparisons using "and", "or", and "not" operators
QueryBuilder builder = session.getQueryBuilder();
QueryDomainType<Employee> qemp = builder.createQueryDefinition(Employee.class);
Predicate service = qemp.get("yearsOfService").greaterThan(qemp.param("service"));
Predicate salary = qemp.get("salary").lessEqual(qemp.param("salaryCap"));
qemp.where(service.and(salary));
Query<Employee> query = session.createQuery(qemp);
query.setParameter("service", 10);
query.setParameter("salaryCap", 180000.00);
List<Employee> results = query.getResultList();