type=page
status=published
title=The trading Example
next=connectorexample003.html
prev=connectorexample001.html
~~~~~~
= The trading Example


[[CHDFHAID]]

[[the-trading-example]]
The trading Example
-------------------

The `trading` example demonstrates how to implement and use a simple
outbound resource adapter that submits requests to a legacy EIS using a
TCP socket. The example demonstrates the scenario in
link:#CHDHADIG[Figure 56-1] and consists of the following modules:

* `trading-eis`: A Java SE program that simulates a legacy EIS
* `trading-rar`: The outbound resource adapter implementation
* `trading-war`: A web application that uses the resource adapter
* `trading-ear`: An enterprise archive that contains the resource
adapter and the web application

[[CHDHADIG]]

.*Figure 56-1 The trading Example*
image:img/javaeett_dt_054.png[
"This figure shows the trading example components: a deployed WAR and RAR
that communicate with the EIS over a TCP socket."]

The `trading-eis` module is an auxiliary project that resembles a legacy
stock trading execution platform. It contains a Java SE program that
listens for trading requests in plain text on a TCP socket. The program
replies to trading requests with a status value, a confirmation number,
and the dollar amounts for the requested shares and fees. For example, a
request-response pair would look like this:

[source,oac_no_warn]
----
>> BUY 1000 ZZZZ MARKET
<< EXECUTED #1234567 TOTAL 50400.00 FEE 252.00
----

The `trading-rar` module implements the outbound contract of the Java EE
Connector Architecture to submit requests and obtain responses from the
legacy stock trading execution platform. The `trading-rar` module
provides and implements a custom client interface for Java EE
applications to use. This interface is simpler than the Common Client
Interface (CCI).

The `trading-war` module is a web application with a JavaServer Faces
interface and a managed bean. This application enables clients to submit
trades to the EIS using the resource adapter provided by the
`trading-rar` module. The `trading-war` module uses the custom client
interface provided by the resource adapter to obtain connections to the
EIS.

[[CHDFADJD]]

[[using-the-outbound-resource-adapter]]
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 link:#CHDCHJAC[Table 56-1].

[[sthref242]][[CHDCHJAC]]


*Table 56-1 Classes and Interfaces in the javaeetutorial.trading.rar.api
Package*


[width="80%",cols="20%,60%"]
|=======================================================================
|*API Component* |*Description*
|`TradeOrder` |Represents a trade order for the EIS

|`TradeResponse` |Represents a response from the EIS to a trade request

|`TradeConnection` a|
Represents a connection handle to the EIS

Provides a method for applications to submit trades to the EIS

|`TradeConnectionFactory` |Enables applications to obtain connection
handles to the EIS

|`TradeProcessingException` |Indicates that a problem occurred
processing a trade request
|=======================================================================


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:

[source,oac_no_warn]
----
@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.


[width="100%",cols="100%",]
|=======================================================================
a|
*Note*:

You can also configure a connection factory for a previously deployed
outbound resource adapter using the administration commands from your
application server. However, this is a vendor-specific procedure.

|=======================================================================


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

[source,oac_no_warn]
----
...
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:

[source,oac_no_warn]
----
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:

[source,oac_no_warn]
----
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) { ... }
----

[[sthref243]]

[[implementing-the-outbound-resource-adapter]]
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 link:#CHDIGAJE[Figure 56-2].

[[CHDIGAJE]]

.*Figure 56-2 Architecture of the trading Example*
image:img/javaeett_dt_055.png[
"This figure shows the classes in each of the modules of the trading
example."]

The `trading-rar` module implements the interfaces listed in
link:#CHDIBBIC[Table 56-2].

[[sthref245]][[CHDIBBIC]]


*Table 56-2 Interfaces Implemented in the trading-rar Module*


[width="99%",cols="20%,20%,60%"]
|=======================================================================
|*Package* |*Interface* |*Description*
|`javax.resource.spi` |`ResourceAdapter` |Defines the lifecycle methods
of the resource adapter

|`javax.resource.spi` |`ManagedConnectionFactory` |Defines a connection
factory that the connection manager from the application server uses to
obtain physical connections to the EIS

|`javax.resource.spi` |`ManagedConnection` |Defines a physical
connection to the EIS that can be managed by the connection manager

|`trading.rar.api` |`TradeConnectionFactory` |Defines a connection
factory that applications use to obtain connection handles

|`trading.rar.api` |`TradeConnection` |Defines a connection handle that
applications use to interact with the EIS
|=======================================================================


When the `trading-ear` archive is deployed and a connection pool
resource is configured as described in link:#CHDFADJD[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.

[[sthref246]]

[[running-the-trading-example]]
Running the trading Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

The following topics are addressed here:

* link:#BABCHDDC[To Run the trading Example Using NetBeans IDE]
* link:#BABFJAAG[To Run the trading Example Using Maven]

[[BABCHDDC]]

[[to-run-the-trading-example-using-netbeans-ide]]
To Run the trading Example Using NetBeans IDE
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1.  Make sure that GlassFish Server has been started (see
link:usingexamples002.html#BNADI[Starting and Stopping GlassFish
Server]).
2.  From the File menu, choose Open Project.
3.  In the Open Project dialog box, navigate to:
+
[source,oac_no_warn]
----
tut-install/examples/connectors
----
4.  Select the `trading` folder.
5.  Click Open Project.
6.  In the Projects tab, expand the `trading` node.
7.  Right-click the `trading-eis` module and select Open Project.
8.  Right-click the `trading-eis` project and select Run.
+
The messages from the EIS appear in the Output tab:
+
[source,oac_no_warn]
----
Trade execution server listening on port 4004.
----
9.  Right-click the `trading-ear` project and select Build.
+
This command packages the resource adapter and the web application in an
EAR file and deploys it to GlassFish Server.
10. Open the following URL in a web browser:
+
[source,oac_no_warn]
----
http://localhost:8080/trading/
----
+
The web interface enables you to connect to the EIS and submit trades.
The server log shows the requests from the web application and the call
sequence that provides connection handles from the resource adapter.
11. Before undeploying the `trading-ear` application, close the
`trading-eis` application from the status bar.

[[BABFJAAG]]

[[to-run-the-trading-example-using-maven]]
To Run the trading Example Using Maven
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1.  Make sure that GlassFish Server has been started (see
link:usingexamples002.html#BNADI[Starting and Stopping GlassFish
Server]).
2.  In a terminal window, go to:
+
[source,oac_no_warn]
----
tut-install/examples/connectors/trading/
----
3.  Enter the following command:
+
[source,oac_no_warn]
----
mvn install
----
+
This command builds and packages the resource adapter and the web
application into an EAR archive and deploys it to GlassFish Server.
4.  In the same terminal window, go to the `trading-eis` directory:
+
[source,oac_no_warn]
----
cd trading-eis
----
5.  Enter the following command to run the trade execution platform:
+
[source,oac_no_warn]
----
mvn exec:java
----
+
The messages from the EIS appear in the terminal window:
+
[source,oac_no_warn]
----
Trade execution server listening on port 4004.
----
6.  Open the following URL in a web browser:
+
[source,oac_no_warn]
----
http://localhost:8080/trading/
----
+
The web interface enables you to connect to the EIS and submit trades.
The server log shows the requests from the web application and the call
sequence that provides connection handles from the resource adapter.
7.  Before undeploying the `trading-ear` application, press Ctrl+C on
the terminal window to close the `trading-eis` application.
