# Transaction Events

### Transactional Events

BoxLang emits events during the lifecycle of a JDBC transaction which can be used to react to various transaction points in your app:

* [`onTransactionBegin`](#ontransactionbegin)
* [`onTransactionEnd`](#ontransactionend)
* [`onTransactionCommit`](#ontransactioncommit)
* [`onTransactionRollback`](#ontransactionrollback)
* [`onTransactionSetSavepoint`](#ontransactionsetsavepoint)
* [`onTransactionAcquire`](#ontransactionacquire)\*
* [`onTransactionRelease`](#ontransactionrelease)\*

Note that all these events (with the exception of `onTransactionAcquire` and `onTransactionRelease`) have the potential to be acting upon a no-op transaction, with a null `connection` parameter since no connection was ever obtained. ( Read more in [Transaction Behavior](/boxlang-framework/jdbc/transactions.md#transaction-behavior) for a description of how transactions work. )

With this in mind, you'll want to do null checks against the `connection` parameter in case no connection has yet been acquired:

```js
function onTransactionSetSavepoint( struct data ){
    if( data.keyExists( "connection" ) && data.connection != null ){
        // we can be sure this transaction is "doing work".
    }
}
```

The two exceptions, as mentioned above, are `onTransactionAcquire` and `onTransactionRelease`, which *only* emit once a connection has been acquired, and is being released, respectively. Most of the time you'll want to listen for these events instead of their `onTransactionBegin`/`onTransactionEnd` counterparts.

### onTransactionBegin

This event fires when the transaction block is first opened and before the body begins processing.

Note that in BoxLang transactions, *no connection is acquired until the first JDBC query is executed*. This means that the `onTransactionBegin` will not have any connection to operate on. Most of the time, you will want to use [`onTransactionAcquire`](#ontransactionacquire) in place of `onTransactionBegin`.

| Data Key    | Type       | Description                        |
| ----------- | ---------- | ---------------------------------- |
| transaction | Java class | Instance of the Transaction object |

#### Example

```js
function onTransactionBegin( struct data ){}
```

### onTransactionEnd

This event fires when the transaction block is closed after the body has finished processing.

Consider using [`onTransactionRelease`](#ontransactionrelease) as an alternative to `onTransactionEnd` if you only want to listen for transactions that have done work.

| Data Key    | Type       | Description                                                                                                                                            |
| ----------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| transaction | Java class | Instance of the Transaction object                                                                                                                     |
| connection  | Java class | Instance of the java.sql.Connection object this transaction is operating upon. May be `null` if no JDBC queries have executed inside this transaction. |

#### Example

```js
function onTransactionEnd( struct data ){}
```

### onTransactionAcquire

This event fires when the transaction first acquires a connection due to a JDBC query being executed within the body. You should prefer this over `onTransactionBegin`.

| Data Key    | Type       | Description                                                                   |
| ----------- | ---------- | ----------------------------------------------------------------------------- |
| transaction | Java class | Instance of the Transaction object                                            |
| connection  | Java class | Instance of the java.sql.Connection object this transaction is operating upon |

#### Example

```js
function onTransactionAcquire( struct data ){}
```

### onTransactionRelease

This event fires when the transaction releases its connection. You should prefer this over `onTransactionEnd`.

| Data Key    | Type       | Description                                                                   |
| ----------- | ---------- | ----------------------------------------------------------------------------- |
| transaction | Java class | Instance of the Transaction object                                            |
| connection  | Java class | Instance of the java.sql.Connection object this transaction is operating upon |

#### Example

```js
function onTransactionRelease( struct data ){}
```

### onTransactionCommit

This event fires when a transaction commit action occurs. Can occur multiple times (or never) within a single transaction.

| Data Key    | Type       | Description                                                                   |
| ----------- | ---------- | ----------------------------------------------------------------------------- |
| transaction | Java class | Instance of the Transaction object                                            |
| connection  | Java class | Instance of the java.sql.Connection object this transaction is operating upon |

#### Example

```js
function onTransactionCommit( struct data ){}
```

### onTransactionRollback

This event fires when a transaction rollback action occurs. Can occur multiple times (or never) within a single transaction.

| Data Key    | Type       | Description                                                                   |
| ----------- | ---------- | ----------------------------------------------------------------------------- |
| transaction | Java class | Instance of the Transaction object                                            |
| connection  | Java class | Instance of the java.sql.Connection object this transaction is operating upon |
| savepoint   | String     | Savepoint name to roll back to. May be `null`.                                |

#### Example

```js
function onTransactionRollback( struct data ){}
```

### onTransactionSetSavepoint

This event fires when a transaction savepoint is set.

| Data Key    | Type       | Description                                                                   |
| ----------- | ---------- | ----------------------------------------------------------------------------- |
| transaction | Java class | Instance of the Transaction object                                            |
| connection  | Java class | Instance of the java.sql.Connection object this transaction is operating upon |
| savepoint   | String     | Savepoint name to set.                                                        |

#### Example

```js
function onTransactionSetSavepoint( struct data ){}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://boxlang.ortusbooks.com/boxlang-framework/interceptors/core-interception-points/transaction-events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.