/*
 * Created on Apr 28, 2005
 */
package stockportfolio;

import java.util.Date;
import java.util.List;

/**
 */
public interface IPortfolio {
    /** Add a block of stock to the portfolio.  A block is one purchase
     * of a number of shares at a given price.
     * @param stock a non-null stock
     * @param date a non-null date/time.  You may assume for now that each
     * block is at a later date/time than any previous block bought.
     * @param shares a number of shares, must be > 0.
     * @param pricePerShare price of each share, must be > 0.
     * @return true iff the buy was successful, i.e., if the block was
     * added to the portfolio.
     * @throws IllegalArgumentException if any argument value is invalid.
     */
    boolean buy(String stock, Date date, double shares, double pricePerShare);

    /** "Sell" a block of a stock, in the process calculating the capital gain
     * on the stock.  After being sold, the amount of the stock held in the
     * portfolio is decreased by the amount sold.  The "first in first out"
     * rule is used for determining which shares are sold.  
     * The block does not have to correspond exactly in size
     * to any block purchased.
     * @param stock non-null stock being sold; must be a stock currently owned.
     * @param saleDate non-null date of the sale.
     * @param shares number of shares being sold, must be >= 0.
     * @param pricePerShare price of each share, must be >= 0.
     * @return double the capital gain on the sale.
     * @throws IllegalArgumentException if any parameter value is invalid, or
     * if the number of shares being sold is greater than the number of shares
     * of that stock currently owned.
     */
    double sell(final String stock, final Date saleDate, final double shares,
            final double pricePerShare);

    /** Tells the number of shares owned of a particular stock.
     *   It is not an error to ask about
     * a stock which is not owned -- the method simply returns 0.0 in this case.
     * @param stock a non-null stock.
     * @return number of shares owned, which must be >= 0.  
     */
    double getSharesOwned(String stock);

    /** Return a list of all the blocks of stock that are owned. 
     * The list should be in order by stock name, then by date,
     * then by number of shares owned, then by share price.
     * Hint: you can do this sort in ONE LINE using Collections.sort
     * (if you have things set up right...)
     * @return a list of non-null stock blocks, in the order mentioned.
     * Each block is either the full block from some previous buy operation,
     * or is a partial block of stocks left over after some sell operation.
     */
    List getBlocksOwned();

    /** Gives a compact summary of the information in the Portfolio.
     * Should show the names of the stocks held, and the number of
     * shares of each; one per line, or several per line, is
     * recommended.
     */
    String toString();
}