EJBs with container-managed transactions

The latest version of Java EE greatly simplifies EJBs while still providing all the same (if not more) benefits, like container-managed transactions. Let's consider this stateless EJB that stores a file inside a repository. To keep things simple (and focused on the transactions), we'll use a utility called JcrTools that ModeShape includes in its public API with a method to upload the content in the supplied InputStream into a nt:file node (with its "jcr:content" child node), creating any missing ancestor nt:folder nodes along the way:

@Stateless
public class ContentProvider {
    protected Session getSession() throws RepositoryException, NamingException {
        InitialContext context = new InitialContext();
        Repository repository = (Repository)context.lookup("jcr/my_repository");
        return repository.login(); // uses default workspace and JAAS
    }

    public void uploadFile( String path, InputStream stream ) throws RepositoryException, NamingException, IOException {
        Session session = getSession();
        try {
            // Use a ModeShape utility ...
            new JcrTools().uploadFile(session,path,stream);
            session.save();
        } finally {
            session.logout();
        }
    }
}

This EJB can then be called by any other component in the web application (including JSPs). And notice that we don't include any transaction-related code, yet this is what happens when the uploadFile method is called:

1. If a transaction doesn't exist, one will be started

2. The uploadFile(...) method is executed

   1. A new Session is created using the current JAAS credentials (line 10)

   2. nt:folder and nt:file nodes dictated by the path are created as needed, a Binary value is created with the content from the InputStream and set as the "jcr:data" property on the "jcr:content" child of the nt:file node (line 13)

   3. The changes made to the session are saved (line 14)

   4. The session is closed (line 16)

3. The transaction (started before the uploadFile method is executed or at an earlier point) is committed (or rolled back if an exception is thrown)

Now the somewhat tricky part. The transient changes made on line 13 are not persisted when the Session is saved (on line 14); rather, the changes are written to the repository, made visible to other sessions, and events are produced only when/if the transaction is committed. This would be true if we'd made several sets of transient changes interspersed with multiple Session.save() calls.

EJBs with bean-managed transactions

Using JCR within EJBs that manage the transactions themselves (i.e., bean-managed transactions) works the same way, except that the bean must explicitly control the transaction boundaries via the UserTransaction interface. Prior to EE6, obtaining the UserTransaction instance was not (as) standardized, though often looking it upon JNDI was the most common approach. However, with EE6, the UserTransaction can simply be injected into the bean:

@Stateless
@TransactionManagement(BEAN)
public class ContentProvider {

    @Resource
    UserTransaction ut;

    protected Session getSession() throws RepositoryException, NamingException {
        InitialContext context = new InitialContext();
        Repository repository = (Repository)context.lookup("jcr/my_repository");
        return repository.login(); // uses default workspace and JAAS
    }

    public void uploadFile( String path, InputStream stream ) throws RepositoryException, NamingException, IOException {
        Session session = getSession();
        try {
            ut.begin();

            // Use a ModeShape utility ...
            new JcrTools().uploadFile(session,path,stream);
            session.save();

            // Commit the transaction ...
            ut.commit();
        } catch ( RepositoryException e ) {
            ut.rollback();
            throw e;
        } catch ( ... ) {
            // Handle the various (and many) JTA-related transactions, rolling back as appropriate
        } finally {
            session.logout();
        }
    }
}

Explicit JTA transactions

If your application is running in an environment that supports JTA, then your application can control the boundaries of the transactions. Here's an example that uploads a file into the repository, creating also missing nodes or updating the existing nodes (the same thing as the EJB example above):

javax.jta.TransactionManager txnMgr = ...
javax.jcr.Repository repository = ...

// Start the transaction ...
txnMgr.begin();
try {
    // Obtain a session, using default workspace and credentials (which may be JAAS)
    Session session = repository.login();
    try {
        // Use a ModeShape utility ...
        new JcrTools().uploadFile(session,path,stream);
        session.save();

        // Commit the transaction ...
        txnMgr.commit();
    } finally {
        session.logout();
    }
} catch ( ... ) {
    // Handle RepositoryException and the various (and many) JTA-related transactions, rolling back as appropriate
}

In this example, we had to code all the transaction-related logic, which is quite extensive and can be tricky to get right while properly handling all the JTA-related and repository exceptions. But once again, the transient changes made on line 11 and saved on line 12 will not actually be persisted in the repository until the transaction is committed (line 15).

We could just as easily created our session outside the transaction, too:

javax.jta.TransactionManager txnMgr = ...
javax.jcr.Repository repository = ...
Session session = repository.login();

// Start the transaction ...
txnMgr.begin();
try {
    // Use a ModeShape utility ...
    new JcrTools().uploadFile(session,path,stream);
    session.save();

    // Commit the transaction ...
    txnMgr.commit();
} catch ( ... ) {
    // Handle RepositoryException and the various (and many) JTA-related transactions, rolling back as appropriate
} finally {
    session.logout();
}

We could have also used UserTransaction, but the details of how to obtain the UserTransaction instance varies by environment (particularly outside non-JEE6 environments).