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