com.mysql.clusterj

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();