# informat.transaction 数据库事务操作

## 概述

使用`informat.transaction`执行事务相关的操作

## defaultTransactionDefinition

创建默认事务定义

```javascript
informat.transaction.defaultTransactionDefinition()
```

***返回值***
默认事务定义，类型为[TransactionDefinition](/guide/script/transaction.md#transactiondefinition)

***

## currentTransactionStatus

获取当前事务状态

```js
informat.transaction.currentTransactionStatus()
```

***返回值***

当前事务状态,类型为[TransactionStatus](/guide/script/transaction.md#transactionstatus)

***

## getTransactionStatus

根据给定的事务定义（TransactionDefinition）获取一个事务，并返回其运行时状态

```js
informat.transaction.getTransactionStatus(td)
```

| 参数 | 类型                                                                          | 描述   |
|----|-----------------------------------------------------------------------------|------|
| td | [TransactionDefinition](/guide/script/transaction.md#transactiondefinition) | 事务定义 |

***返回值***

事务传播方式,类型为[TransactionStatus](/guide/script/transaction.md#transactionstatus)

## commit

提交事务

```js
informat.transaction.commit(ts)
```

| 参数 | 类型                | 描述   |
|----|-------------------|------|
| ts | TransactionStatus | 事务状态 |

## rollback

回滚事务

```js
informat.transaction.rollback(ts)
```

| 参数 | 类型                | 描述   |
|----|-------------------|------|
| ts | TransactionStatus | 事务状态 |

## TransactionDefinition

### setPropagationBehavior

设置事务传播方式

```js
td.setPropagationBehavior(pb)
```

| 参数 | 类型      | 描述     |
|----|---------|--------|
| pb | Integer | 事务传播方式 |

事务传播方式如下:

| 传播方式                      | 值 | 描述                                             |
|---------------------------|---|------------------------------------------------|
| PROPAGATION_REQUIRED      | 0 | 如果当前没有事务，就新建一个事务；如果已经存在一个事务，就加入到这个事务中。默认的传播行为。 |
| PROPAGATION_SUPPORTS      | 1 | 如果当前存在事务，则加入到该事务中；如果没有事务，则以非事务方式执行。            |
| PROPAGATION_MANDATORY     | 2 | 如果当前存在事务，则加入到该事务中；如果没有事务，则抛出异常。                |
| PROPAGATION_REQUIRES_NEW  | 3 | 无论当前是否存在事务，都新建一个事务。当前事务（如果存在）会被挂起，新事务执行完毕后恢复。  |
| PROPAGATION_NOT_SUPPORTED | 4 | 以非事务方式执行。如果当前存在事务，则将事务挂起，执行完毕后恢复事务。            |
| PROPAGATION_NEVER         | 5 | 以非事务方式执行。如果当前存在事务，则抛出异常。                       |
| PROPAGATION_NESTED        | 6 | 如果当前存在事务，则在嵌套事务中执行；如果没有事务，则新建一个事务。嵌套事务可独立回滚，   |

***

### setPropagationBehaviorName

设置事务传播方式

```js
td.setPropagationBehaviorName(pbName)
```

示例：

```
td.setPropagationBehaviorName('PROPAGATION_REQUIRED')
```

### getPropagationBehavior

获取事务传播方式

```js
td.getPropagationBehavior()
```

***返回值***

事务传播方式,类型为`Integer`



***

### setIsolationLevel

设置事务隔离级别

```js
td.setIsolationLevel(isolationLevel)
```

| 参数             | 类型      | 描述   |
|----------------|---------|------|
| isolationLevel | Integer | 隔离级别 |

隔离级别定义如下：

| 隔离级别                       | 值  | 描述                       |
|----------------------------|----|--------------------------|
| ISOLATION_DEFAULT          | -1 | 默认隔离级别，使用底层数据源的默认隔离级别    |
| ISOLATION_READ_UNCOMMITTED | 0  | 读取未提交数据，允许脏读、不可重复读和幻读    |
| ISOLATION_READ_COMMITTED   | 1  | 读取已提交数据，防止脏读，但允许不可重复读和幻读 |
| ISOLATION_REPEATABLE_READ  | 2  | 可重复读，防止脏读和不可重复读，但允许幻读    |
| ISOLATION_SERIALIZABLE     | 3  | 串行化，防止脏读、不可重复读和幻读        |

### setIsolationLevelName

设置事务隔离级别

```js
td.setIsolationLevelName(isolationLevelName)
```

示例:

```js
td.setIsolationLevelName('ISOLATION_READ_UNCOMMITTED')
```

***

### getIsolationLevel

获取事务隔离级别

```js
td.getIsolationLevel()
```

***返回值***

事务隔离级别,类型为`Integer`

***

### setTimeout

设置事务超时时间

```js
td.setTimeout(seconds)
```

| 参数      | 类型      | 描述   |
|---------|---------|------|
| seconds | Integer | 超时秒数 |

示例：

```js
var td = informat.transaction.defaultTransactionDefinition()
td.setTimeout(30)
```

在这个示例中，我们创建了一个 默认TransactionDefinition 对象，并调用 setTimeout 方法将事务的超时时间设置为 30 秒。这意味着如果事务在 30
秒内没有完成，事务管理器将中止事务并执行回滚操作。

***

### getTimeout

获取事务超时时间,单位：秒

```js
td.getTimeout()
```

***返回值***
事务超时时间,类型为`Integer`

***

### setReadOnly

设置事务是否只读

```js
td.setReadOnly(readOnly)
```

| 参数       | 类型      | 描述   |
|----------|---------|------|
| readOnly | Boolean | 是否只读 |

只读事务通常用于查询操作，因为它们不需要修改数据。将事务设置为只读可能对性能有所帮助，因为某些数据库可能会针对只读事务进行优化。


***

### isReadOnly

返回事务是否只读

```js
td.isReadOnly()
```

***返回值***
事务是否只读,类型为`Boolean`

***

### setName

设置事务名称

```js
td.setName(name)
```

| 参数   | 类型     | 描述 |
|------|--------|----|
| name | String | 名称 |

事务名称可以帮助开发人员在日志和监控工具中轻松识别和跟踪事务。

### getName

获取事务名称

```js
td.getName()
```

***返回值***
事务名称,类型为`String`

## TransactionStatus

### isNewTransaction

判断是否为新事务

```js
ts.isNewTransaction()
```

***返回值***
是否为新事务,类型为`Boolean`

### isRollbackOnly

判断事务是否仅限于回滚

```js
ts.isRollbackOnly()
```

***返回值***
事务是否仅限于回滚,类型为`Boolean`

### isCompleted

判断事务是否已完成

```js
ts.isCompleted()
```

***返回值***
事务是否已完成,类型为`Boolean`

### setRollbackOnly

设置事务仅限于回滚

```js
ts.setRollbackOnly()
```

**一个完整的例子**

```js
var ts = informat.transaction.currentTransactionStatus();//获取当前事务状态
informat.transaction.commit(ts);//提交当前事务
//
var td = informat.transaction.defaultTransactionDefinition();//创建默认事务定义
td.setPropagationBehaviorName('PROPAGATION_REQUIRES_NEW');//修改事务传播方式为新事务
var ts = informat.transaction.getTransactionStatus(td);//获取事务状态
try {
    informat.table.insert('task', {
        'name': '来自脚本'
    });//插入一条数据表记录
    informat.transaction.commit(ts);//提交事务
} catch (e) {
    informat.transaction.rollback(ts);//如果异常事务回滚
}
```

:::tip
注意：在自动化中如果需要开启新事务，让之后的步骤可以开启事务执行，需要执行以下命令：

let td=informat.transaction.defaultTransactionDefinition();
td.setPropagationBehaviorName('PROPAGATION_REQUIRES_NEW');
let ts=informat.transaction.getTransactionStatus(td);

在代码片段中执行这三条命令后，之后的自动化步骤将是开启事务执行。
:::

## registerSynchronization

注册事务同步回调

```javascript
informat.transaction.registerSynchronization(ts)
```

| 参数   | 类型     | 描述 |
|------|--------|----|
| ts | TransactionSynchronization | 事务同步回调对象 |


***TransactionSynchronization***
事务同步回调对象包含以下可配置的监听函数：

### beforeCommit
类型: Function
触发时机：在事务提交前执行
参数: readOnly (Boolean) - 表示事务是否只读

### beforeCompletion
类型: Function
触发时机：在事务完成前执行（无论提交或回滚）

### afterCommit
类型: Function
触发时机：在事务成功提交后执行（仅提交时触发）

### afterCompletion
类型: Function
触发时机：在事务完成后执行（无论提交或回滚）
参数: status (Integer) - 完成状态（0=提交,1=回滚）

***示例***
```js
// 创建同步回调对象
var sync = {};
// 配置回调函数
sync.beforeCommit = function(readOnly) {
    console.log("事务即将提交，只读模式:", readOnly);
};

sync.beforeCompletion = function() {
    console.log("事务完成前处理");
};

sync.afterCommit = function() {
    console.log("事务已成功提交");
};

sync.afterCompletion = function(status) {
    console.log("事务完成状态:", status === 0 ? "提交" : "回滚");
};

// 注册回调
informat.transaction.registerSynchronization(sync);
```
