ResourceAdapter (Java EE 5)

This represents a resource adapter instance and contains operations for lifecycle management and message endpoint setup. A concrete implementation of this interface is required to be a JavaBean.

Version:

1.0

Author:

Ram Jeyaraman

public void start(BootstrapContext ctx) throws ResourceAdapterInternalException
引导资源适配器实例时调用此方法。这可以在资源适配器部署或应用服务器启动期间进行。这是一个来自应用服务器的启动通知，此方法由应用服务器线程调用。应用服务器线程在未指定的上下文中执行。

在此方法调用期间，ResourceAdapter JavaBean 负责初始化资源适配器实例。在此方法调用期间抛出任何异常都会导致应用服务器终止此特定资源适配器实例的引导过程。

ctx	一个引导上下文，它包含对资源适配器实例可以使用的有用工具的引用。
Throws	ResourceAdapterInternalException: 指示引导失败。该资源适配器实例不能使用，必须丢弃。

英文文档：

start

void start(BootstrapContext ctx)
           throws ResourceAdapterInternalException

This is called when a resource adapter instance is bootstrapped. This may be during resource adapter deployment or application server startup. This is a startup notification from the application server, and this method is called by an application server thread. The application server thread executes in an unspecified context.

During this method call a ResourceAdapter JavaBean is responsible for initializing the resource adapter instance. Any exception thrown during this method call causes the application server to abort the bootstrap procedure for this specific resource adapter instance.

Parameters:

ctx - a bootstrap context containing references to useful facilities that could be used by a resource adapter instance.

Throws:

ResourceAdapterInternalException - indicates bootstrap failure. The resource adapter instance is unusable and must be discarded.

public void stop()
取消部署资源适配器实例或者应用服务器关闭期间调用此方法。这是一个来自应用服务器的关闭通知，此方法由应用服务器线程调用。应用服务器线程在未指定的上下文中执行。

在此方法调用期间，ResourceAdapter JavaBean 负责按顺序关闭资源适配器实例。此方法抛出的任何异常都不能改变导致调用此方法的应用服务器关闭过程或资源适配器取消部署过程。应用服务器可以记录异常信息，用于错误报告。

英文文档：

stop

void stop()

This is called when a resource adapter instance is undeployed or during application server shutdown. This is a shutdown notification from the application server, and this method is called by an application server thread. The application server thread executes in an unspecified context.

During this method call, a ResourceAdapter JavaBean is responsible for performing an orderly shutdown of the resource adapter instance. Any exception thrown by this method call does not alter the processing of the application server shutdown or resource adapter undeployment that caused this method call. The application server may log the exception information for error reporting purposes.

public void endpointActivation(MessageEndpointFactory endpointFactory, ActivationSpec spec) throws ResourceException
激活消息端点期间调用此方法。这会使资源适配器执行必要的设置（即使用消息提供者设置消息端点的消息传送）。注意，向消息端点传送消息甚至会在此方法返回之前启动。

仅当此方法成功完成且没有抛出任何异常时，端点激活才视为成功。

endpointFactory	消息端点工厂实例。
spec	激活的规范 JavaBean 实例。
Throws	NotSupportedException: 指示由于激活设置信息不正确而拒绝消息端点激活。

英文文档：

endpointActivation

void endpointActivation(MessageEndpointFactory endpointFactory,
                        ActivationSpec spec)
                        throws ResourceException

This is called during the activation of a message endpoint. This causes the resource adapter instance to do the necessary setup (ie., setup message delivery for the message endpoint with a message provider). Note that message delivery to the message endpoint might start even before this method returns.

Endpoint activation is deemed successful only when this method completes successfully without throwing any exceptions.

Parameters:

endpointFactory - a message endpoint factory instance.

spec - an activation spec JavaBean instance.

Throws:

NotSupportedException - indicates message endpoint activation rejection due to incorrect activation setup information.

ResourceException

public void endpointDeactivation(MessageEndpointFactory endpointFactory, ActivationSpec spec)
取消激活消息端点时调用此方法。作为此方法调用的参数传递的实例必须与传入相应 endpointActivation 调用的实例相同。这会使资源适配器停止向消息端点传送消息。

忽略此方法抛出的任何异常。调用此方法之后，将该端点视为不活动。

endpointFactory	消息端点工厂实例。
spec	激活的规范 JavaBean 实例。

英文文档：

endpointDeactivation

void endpointDeactivation(MessageEndpointFactory endpointFactory,
                          ActivationSpec spec)

This is called when a message endpoint is deactivated. The instances passed as arguments to this method call should be identical to those passed in for the corresponding endpointActivation call. This causes the resource adapter to stop delivering messages to the message endpoint.

Any exception thrown by this method is ignored. After this method call, the endpoint is deemed inactive.

Parameters:

endpointFactory - a message endpoint factory instance.

spec - an activation spec JavaBean instance.

public XAResource[] getXAResources(ActivationSpec[] specs) throws ResourceException
在崩溃恢复期间应用服务器调用此方法。此方法带有一个 ActivationSpec JavaBean 数组，返回一个 XAResource 对象数组，其中每个对象表示一个唯一的资源管理器。 如果资源适配器未实现 XAResource 接口，则返回 null。否则，它必须返回一个 XAResource 对象数组，其中每个对象都表示一个此端点应用程序使用的唯一资源管理器。 应用服务器使用 XAResource 对象查询所需事务列表中的每个资源管理器。然后，它向参与的资源管理器发送提交决定，以完成每个挂起的事务。

specs	一个 ActivationSpec JavaBean 数组，其中每个 JavaBean 都对应于系统崩溃之前处于活动状态的已部署端点应用程序。
Throws	ResourceException: 如果由于错误情况导致操作失败，则抛出此一般异常。
return	一个 XAResource 对象数组，其中每个对象都表示一个唯一的资源管理器。

英文文档：

getXAResources

XAResource[] getXAResources(ActivationSpec[] specs)
                            throws ResourceException

This method is called by the application server during crash recovery. This method takes in an array of ActivationSpec JavaBeans and returns an array of XAResource objects each of which represents a unique resource manager. The resource adapter may return null if it does not implement the XAResource interface. Otherwise, it must return an array of XAResource objects, each of which represents a unique resource manager that was used by the endpoint applications. The application server uses the XAResource objects to query each resource manager for a list of in-doubt transactions. It then completes each pending transaction by sending the commit decision to the participating resource managers.

Parameters:

specs - an array of ActivationSpec JavaBeans each of which corresponds to an deployed endpoint application that was active prior to the system crash.

Returns:

an array of XAResource objects each of which represents a unique resource manager.

Throws:

ResourceException - generic exception if operation fails due to an error condition.

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