53.1.1 Using the Outbound Resource Adapter

In most cases, Java EE application developers use outbound resource adapters developed by a third party. Outbound resource adapters either implement the Common Client Interface (CCI) or provide a custom interface for applications to interact with the EIS. Outbound resource adapters provide Java EE applications with the following elements:

• Connection factories

• Connection handles

• Other interfaces and objects specific to the EIS domain

Java EE applications obtain an instance of the connection factory via resource injection and then use the factory object to obtain connection handles to the EIS. The connection handles enable the application to make requests and obtain information from the EIS.

The trading-rar module provides a custom client interface that consists of the classes listed in Table 53-1.

The ResourceAccessBean managed bean in the trading-war module configures a connection factory for the trading-rar resource adapter by using the @ConnectionFactoryDefinition annotation as follows:

@Named
@SessionScoped
@ConnectionFactoryDefinition(
    name = "java:comp/env/eis/TradeConnectionFactory",
    interfaceName = "javaeetutorial.trading.rar.api.TradeConnectionFactory",
    resourceAdapter = "#trading-rar",
    minPoolSize = 5,
    transactionSupport = 
            TransactionSupport.TransactionSupportLevel.NoTransaction
)
public class ResourceAccessBean implements Serializable { ... }

The name parameter specifies the JNDI name for the connection factory. This example registers the connection factory in the java:comp scope. You can use the ConnectionFactoryDefinition annotation to specify a different scope, such as java:global, java:app, or java:module. The AdministeredObjectDefinition annotation also enables you to register administered connector objects in the JNDI namespace.

The interfaceName parameter specifies the interface implemented by the connection factory included in the resource adapter. In this example, this is a custom interface.

The resourceAdapter parameter specifies the name of the resource adapter that contains the connection factory implementation. The # prefix in #trading-rar indicates that trading-rar is an embedded resource adapter that is bundled in the same EAR as this web application.

The managed bean obtains a connection factory object using resource injection as follows:

...
public class ResourceAccessBean implements Serializable {
    @Resource(lookup = "java:comp/env/eis/TradeConnectionFactory")
    private TradeConnectionFactory connectionFactory;
    ...
}

The managed bean uses the connection factory to obtain connection handles as follows:

TradeConnection connection = connectionFactory.getConnection();

The resource adapter returns a connection handle associated with a physical connection to the EIS. Once a connection handle is available, the managed bean submits a trade and obtains the response as follows:

TradeOrder order = new TradeOrder();
order.setNShares(1000);
order.setTicker(TradeOrder.Ticker.YYYY);
order.setOrderType(TradeOrder.OrderType.BUY);
order.setOrderClass(TradeOrder.OrderClass.MARKET);
...
try {
    TradeResponse response = connection.submitOrder(order);
    ...
} catch (TradeProcessingException ex) { ... }

53.1.2 Implementing the Outbound Resource Adapter

The trading-rar module implements the outbound contract and a custom client interface for the simple legacy stock trading platform EIS used in this example. The architecture of the outbound resource adapter is shown in Figure 53-2.

Figure 53-2 Architecture of the trading Example

Description of "Figure 53-2 Architecture of the trading Example"

The trading-rar module implements the interfaces listed in Table 53-2.

When the trading-ear archive is deployed and a connection pool resource is configured as described in Using the Outbound Resource Adapter, the application server creates TradeConnectionFactory objects that applications can obtain using resource injection. The TradeConnectionFactory implementation delegates creating connections to the connection manager provided by the application server.

The connection manager uses the ManagedConnectionFactory implementation to obtain physical connections to the EIS and maintains a pool of active physical connections. When an application requests a connection handle, the connection manager associates a connection from the pool with a new connection handle that the application can use. Connection pooling improves application performance and simplifies resource adapter development.

For more details, see the code and the comments in the trading-rar module.

53.1.3 Running the trading Example

You can use either NetBeans IDE or Maven to build, package, deploy, and run the trading example.