TransactionSynchronizationRegistry (Java EE 5)

在标准的应用服务器环境中，可以通过 JNDI 使用标准名称查询实现此接口的实例。标准名称是 java:comp/TransactionSynchronizationRegistry。

This interface is intended for use by system level application server components such as persistence managers, resource adapters, as well as EJB and Web application components. This provides the ability to register synchronization objects with special ordering semantics, associate resource objects with the current transaction, get the transaction context of the current transaction, get current transaction status, and mark the current transaction for rollback. This interface is implemented by the application server by a stateless service object. The same object can be used by any number of components with thread safety.

In standard application server environments, an instance implementing this interface can be looked up by a standard name via JNDI. The standard name is java:comp/TransactionSynchronizationRegistry.

Since:

JTA 1.1

public Object getTransactionKey()
返回一个不透明对象，以表示调用此方法时邦定到当前线程的事务。此对象重写 hashCode 和 equals，以允许将其作为 hashMap 中的键供调用者使用。如果当前没有活动的事务，则返回 null。

此对象将返回相同的 hashCode，并且对于相同应用服务器的相同事务上下文中执行的任何组件，调用此方法所返回所有其他对象都与此对象相等。

toString 方法返回一个 String，这将有助于人类读者更好地理解事务上下文。toString 结果的其他方面都没有定义。尤其不保证 toString 的结果具有向前或向后兼容性。

对象不必是可序列化的，而且没有定义获取对象的虚拟机外部的任何行为。

return	一个不透明对象，它表示调用此方法时当前线程的事务邦定。
since	JTA 1.1

英文文档：

getTransactionKey

Object getTransactionKey()

Return an opaque object to represent the transaction bound to the current thread at the time this method is called. This object overrides hashCode and equals to allow its use as the key in a hashMap for use by the caller. If there is no transaction currently active, return null.

This object will return the same hashCode and compare equal to all other objects returned by calling this method from any component executing in the same transaction context in the same application server.

The toString method returns a String that might be usable by a human reader to usefully understand the transaction context. The toString result is otherwise not defined. Specifically, there is no forward or backward compatibility guarantee of the results of toString.

The object is not necessarily serializable, and has no defined behavior outside the virtual machine whence it was obtained.

Returns:

an opaque object representing the transaction bound to the current thread at the time this method is called.

Since:

JTA 1.1

public void putResource(Object key, Object value)
添加或替换资源 Map 中的一个对象，调用此方法时正为绑定到当前线程的事务管理着这些资源。提供的键应该是一个调用者定义的类，以避免与其他用户冲突。键的类必须保证 hashCode 和 equals 方法可以用作映射中的键。实现不会检查或使用键和值。此方法的常规协定为，支持非 null 键和 null 值的 Map 的 put(Object, Object)。例如，如果已有一个与键关联的值，那么它会被 value 参数取代。

key	Map 条目的键。
value	Map 条目的值。
Throws	IllegalStateException: 如果没有任何事务处于活动状态。
Throws	NullPointerException: 如果参数 key 为 null。
since	JTA 1.1

英文文档：

putResource

void putResource(Object key,
                 Object value)

Add or replace an object in the Map of resources being managed for the transaction bound to the current thread at the time this method is called. The supplied key should be of an caller- defined class so as not to conflict with other users. The class of the key must guarantee that the hashCode and equals methods are suitable for use as keys in a map. The key and value are not examined or used by the implementation. The general contract of this method is that of Map.put(Object, Object) for a Map that supports non-null keys and null values. For example, if there is already an value associated with the key, it is replaced by the value parameter.

Parameters:

key - the key for the Map entry.

value - the value for the Map entry.

Throws:

IllegalStateException - if no transaction is active.

NullPointerException - if the parameter key is null.

Since:

JTA 1.1

public Object getResource(Object key)
从资源 Map 中获取一个对象，调用此方法时正为邦定到当前线程的事务管理着这些资源。应该通过在同一个事务中调用 putResouce 提前提供键。如果不能在当前资源 Map 中找到键，则返回 null。此方法的常规协定为，支持非 null 键和 null 值的 Map 的 get(Object)。例如，如果没有参数键条目或者与键关联的值实际上为 null，则返回值为 null。

key	Map 条目的键。
return	与该键关联的值。
Throws	IllegalStateException: 如果没有任何事务处于活动状态。
Throws	NullPointerException: 如果参数 key 为 null。
since	JTA 1.1

英文文档：

getResource

Object getResource(Object key)

