|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
javax.resource.spi Interface ManagedConnection
public interface ManagedConnection
ManagedConnection 实例表示与底层 EIS 的物理连接。
ManagedConnection 实例提供对两个接口的访问:javax.transaction.xa.XAResource
和 javax.resource.spi.LocalTransaction
。
事务管理器使用 XAResource
接口关联(取消关联)事务与底层 EIS 资源管理器实例,并执行两阶段提交协议。事务管理器不能直接使用 ManagedConnection 接口。有关 XAResource 接口的更多详细信息在 JTA 规范中描述。
应用服务器使用 LocalTransaction 接口管理本地事务。
version | 0.5 |
See also | javax.resource.spi.ManagedConnectionFactory, javax.transaction.xa.XAResource, javax.resource.spi.LocalTransaction |
ManagedConnection instance represents a physical connection to the underlying EIS.
A ManagedConnection instance provides access to a pair of
interfaces: javax.transaction.xa.XAResource
and
javax.resource.spi.LocalTransaction
.
XAResource
interface is used by the transaction
manager to associate and dissociate a transaction with the underlying
EIS resource manager instance and to perform two-phase commit
protocol. The ManagedConnection interface is not directly used
by the transaction manager. More details on the XAResource
interface are described in the JTA specification.
The LocalTransaction interface is used by the application server to manage local transactions.
- Version:
- 0.5
- Author:
- Rahul Sharma
- See Also:
ManagedConnectionFactory
,XAResource
,LocalTransaction
Method Summary | |
---|---|
void |
addConnectionEventListener(ConnectionEventListener listener)
Adds a connection event listener to the ManagedConnection instance. |
void |
associateConnection(Object connection)
Used by the container to change the association of an application-level connection handle with a ManagedConneciton instance. |
void |
cleanup()
Application server calls this method to force any cleanup on the ManagedConnection instance. |
void |
destroy()
Destroys the physical connection to the underlying resource manager. |
Object |
getConnection(Subject subject,
ConnectionRequestInfo cxRequestInfo)
Creates a new connection handle for the underlying physical connection represented by the ManagedConnection instance. |
LocalTransaction |
getLocalTransaction()
Returns an javax.resource.spi.LocalTransaction instance. |
PrintWriter |
getLogWriter()
Gets the log writer for this ManagedConnection instance. |
ManagedConnectionMetaData |
getMetaData()
Gets the metadata information for this connection's underlying EIS resource manager instance. |
XAResource |
getXAResource()
Returns an javax.transaction.xa.XAresource instance. |
void |
removeConnectionEventListener(ConnectionEventListener listener)
Removes an already registered connection event listener from the ManagedConnection instance. |
void |
setLogWriter(PrintWriter out)
Sets the log writer for this ManagedConnection instance. |
Method Detail |
---|
public Object
getConnection(javax.security.auth.Subject subject, ConnectionRequestInfo cxRequestInfo) throws ResourceException
为 ManagedConnection 实例表示的底层物理连接创建一个新的连接句柄。应用程序代码使用此连接句柄引用底层物理连接。采用特定于资源适配器实现的方法,将此连接句柄与其 ManagedConnection 实例关联。
ManagedConnection 使用 Subject 和其他 ConnectionRequest 信息(特定于资源适配器并且对应用服务器不透明)设置物理连接的状态。
subject | 作为 JAAS 主体的安全上下文 |
cxRequestInfo | ConnectionRequestInfo 实例 |
return | 表示连接句柄的一般 Object 实例。对于 CCI,ManagedConnection 实例创建的连接句柄的类型为 javax.resource.cci.Connection。 |
Throws | ResourceException: 如果操作失败,则抛出此一般异常 |
Throws | ResourceAdapterInternalException: 资源适配器内部错误情况 |
Throws | SecurityException: 与安全有关的错误情况 |
Throws | CommException: 与 EIS 实例的通信失败 |
Throws | EISSystemException: EIS 实例中的内部错误情况(在 EIS 实例涉及设置 ManagedConnection 的状态时使用) |
getConnection
Object getConnection(Subject subject, ConnectionRequestInfo cxRequestInfo) throws ResourceException
- Creates a new connection handle for the underlying physical connection represented by the ManagedConnection instance. This connection handle is used by the application code to refer to the underlying physical connection. This connection handle is associated with its ManagedConnection instance in a resource adapter implementation specific way.
The ManagedConnection uses the Subject and additional ConnectionRequest Info (which is specific to resource adapter and opaque to application server) to set the state of the physical connection.
- Parameters:
subject
- security context as JAAS subjectcxRequestInfo
- ConnectionRequestInfo instance- Returns:
- generic Object instance representing the connection handle. For CCI, the connection handle created by a ManagedConnection instance is of the type javax.resource.cci.Connection.
- Throws:
ResourceException
- generic exception if operation failsResourceAdapterInternalException
- resource adapter internal error conditionSecurityException
- security related error conditionCommException
- failed communication with EIS instanceEISSystemException
- internal error condition in EIS instance - used if EIS instance is involved in setting state of ManagedConnection
public void
destroy() throws ResourceException
销毁与底层资源管理器的物理连接。
为了管理连接池的大小,应用服务器可以显式调用 ManagedConnection.destroy 销毁物理连接。当调用 destroy 方法时,资源适配器应该销毁为此 ManagedConnection 实例分配的所有系统资源。
Throws | ResourceException: 如果操作失败,则抛出此一般异常 |
Throws | IllegalStateException: 销毁连接时处于非法状态 |
destroy
void destroy() throws ResourceException
- Destroys the physical connection to the underlying resource manager.
To manage the size of the connection pool, an application server can explictly call ManagedConnection.destroy to destroy a physical connection. A resource adapter should destroy all allocated system resources for this ManagedConnection instance when the method destroy is called.
- Throws:
ResourceException
- generic exception if operation failedIllegalStateException
- illegal state for destroying connection
public void
cleanup() throws ResourceException
应用服务器调用此方法强制在 ManagedConnection 实例上执行清除。
方法 ManagedConnection.cleanup 启动 ManagedConnection 实例维护的任何特定于客户端的状态的清除。清除应该使使用此 ManagedConnection 实例创建的所有连接句柄无效。清除底层 ManagedConnection 之后,应用程序组件使用连接句柄的任何尝试都将导致异常。
清除 ManagedConnection 总是由应用服务器驱动。还存在正在进行的未完成事务(与 ManagedConnection 实例关联)时,应用服务器不应该调用 ManagedConnection.cleanup。
对已经清除的连接调用 ManagedConnection.cleanup 方法不应该抛出异常。
清除 ManagedConnection 实例将重置其特定于客户端的状态,并准备好将连接放回到连接池中。cleanup 方法不应该使资源适配器关闭物理管道并回收与物理连接关联的系统资源。
Throws | ResourceException: 如果操作失败,则抛出此一般异常 |
Throws | ResourceAdapterInternalException: 资源适配器内部错误情况 |
Throws | IllegalStateException: 调用连接清除时处于非法状态。例如,如果正在进行不允许清除连接的 localtransaction 操作。 |
cleanup
void cleanup() throws ResourceException
- Application server calls this method to force any cleanup on the
ManagedConnection instance.
The method ManagedConnection.cleanup initiates a cleanup of the any client-specific state as maintained by a ManagedConnection instance. The cleanup should invalidate all connection handles that had been created using this ManagedConnection instance. Any attempt by an application component to use the connection handle after cleanup of the underlying ManagedConnection should result in an exception.
The cleanup of ManagedConnection is always driven by an application server. An application server should not invoke ManagedConnection.cleanup when there is an uncompleted transaction (associated with a ManagedConnection instance) in progress.
The invocation of ManagedConnection.cleanup method on an already cleaned-up connection should not throw an exception.
The cleanup of ManagedConnection instance resets its client specific state and prepares the connection to be put back in to a connection pool. The cleanup method should not cause resource adapter to close the physical pipe and reclaim system resources associated with the physical connection.
- Throws:
ResourceException
- generic exception if operation failsResourceAdapterInternalException
- resource adapter internal error conditionIllegalStateException
- Illegal state for calling connection cleanup. Example - if a localtransaction is in progress that doesn't allow connection cleanup
public void
associateConnection(Object connection) throws ResourceException
容器使用此方法更改应用程序级别的连接句柄与 ManagedConneciton 实例的关联。容器应该查找正确的 ManagedConnection 实例并调用 associateConnection 方法。
资源适配器需要实现 associateConnection 方法。ManagedConnection 的方法实现应该取消连接句柄(作为参数传递)与当前关联 ManagedConnection 之间的关联,并将自身与新的连接句柄关联。
connection | 应用程序级别的连接句柄 |
Throws | ResourceException: 无法将连接句柄与此 ManagedConnection 实例关联 |
Throws | IllegalStateException: 调用此方法时处于非法状态 |
Throws | ResourceAdapterInternalException: 资源适配器内部错误情况 |
associateConnection
void associateConnection(Object connection) throws ResourceException
- Used by the container to change the association of an
application-level connection handle with a ManagedConneciton
instance. The container should find the right ManagedConnection
instance and call the associateConnection method.
The resource adapter is required to implement the associateConnection method. The method implementation for a ManagedConnection should dissociate the connection handle (passed as a parameter) from its currently associated ManagedConnection and associate the new connection handle with itself.
- Parameters:
connection
- Application-level connection handle- Throws:
ResourceException
- Failed to associate the connection handle with this ManagedConnection instanceIllegalStateException
- Illegal state for invoking this methodResourceAdapterInternalException
- Resource adapter internal error condition
public void
addConnectionEventListener(ConnectionEventListener listener)
向 ManagedConnection 实例添加一个连接事件侦听器。
向已注册 ConnectionEventListener 实例通知连接关闭和错误事件,以及 ManagedConnection 上与本地事务相关的事件。
listener | 要注册的新 ConnectionEventListener |
addConnectionEventListener
void addConnectionEventListener(ConnectionEventListener listener)
- Adds a connection event listener to the ManagedConnection
instance.
The registered ConnectionEventListener instances are notified of connection close and error events, also of local transaction related events on the Managed Connection.
- Parameters:
listener
- a new ConnectionEventListener to be registered
public void
removeConnectionEventListener(ConnectionEventListener listener)
从 ManagedConnection 实例中移除已经注册的连接事件侦听器。
listener | 要移除的已注册连接事件侦听器 |
removeConnectionEventListener
void removeConnectionEventListener(ConnectionEventListener listener)
- Removes an already registered connection event listener from the
ManagedConnection instance.
- Parameters:
listener
- already registered connection event listener to be removed
public XAResource
getXAResource() throws ResourceException
返回一个 javax.transaction.xa.XAresource
实例。如果由事务管理器协调的 JTA 事务中正在使用 ManagedConnection 实例,则应用服务器使用事务管理器添加此 XAResource 实例。
return | XAResource 实例 |
Throws | ResourceException: 如果操作失败,则抛出此一般异常 |
Throws | NotSupportedException: 如果不支持该操作 |
Throws | ResourceAdapterInternalException: 资源适配器内部错误情况 |
getXAResource
XAResource getXAResource() throws ResourceException
- Returns an
javax.transaction.xa.XAresource
instance. An application server enlists this XAResource instance with the Transaction Manager if the ManagedConnection instance is being used in a JTA transaction that is being coordinated by the Transaction Manager. - Returns:
- XAResource instance
- Throws:
ResourceException
- generic exception if operation failsNotSupportedException
- if the operation is not supportedResourceAdapterInternalException
- resource adapter internal error condition
public LocalTransaction
getLocalTransaction() throws ResourceException
返回一个 javax.resource.spi.LocalTransaction
实例。容器使用 LocalTransaction 接口管理 RM 实例的本地事务。
return | LocalTransaction 实例 |
Throws | ResourceException: 如果操作失败,则抛出此一般异常 |
Throws | NotSupportedException: 如果不支持该操作 |
Throws | ResourceAdapterInternalException: 资源适配器内部错误情况 |
getLocalTransaction
LocalTransaction getLocalTransaction() throws ResourceException
- Returns an
javax.resource.spi.LocalTransaction
instance. The LocalTransaction interface is used by the container to manage local transactions for a RM instance. - Returns:
- LocalTransaction instance
- Throws:
ResourceException
- generic exception if operation failsNotSupportedException
- if the operation is not supportedResourceAdapterInternalException
- resource adapter internal error condition
public ManagedConnectionMetaData
getMetaData() throws ResourceException
获取此连接的底层 EIS 资源管理器实例的元数据信息。ManagedConnectionMetaData 接口提供与 ManagedConenction 实例关联的底层 EIS 实例的有关信息。
return | ManagedConnectionMetaData 实例 |
Throws | ResourceException: 如果操作失败,则抛出此一般异常 |
Throws | NotSupportedException: 如果不支持该操作 |
getMetaData
ManagedConnectionMetaData getMetaData() throws ResourceException
Gets the metadata information for this connection's underlying EIS resource manager instance. The ManagedConnectionMetaData interface provides information about the underlying EIS instance associated with the ManagedConenction instance.
- Returns:
- ManagedConnectionMetaData instance
- Throws:
ResourceException
- generic exception if operation failsNotSupportedException
- if the operation is not supported
public void
setLogWriter(java.io.PrintWriter out) throws ResourceException
设置此 ManagedConnection 实例的日志 writer。
日志 writer 是一个字符输出流,此 ManagedConnection 实例的所有记录和跟踪消息都将打印到该输出流。应用服务器根据连接池的需要管理输出流与 ManagedConnection 实例的关联。
开始创建 ManagedConnection 对象时,从 ManagedConnectionFactory 中获取与此实例关联的默认日志 writer。应用服务器可以使用 setLogWriter 方法设置特定于此 ManagedConnection 的日志 writer,以记录/跟踪此实例。
out | 要关联的字符输出流 |
Throws | ResourceException: 如果操作失败,则抛出此一般异常 |
Throws | ResourceAdapterInternalException: 与资源适配器相关的错误情况 |
setLogWriter
void setLogWriter(PrintWriter out) throws ResourceException
- Sets the log writer for this ManagedConnection instance.
The log writer is a character output stream to which all logging and tracing messages for this ManagedConnection instance will be printed. Application Server manages the association of output stream with the ManagedConnection instance based on the connection pooling requirements.
When a ManagedConnection object is initially created, the default log writer associated with this instance is obtained from the ManagedConnectionFactory. An application server can set a log writer specific to this ManagedConnection to log/trace this instance using setLogWriter method.
- Parameters:
out
- Character Output stream to be associated- Throws:
ResourceException
- generic exception if operation failsResourceAdapterInternalException
- resource adapter related error condition
public java.io.PrintWriter
getLogWriter() throws ResourceException
获取此 ManagedConnection 实例的日志 writer。
日志 writer 是一个字符输出流,此 ManagedConnection 实例的所有记录和跟踪消息都将打印到该输出流。ConnectionManager 根据连接池的需要管理输出流与 ManagedConnection 实例的关联。
与 ManagedConnection 实例关联的日志 writer 可以是 ManagedConnectionFactory(创建此连接)的默认设置,也可以是应用服务器专门为此实例设置的 writer。
return | 与此 ManagedConnection 实例关联的字符输出流 |
Throws | ResourceException: 如果操作失败,则抛出此一般异常 |
getLogWriter
PrintWriter getLogWriter() throws ResourceException
- Gets the log writer for this ManagedConnection instance.
The log writer is a character output stream to which all logging and tracing messages for this ManagedConnection instance will be printed. ConnectionManager manages the association of output stream with the ManagedConnection instance based on the connection pooling requirements.
The Log writer associated with a ManagedConnection instance can be one set as default from the ManagedConnectionFactory (that created this connection) or one set specifically for this instance by the application server.
- Returns:
- Character ourput stream associated with this Managed- Connection instance
- Throws:
ResourceException
- generic exception if operation fails
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Submit a bug or feature
Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.
PS : 未经我党受权你也可自由散发此文档。 如有任何错误请自行修正;若因此而造成任何损失请直接找人民主席,请勿与本人联系。谢谢!