Description

The StockTrader Business Service is responsible for providing an interface to clients for the state of the application as a whole. It provides access to data within the StockTrader Database directly, as well as passing off buy and sell orders to the queue managed by the StockTrader Order Processor Service. Nearly all interactions (including read-only) interactions with any data managed by the Stonehenge StockTrader Sample Application, will flow through the Business Service at some point. This excludes only overall application configuration which is managed by a separate service.

Live Demonstrations

In December of 2009, the PHP and .NET implementations of the StockTrader Business Service were ported to run on Windows Azure. These live cloud-based version of the StockTrader Business Service can be accessed using the URLs in the table below:

Service Actions

The namespace used throughout the service contract is http://trade.samples.websphere.ibm.com. This is due to historical reasons, and was originally done to ensure compatibility between the .NET Implementation of the StockTrader sample and IBM's original implementation of the same. This was before the StockTrader sample became a part of Apache Stonehenge.

isOnline

The isOnline action is a one-way service call that is used by clients of this service to determine if the service is running. It is employed in StockTrader load-balanced scenarios to ensure application-level failover of service-to-service remote calls to clusters running this service.

login (deprecated in M2)

The login action is used to indicate that a login has occurred. It returns information about the account associated with the userID passed in. In the case of an error, the error message can be checked to determine why the login failed.

In those implementations supporting claims based security, this service action is not explicitly called whenever a user logs in. In subsequent service calls that have a userID parameter, an empty string is sent instead, since the userID can be deduced from the claims included as part of the service call.

getOrders

The getOrders action is used to retrieve recent orders placed by a given users. Orders are considered to be user instructions to buy or sell a stock. This means that not every order will have a negative impact on the user's account balance. Additionally sell orders are not associated with a specific holding, as they may include only a portion of an existing holding. Buy orders, on the other hand, will always become a new holding.

Each implementations can control the number of orders returned, and it is not guaranteed to be a complete list of all orders ever placed. Those implementations that support claims-based security will accept an empty string in place of a userID, since the userID can be deduced from the claims included as part of the service call.

getAccountData

The getAccountData action is used to retrieve information about an account associated with a given userID. This data will contain purely statistical information about the account itself. In order to get information about the user specifically, the getAccountProfileData action should be used instead.

Those implementations that support claims-based security will accept an empty string in place of a userID, since the userID can be deduced from the claims included as part of the service call.

getAccountProfileData

The getAccountProfileData action is used to retrieve authentication, contact, and payment information for a given user, based on the user's userID.

Those implementations that support claims-based security will accept an empty string in place of a userID, since the userID can be deduced from the claims included as part of the service call.

updateAccountProfile

The updateAccountProfile action is used to update account profile data for a given user with the data supplied. All data can be changed for a given user, except for the user's userID.

logout (deprecated in M2)

The logout action is used to signal that a user has logged out of the client application.

In those implementations supporting claims based security, this service action is not explicitly called whenever a user logs out.

buy

The buy action is used to asynchronously register a buy order with the StockTrader Order Processor Service. By submitting an order through this action, there is no guarantees that the order will be successfully completed.

Those implementations that support claims-based security will accept an empty string in place of a userID, since the userID can be deduced from the claims included as part of the service call.

sell (deprecated)

The sell action is used to asynchronously register a sell order with the StockTrader Order Processor Service. By submitting an order through this action, there is no guarantees that the order will be successfully completed.

This action differs from the sellEnhanced action in that this action always sells the entire holding. This action has been retained for backwards compatibility with IBM Trade 6.1, as all implementations of the Stonehenge StockTrader Sample Application that are a part of the Apache Stonehenge project use the sellEnhanced action.

Those implementations that support claims-based security will accept an empty string in place of a userID, since the userID can be deduced from the claims included as part of the service call.

getHoldings

The getHoldings action is used to retrieve a list of the user's holdings.

Those implementations that support claims-based security will accept an empty string in place of a userID, since the userID can be deduced from the claims included as part of the service call.

register

The register action is used to create an account and a new user within the StockTrader application.

Those implementations that support claims-based security will not rely on the password used here for user authentication. A Passive STS will be used for authentication of a user with a third party. The claims passed from that Passive STS will determine whether or not the user is authorized to perform actions requested.

getClosedOrders

The getClosedOrders action is used to get a list of the orders where the status is set to closed. This allows orders to be displayed to the user when accessing the StockTrader Client. Orders returned as a result of calling the service with this action will be marked as completed, and will not be reported again by subsequent calls.

getMarketSummary

The getMarketSummary action is used to retrieve a summary of the current market conditions.

getQuote

The getQuote action is used to generate a quote for a given stock.

getHolding

The getHolding action is used to retrieve details about a specific holding of a given user. Even though the holdingID should be unique for all holdings, a userID is supplied for this service call as well to ensure absolutely that the correct holding is located.

Those implementations that support claims-based security will accept an empty string in place of a userID, since the userID can be deduced from the claims included as part of the service call.

getTopOrders

The getTopOrders action is used to retrieve the top N orders for a given user. Each implementation is responsible for determining the number of orders that will be returned.

Those implementations that support claims-based security will accept an empty string in place of a userID, since the userID can be deduced from the claims included as part of the service call.

sellEnhanced

The sellEnhanced action is used to asynchronously register a sell order with the StockTrader Order Processor Service. By submitting an order through this action, there is no guarantees that the order will be successfully completed.

This action differs from the sell action in that this action allows for the partial sale of holdings. All implementations of the Stonehenge StockTrader Sample Application that are a part of the Apache Stonehenge project use the sellEnhanced action as opposed to the sell action for handling the sale of holdings.

Those implementations that support claims-based security will accept an empty string in place of a userID, since the userID can be deduced from the claims included as part of the service call.