Get an object from the Map of resources being managed for the transaction bound to the current thread at the time this method is called. The key should have been supplied earlier by a call to putResouce in the same transaction. If the key cannot be found in the current resource Map, null is returned. The general contract of this method is that of Map.get(Object) for a Map that supports non-null keys and null values. For example, the returned value is null if there is no entry for the parameter key or if the value associated with the key is actually null.

Parameters:

key - the key for the Map entry.

Returns:

the value associated with the key.

Throws:

IllegalStateException - if no transaction is active.

NullPointerException - if the parameter key is null.

Since:

JTA 1.1

public void registerInterposedSynchronization(Synchronization sync)
注册一个具有特殊排序语义的 Synchronization 实例。其 beforeCompletion 将在所有 SessionSynchronization beforeCompletion 回调和直接向 Transaction 注册的回调之后，但在启动二阶段提交过程之前调用。同样，afterCompletion 回调将在二阶段提交完成之后，但在任何 SessionSynchronization 和 Transaction afterCompletion 回调之前调用。

beforeCompletion 回调将在调用此方法时当前线程事务邦定的事务上下文中调用。允许的方法包括访问资源，例如 Connector。不允许访问“用户组件”（例如，计时器服务或 Bean 方法），因为这可能更改调用者管理的数据状态，也可能更改已经由 registerInterposedSynchronization 的另一个调用者刷新的数据状态。常规上下文是 registerInterposedSynchronization 调用者的组件上下文。

将调用 afterCompletion 回调的上下文中是不确定的。正如上面所定义的，不允许访问“用户组件”。可以关闭资源，但是不能对其执行任何事务性操作。

如果调用此方法时没有活动的事务上下文，则抛出 IllegalStateException。

如果在启动二阶段提交过程之后调用此方法，则抛出 IllegalStateException。

sync	Synchronization 实例。
Throws	IllegalStateException: 如果没有任何事务处于活动状态。
since	JTA 1.1

英文文档：

registerInterposedSynchronization

void registerInterposedSynchronization(Synchronization sync)

Register a Synchronization instance with special ordering semantics. Its beforeCompletion will be called after all SessionSynchronization beforeCompletion callbacks and callbacks registered directly with the Transaction, but before the 2-phase commit process starts. Similarly, the afterCompletion callback will be called after 2-phase commit completes but before any SessionSynchronization and Transaction afterCompletion callbacks.

The beforeCompletion callback will be invoked in the transaction context of the transaction bound to the current thread at the time this method is called. Allowable methods include access to resources, e.g. Connectors. No access is allowed to "user components" (e.g. timer services or bean methods), as these might change the state of data being managed by the caller, and might change the state of data that has already been flushed by another caller of registerInterposedSynchronization. The general context is the component context of the caller of registerInterposedSynchronization.

The afterCompletion callback will be invoked in an undefined context. No access is permitted to "user components" as defined above. Resources can be closed but no transactional work can be performed with them.

If this method is invoked without an active transaction context, an IllegalStateException is thrown.

If this method is invoked after the two-phase commit processing has started, an IllegalStateException is thrown.

Parameters:

sync - the Synchronization instance.

Throws:

IllegalStateException - if no transaction is active.

Since:

JTA 1.1

public int getTransactionStatus()
返回调用此方法时当前线程事务邦定的状态。这是在调用此方法时当前线程事务邦定的上下文中执行 TransactionManager.getStatus() 的结果。

return	调用此方法时当前线程事务邦定的状态。
since	JTA 1.1

英文文档：

getTransactionStatus

int getTransactionStatus()

Return the status of the transaction bound to the current thread at the time this method is called. This is the result of executing TransactionManager.getStatus() in the context of the transaction bound to the current thread at the time this method is called.

Returns:

the status of the transaction bound to the current thread at the time this method is called.

Since:

JTA 1.1

public void setRollbackOnly()
设置调用此方法时当前线程事务邦定的 rollbackOnly 状态。

Throws	IllegalStateException: 如果没有任何事务处于活动状态。
since	JTA 1.1

英文文档：

setRollbackOnly

void setRollbackOnly()

Set the rollbackOnly status of the transaction bound to the current thread at the time this method is called.

Throws:

IllegalStateException - if no transaction is active.

Since:

JTA 1.1

public boolean getRollbackOnly()
获取调用此方法时当前线程事务邦定的 rollbackOnly 状态。

return	rollbackOnly 状态
Throws	IllegalStateException: 如果没有任何事务处于活动状态。
since	JTA 1.1

英文文档：

getRollbackOnly

boolean getRollbackOnly()

Get the rollbackOnly status of the transaction bound to the current thread at the time this method is called.

Returns:

the rollbackOnly status.

Throws:

IllegalStateException - if no transaction is active.

Since:

JTA 1.1

Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.