001 /** 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017 package org.apache.geronimo.samples.daytrader; 018 019 020 import java.math.BigDecimal; 021 import java.rmi.Remote; 022 import java.rmi.RemoteException; 023 import java.util.Collection; 024 025 /** 026 * TradeServices interface specifies the business methods provided by the Trade online broker application. 027 * These business methods represent the features and operations that can be performed by customers of 028 * the brokerage such as login, logout, get a stock quote, buy or sell a stock, etc. 029 * This interface is implemented by {@link Trade} providing an EJB implementation of these 030 * business methods and also by {@link TradeDirect} providing a JDBC implementation. 031 * 032 * @see Trade 033 * @see TradeDirect 034 * 035 */ 036 public interface TradeServices extends Remote { 037 038 /** 039 * Compute and return a snapshot of the current market conditions 040 * This includes the TSIA - an index of the price of the top 100 Trade stock quotes 041 * The openTSIA ( the index at the open) 042 * The volume of shares traded, 043 * Top Stocks gain and loss 044 * 045 * @return A snapshot of the current market summary 046 */ 047 public MarketSummaryDataBean getMarketSummary() throws Exception, RemoteException; 048 049 050 /** 051 * Purchase a stock and create a new holding for the given user. 052 * Given a stock symbol and quantity to purchase, retrieve the current quote price, 053 * debit the user's account balance, and add holdings to user's portfolio. 054 * buy/sell are asynchronous, using J2EE messaging, 055 * A new order is created and submitted for processing to the TradeBroker 056 * 057 * @param userID the customer requesting the stock purchase 058 * @param symbol the symbol of the stock being purchased 059 * @param quantity the quantity of shares to purchase 060 * @return OrderDataBean providing the status of the newly created buy order 061 */ 062 063 064 public OrderDataBean buy(String userID, String symbol, double quantity, int orderProcessingMode) throws Exception, RemoteException; 065 066 /** 067 * Sell a stock holding and removed the holding for the given user. 068 * Given a Holding, retrieve current quote, credit user's account, 069 * and reduce holdings in user's portfolio. 070 * 071 * @param userID the customer requesting the sell 072 * @param holdingID the users holding to be sold 073 * @return OrderDataBean providing the status of the newly created sell order 074 */ 075 public OrderDataBean sell(String userID, Integer holdingID, int orderProcessingMode) throws Exception, RemoteException; 076 077 078 /** 079 * Queue the Order identified by orderID to be processed 080 * 081 * Orders are submitted through JMS to a Trading Broker 082 * and completed asynchronously. This method queues the order for processing 083 * 084 * The boolean twoPhase specifies to the server implementation whether or not the 085 * method is to participate in a global transaction 086 * 087 * @param orderID the Order being queued for processing 088 * @return OrderDataBean providing the status of the completed order 089 */ 090 public void queueOrder(Integer orderID, boolean twoPhase) throws Exception, RemoteException; 091 092 /** 093 * Complete the Order identefied by orderID 094 * Orders are submitted through JMS to a Trading agent 095 * and completed asynchronously. This method completes the order 096 * For a buy, the stock is purchased creating a holding and the users account is debited 097 * For a sell, the stock holding is removed and the users account is credited with the proceeds 098 * 099 * The boolean twoPhase specifies to the server implementation whether or not the 100 * method is to participate in a global transaction 101 * 102 * @param orderID the Order to complete 103 * @return OrderDataBean providing the status of the completed order 104 */ 105 public OrderDataBean completeOrder(Integer orderID, boolean twoPhase) throws Exception, RemoteException; 106 107 /** 108 * Cancel the Order identefied by orderID 109 * 110 * The boolean twoPhase specifies to the server implementation whether or not the 111 * method is to participate in a global transaction 112 * 113 * @param orderID the Order to complete 114 * @return OrderDataBean providing the status of the completed order 115 */ 116 public void cancelOrder(Integer orderID, boolean twoPhase) throws Exception, RemoteException; 117 118 119 /** 120 * Signify an order has been completed for the given userID 121 * 122 * @param userID the user for which an order has completed 123 * @param orderID the order which has completed 124 * 125 */ 126 public void orderCompleted(String userID, Integer orderID) throws Exception, RemoteException; 127 128 129 /** 130 * Get the collection of all orders for a given account 131 * 132 * @param userID the customer account to retrieve orders for 133 * @return Collection OrderDataBeans providing detailed order information 134 */ 135 public Collection getOrders(String userID) throws Exception, RemoteException; 136 137 /** 138 * Get the collection of completed orders for a given account that need to be alerted to the user 139 * 140 * @param userID the customer account to retrieve orders for 141 * @return Collection OrderDataBeans providing detailed order information 142 */ 143 public Collection getClosedOrders(String userID) throws Exception, RemoteException; 144 145 146 /** 147 * Given a market symbol, price, and details, create and return a new {@link QuoteDataBean} 148 * 149 * @param symbol the symbol of the stock 150 * @param price the current stock price 151 * @param details a short description of the stock or company 152 * @return a new QuoteDataBean or null if Quote could not be created 153 */ 154 public QuoteDataBean createQuote(String symbol, String companyName, BigDecimal price) throws Exception, RemoteException; 155 156 /** 157 * Return a {@link QuoteDataBean} describing a current quote for the given stock symbol 158 * 159 * @param symbol the stock symbol to retrieve the current Quote 160 * @return the QuoteDataBean 161 */ 162 public QuoteDataBean getQuote(String symbol) throws Exception, RemoteException; 163 164 /** 165 * Return a {@link java.util.Collection} of {@link QuoteDataBean} 166 * describing all current quotes 167 * @return A collection of QuoteDataBean 168 */ 169 public Collection getAllQuotes() throws Exception, RemoteException; 170 171 /** 172 * Update the stock quote price and volume for the specified stock symbol 173 * 174 * @param symbol for stock quote to update 175 * @param price the updated quote price 176 * @return the QuoteDataBean describing the stock 177 */ 178 public QuoteDataBean updateQuotePriceVolume(String symbol, BigDecimal newPrice, double sharesTraded) throws Exception, RemoteException; 179 180 181 /** 182 * Return the portfolio of stock holdings for the specified customer 183 * as a collection of HoldingDataBeans 184 * 185 * @param userID the customer requesting the portfolio 186 * @return Collection of the users portfolio of stock holdings 187 */ 188 public Collection getHoldings(String userID) throws Exception, RemoteException; 189 190 /** 191 * Return a specific user stock holding identifed by the holdingID 192 * 193 * @param holdingID the holdingID to return 194 * @return a HoldingDataBean describing the holding 195 */ 196 public HoldingDataBean getHolding(Integer holdingID) throws Exception, RemoteException; 197 198 /** 199 * Return an AccountDataBean object for userID describing the account 200 * 201 * @param userID the account userID to lookup 202 * @return User account data in AccountDataBean 203 */ 204 public AccountDataBean getAccountData(String userID) 205 throws javax.ejb.FinderException, RemoteException; 206 207 /** 208 * Return an AccountProfileDataBean for userID providing the users profile 209 * 210 * @param userID the account userID to lookup 211 * @param User account profile data in AccountProfileDataBean 212 */ 213 public AccountProfileDataBean getAccountProfileData(String userID) throws Exception, RemoteException; 214 215 /** 216 * Update userID's account profile information using the provided AccountProfileDataBean object 217 * 218 * @param userID the account userID to lookup 219 * @param User account profile data in AccountProfileDataBean 220 */ 221 public AccountProfileDataBean updateAccountProfile(AccountProfileDataBean profileData) throws Exception, RemoteException; 222 223 224 /** 225 * Attempt to authenticate and login a user with the given password 226 * 227 * @param userID the customer to login 228 * @param password the password entered by the customer for authentication 229 * @return User account data in AccountDataBean 230 */ 231 public AccountDataBean login(String userID, String password) throws Exception, RemoteException; 232 233 /** 234 * Logout the given user 235 * 236 * @param userID the customer to logout 237 * @return the login status 238 */ 239 240 public void logout(String userID) throws Exception, RemoteException; 241 242 /** 243 * Register a new Trade customer. 244 * Create a new user profile, user registry entry, account with initial balance, 245 * and empty portfolio. 246 * 247 * @param userID the new customer to register 248 * @param password the customers password 249 * @param fullname the customers fullname 250 * @param address the customers street address 251 * @param email the customers email address 252 * @param creditcard the customers creditcard number 253 * @param initialBalance the amount to charge to the customers credit to open the account and set the initial balance 254 * @return the userID if successful, null otherwise 255 */ 256 public AccountDataBean register(String userID, 257 String password, 258 String fullname, 259 String address, 260 String email, 261 String creditcard, 262 BigDecimal openBalance) throws Exception, RemoteException; 263 264 265 /** 266 * Reset the TradeData by 267 * - removing all newly registered users by scenario servlet 268 * (i.e. users with userID's beginning with "ru:") * 269 * - removing all buy/sell order pairs 270 * - setting logoutCount = loginCount 271 * 272 * return statistics for this benchmark run 273 */ 274 public RunStatsDataBean resetTrade(boolean deleteAll) throws Exception, RemoteException; 275 } 276