com.atlassian.jira.database

Interface QueryDslAccessor

All Known Implementing Classes:

DefaultQueryDslAccessor, MockQueryDslAccessor

public interface QueryDslAccessor

Provides access to database connections from the Database Connection Pool with QueryDsl support built in.

Since:

7.0.6

Method Summary

Modifier and Type	Method and Description
void	execute(SqlCallback callback) Executes SQL statements as defined in the callback function.
<T> T	executeQuery(QueryCallback<T> callback) Executes SQL statements as defined in the callback function and returns the results.
ConnectionProvider	withNewConnection() Get a connection provider that will always borrow a new DB connection from the connection pool.

Method Detail

executeQuery

<T> T executeQuery(@Nonnull
                   QueryCallback<T> callback)

Executes SQL statements as defined in the callback function and returns the results.

This method is mostly useful for running SELECT statements and returning the given results in some form.

This method will attempt to run the callback within an existing OfBiz transaction if one is running within this thread. If not, it will borrow a new connection, start a transaction and manage that transaction for you. That is, the connection will always be in autocommit=false, and the commit or rollback will be completely managed for you. If you want to rollback the transaction then throw a RuntimeException. The transaction will be marked as "rollback required" such that the code that started the transaction will eventually call rollback on the Connection and the exception will be propagated. If the callback returns normally, then this indicates that the underlying transaction is allowed to be committed at the appropriate time.

Because the connection (borrowing and returning from the pool) and its transaction are managed for you, then specific Connection methods are illegal to call and will cause a RuntimeException including:

• Connection.setAutoCommit(boolean) autocommit is always false
• Connection.commit()
commit will occur in the broader transaction context if no errors are encountered
• Connection.rollback()
rollback will occur if a RuntimeException is thrown from the callback function
• Connection.close()
the connection will be returned to the pool for you at the appropriate time

Example Usage:

    WorklogDTO worklogDTO = queryDslAccessor.executeQuery(
            dbConnection -> dbConnection.newSqlQuery()
                    .from(WORKLOG)
                    .where(WORKLOG.id.eq(worklog.getId()))
                    .singleResult(WORKLOG));
 

Type Parameters:

T - type of results

Parameters:

callback - the callback function that runs the query

Returns:

results of the callback function

Since:

7.0.6

See Also:

execute(SqlCallback), withNewConnection()

execute

void execute(@Nonnull
             SqlCallback callback)

Executes SQL statements as defined in the callback function.

This method does not return results and is mostly useful for running INSERT, UPDATE, and DELETE operations.

This method will attempt to run the callback within an existing OfBiz transaction if one is running within this thread. If not, it will borrow a new connection, start a transaction and manage that transaction for you. That is, the connection will always be in autocommit=false, and the commit or rollback will be completely managed for you. If you want to rollback the transaction then throw a RuntimeException. The transaction will be marked as "rollback required" such that the code that started the transaction will eventually call rollback on the Connection and the exception will be propagated. If the callback returns normally, then this indicates that the underlying transaction is allowed to be committed at the appropriate time.

Because the connection (borrowing and returning from the pool) and its transaction are managed for you, then specific Connection methods are illegal to call and will cause a RuntimeException including:

• Connection.setAutoCommit(boolean) autocommit is always false
• Connection.commit()
commit will occur in the broader transaction context if no errors are encountered
• Connection.rollback()
rollback will occur if a RuntimeException is thrown from the callback function
• Connection.close()
the connection will be returned to the pool for you at the appropriate time

Example Usage:

     queryDslAccessor.execute(dbConnection -> {
             dbConnection.update(QIssueLink.ISSUE_LINK)
                     .set(QIssueLink.ISSUE_LINK.sequence, newSeq)
                     .where(QIssueLink.ISSUE_LINK.id.eq(issueLinkId))
                     .execute();
     });
 

Parameters:

callback - the callback function that runs the query

Since:

7.0.6

See Also:

executeQuery(QueryCallback), withNewConnection()

withNewConnection

ConnectionProvider withNewConnection()

Get a connection provider that will always borrow a new DB connection from the connection pool.

Important: This method will borrow a new connection from the pool, pass it to the callback function and then return it to the pool after the callback has completed. Even if OfBiz is currently running in a ThreadLocal transaction, this will retrieve a fresh connection from the pool. If you want to run in an existing OfBiz transaction then see instead executeQuery(QueryCallback) or execute(SqlCallback)

The connection will have the default auto-commit value as defined by the JIRA connection pool. As at JIRA 7.0 this means autocommit == true. (See org.apache.commons.dbcp.PoolableConnectionFactory#activateObject(Object) for details.)

• You can set autocommit(false) and then commit() to use a transaction.
• To cause a rollback you can either call rollback() explicitly, or throw a RuntimeException.

Note that this is very different to the behaviour of the default methods in this accessor where the transaction is completely managed for you.

Example Usage:

     queryDslAccessor.withNewConnection().execute(dbConnection -> {
             dbConnection.update(QIssueLink.ISSUE_LINK)
                     .set(QIssueLink.ISSUE_LINK.sequence, newSeq)
                     .where(QIssueLink.ISSUE_LINK.id.eq(issueLinkId))
                     .execute();
     });
 

Returns:

a provider that allows you to run QueryDsl queries against a freshly borrowed DB connection.

Since:

7.0.6

See Also:

executeQuery(QueryCallback), execute(SqlCallback)