Purpose

In this assignment, we will gain experience with one-dimensional arrays.  To date, we have been using the Vector class in situations in which an array is appropriate.  Specifically, you will now design the Inventory and Market classes for the trading game.  The Market class represents a market in a location -- where you buy and sell goods.  The Inventory represents an inventory of a vehicle or a market.

When you are in a Market, there are 5 commands you can enter:

• buy: to buy something
• sell: to sell something
• available: to see what the market has available to sell
• inventory: to see what you have available to sell
• exit: to leave the market and return to the location (note that you can be "at a location" and not be "in the market at the location" -- such as being in Boston without necesarily being in the Fish Market at Boston)

Note that some of the details about this assignment we are purposely leaving out -- they can be found in the Java documentation.  The Java documentation for all the classes and methods in this "Trader" project can be found here.

Lots 'o files

To get started, create a new directory for HW J7, and download the following files. Right click on each link, select "save as", and save them all to the same directory.  A number of the files are "placeholder" classes -- meaning they are mostly not yet implemented, but are included so this homework will compile.  And some of them are .class files -- these are files that you will be developing in other assignments.

Skeleton code

These are the files that you will need to submit.

• Inventory.java : This is the skeleton code for the Inventory class. 
• Market.java: This is the skeleton code for the Market class.  Note that we have provided a "dummy" body for the Market constructor so that you can start developing your code. You need to fix the body of this constructor in your final version of Market.java.

Code from previous assignments

You are welcome to use your code (from HWs J5 and J6) instead of these.  If you are unsure about the correctness of the code you previously developed, then you should use our versions. Note that it is fine for you to modify your Vehicle.java, Location.java, and Parser.java for whatever reason for this assignment, but none will be turned in for this HW J7.  If you do modify your classes, be sure not to change the method names (or parameter types).

• Vehicle.class: This is a compiled version of the Vehicle class from HW J6.  You are free (and even encouraged) to use the Vehicle.java that you developed in HW J6.  To do this, delete Vehicle.class from your HW J7 directory (if you downloaded this Vehicle.class) and copy your Vehicle.java from your HW J6 directory to your HW J7 directory.
• Location.class: This is a compiled version of the Location class from HW J5.  Follow the basic steps outlined for Vehicle.class, above, if you want to use your own version of the Location class.
• Parser.class: This is a compiled version of the Parser class from Lab 9.  Follow the basic steps outlined for Vehicle.class, above, if you want to use your own version of the Parser class.

Other code

• Cargo.java: This is the code for the Cargo class -- see below for more details.
• Map.java: This is the same version as was provided for HWJ6. This will be updated in HW J8 and lab 11.
• Descriptions.class:  This class is used to represent the description of names in the game -- names for planets, names for goods, etc.  It is a modified form of what will be developed in lab 10.  Note that you are free to use your Descriptions.java that you develop in lab 10, but we do not expect this (as HWJ7 is due only one day after you develop your own Descriptions.java).
• Universe.java: This class is used to represent the Universe.  It is an empty class, and will be developed in HWJ8.  It is included so that the Game.java file will compile.
• Game.java: This class runs the game.  It prints out some introductory information, and starts the game itself.  Note that although we provide the Game.java code, it is important that you understand how it works!

Part I: Cargo class

The Cargo class is a fairly simple class -- it has three fields, one constructor, the normal accessors and mutators, and two methods: getTotalPrice() and toString() method.  The default constructor creates a random Cargo -- the cargo type, amount, and cost are all randomly chosen. (Note that we set up a random number generator in the Game class, and we invoke operations on it to get our random values.)

In an effort to reduce the amount of work for this assignment, we are giving you the code for the Cargo.java.  However, it is important that you understand how it works!  Descriptions of all the methods can be found here.

You will notice in this file that the comments in Cargo.java are in a rather peculiar format.  These comments are used to generate the Java documentation for the Cargo class -- in fact, in all of our solution files for the project, we have these comments for every method and field, which is how we generate the Java documentation.  You are NOT required to put your comments in this form -- we just mention it in case you wondered (or were confused by) why we wrote comments like that.

Part II: Inventory class

In Part II of HW J7, you will create the ability to carry any number of Cargos (e.g., bananas, diamonds, gold, etc.) This  "inventory" will be used to both represent what is being held on a vehicle as well as represent what is being sold in a particular Location in the game.   This inventory is in an array of Cargo objects.  The various methods are used to manipulate that array of Cargo objects. Note that you can compile your code for the Inventory class as you develop it, but you will not be able to execute it (by executing "Game") until after you implement the Market class. We also recommend "pretty printing" numbers to screen by using the "Game.style.format" routine (see Cargo.java for an example of how this is used).

• cargo (Cargo[]): The inventory is an array of Cargo objects.

Constructors

• Inventory ():  The default constructor create the cargo array with the maximum allowed number of Cargo. This maximum number is a parameter defined in the Game class (Game.MAX_INVENTORY_SIZE).
   
• Inventory (int size):  This specific constructor should instantiate an array of size "size" for the "cargo" instance variable.

Accessors/Mutators

Of course, the instance variable in this class should be declared private and manipulated via accessor and mutator methods as we have discussed during lecture.  Thus, you must include an accessor and mutator method for the above field.  The name of the accessor/mutator should follow the standard Java naming conventions (i.e. getPosX(), setName(), etc.).  Note that your mutators should check for and (thus prevent) nonsense values (such as null for a setCargo). Exiting the program in this case is reasonable.

Other methods

The Inventory class should also support the following methods:

• boolean isInInventory (String type): determines if the inventory contains any cargo of type "type".  This will require searching through each object in the cargo[] array to see if the name of that cargo matches the parameter.
   
• int getNumberCargos (): the size of the data structure (the array) can be different than the number of items in the cargo (if certain "slots" in the array are empty). This returns the number of items in the cargo.  For example, if the inventory can hold 15 Cargo objects (because Game.MAX_INVENTORY_SIZE is 15), and 3 have been added, then this method returns 3.
   
• boolean add (Cargo goods): This Cargo is entered into the lowest vacant position in the Inventory.  Returns true if the addition was successful, false if not (there is no space in the inventory for it).
   
• Cargo removeCargo (int index):  This method removes all of the Cargo in position "index" of the array.  That Cargo should be returned when this method is completed.  If there is Cargo after index in the array, then those Cargos must be "shifted" down so that there are no "holes" in the array.  For example, if the cargo[] array has 5 cargos, and you remove cargo index 2, then the cargos with indices 3 and 4 should be moved down one spot each.
   
• Cargo getCargo (int index): This method just returns what Cargo is in a particular position "index", without actually removing it from Inventory (i.e., it's not destructive in the way that "removeCargo" is).
   
• String toString(): A nice way of representing the entire Inventory as a String -- it should return a String showing each Cargo in the inventory and the amount.  Note that there may be empty slots at the end of the inventory -- if so, then these should not be printed.
   
• void printInventory(): Print this Inventory to the screen.  Note that there may be empty slots at the end of the inventory -- if so, then these should not be printed.
   
• void printInventoryWithNumbers(double marketCostFactor): Print this inventory and also include the value of each Cargo in the Inventory, given the passed cost factor.  To compute the cost, call the getTotalPrice() method in Cargo.

Part III: Market class 

Now that once you have the Inventory Class, you can build the Market Class that each Location will use.

Attributes

• inventory (Inventory): Each market has a unique Inventory of goods that are available for sale.
   
• marketCostFactor (double):  Each market has a "cost factor" that defines how much any given good costs as compared to its "average" cost in all of the markets. A number greater than 1 indicates that the good costs more to buy in this market as compared to the average market, so you probably shouldn't buy goods in this market if you can avoid it. However, it makes sense for you to sell goods in a market with a cost factor > 1, so that you receive more money on average. Try to buy in markets with a cost factor of less than 1.

Constructor

• Market (double costFactor): The only constructor for the Market. In addition to setting the "costFactor", the constructor should also create a unique inventory (you will define this method, below) with the size of a parameter defined in the Game class (Game.DEFAULT_INVENTORY_SIZE).

Accessors/Mutators

As with all of our Java classes, these instance variables in this class should be declared private and manipulated via accessor and mutator methods as we have discussed during lecture.  Thus, you must include an accessor and mutator method for each of the above fields in both classes.  The name of the accessor/mutator should follow the standard Java naming conventions (i.e. getPosX(), setName(), etc.).   Note that your mutators should check for and (thus prevent) nonsense values (such as negative values -- or zero -- for the cost factor). Exiting the program in this case is reasonable.

Other methods

The Market class should also support the following methods:

• void createUniqueInventory (int size): Each Market in our game will be instantiated with a randomly-selected collection of Cargo; this method provides this functionality.  You need to create Game.DEFAULT_INVENTORY_SIZE cargos, and insert them into the inventory.  The default Cargo constructor creates a random cargo.  Note that if the cargo type is already in the inventory (via the isInInventory() method, above), then you should not add it, but try to create a new unique cargo type.
   
• void printInventory():  This method prints the Inventory associated with the Market.
   
• void printMarketCommands(): This method prints the actions that the person can do in the market: buy, sell, list what's available to buy at the market, list the person's inventory.  See the example run of the program, below.  This is just like the printLocationCommands() method in the Location class, but with different commands.  The commands to be printed are described above, and their Parser integer fields are listed in the Parser documentation.
   
• void enterMarket (Vehicle player):  After printing out a welcome banner, this method should loop until the player asks to quit the Market. During the loop, the Parser class should be used to figure out what the player wants to do (via Parser.parse()), and then this request should be performed: buy, sell, list what's available to buy at the market, list the person's inventory, or exit the market.  This method is very similar to the takeTurn() method in Location class.  Also see the example run of the program, below.  If you forget how to use the Parser.parse() method, see HW J6.
   
• void buyItem (Vehicle vehicle):  This method should first use the Parser to get which item the person wants to buy (via Parser.getItemToTrade()). After checking to see if the Market actually has the product in its Inventory, and the user has enough money to make the purchase, the particular product should be exchanged for the value of the product at the local market price.  Note that the cost of buying the cargo is determined by the getTotalPrice() method in the Cargo class.  The Cargo object that is bought should be put into the Vehicle's inventory.
   
• void sellItem (Vehicle vehicle): This method should first use the Parser to get which item the person wants to sell (also via the Parser.getItemToTrade() method). After checking to see if the user actually has the product in his/her Inventory, the particular product should be exchanged for the value of the product at the local market price.  The total sale price is determined by the getTotalPrice() method in the Cargo class.  The Cargo object that is sold should be put into the Market's inventory.

Game Simulation

Here is a sample output of your game at this point (note: We have not shown the ability to move, but your program should be able to do this).  The input that the user entered is shown in red.

Welcome to CS101 Space Trader v3!

Your Intergallactic Thunderbird is starting at Cygni (6.0,7.0).
You burn fuel at the rate of 5.0 gazonkas per million kilometers.

You are at a Cygni
You have $1,000 on hand
Valid commands are:
        travel (to travel to another location)
        market (to enter the market)
        worldmap (to print out the map)
        inventory (to show your inventory)
        quit (to leave the game)
You can abbreviate any command by its first letter
Enter next command: m

Welcome to the market at Cygni (6.0,7.0). The cost factor here is 0.89

You are at the market.  You have $1,000 on hand.
Valid commands are:
        buy (to buy cargo)
        sell (to sell cargo)
        available (to see what's available to buy)
        inventory (to show your inventory)
        exit (to exit the market and return to the location)
Enter next command: a
0: 6 units of Food at $153.335 per unit (total price in market: $920.01)
1: 1 unit of Aluminum at $14.527 per unit (total price in market: $14.527)
2: 8 units of Cloth at $21.598 per unit (total price in market: $172.787)
3: 2 units of Robots at $330.563 per unit (total price in market: $661.126)
4: 3 units of Platinum at $756.097 per unit (total price in market: $2,268.29)

You are at the market.  You have $1,000 on hand.
Valid commands are:
        buy (to buy cargo)
        sell (to sell cargo)
        available (to see what's available to buy)
        inventory (to show your inventory)
        exit (to exit the market and return to the location)
Enter next command: b
Possible items to trade:
0: 6 units of Food at $153.335 per unit (total price in market: $920.01)
1: 1 unit of Aluminum at $14.527 per unit (total price in market: $14.527)
2: 8 units of Cloth at $21.598 per unit (total price in market: $172.787)
3: 2 units of Robots at $330.563 per unit (total price in market: $661.126)
4: 3 units of Platinum at $756.097 per unit (total price in market: $2,268.29)
Which one do you want to trade? 2
It will cost $172.787 for this purchase.

You are at the market.  You have $827.213 on hand.
Valid commands are:
        buy (to buy cargo)
        sell (to sell cargo)
        available (to see what's available to buy)
        inventory (to show your inventory)
        exit (to exit the market and return to the location)
Enter next command: e

You are at a Cygni
You have $827.21 on hand
Valid commands are:
        travel (to travel to another location)
        market (to enter the market)
        worldmap (to print out the map)
        inventory (to show your inventory)
        quit (to leave the game)
You can abbreviate any command by its first letter
Enter next command: q

You ended the game with $827.21
Goodbye!

Congratulations, Space Trader!
Your Intergallactic Thunderbird traveled 0.0 million kilometers.
You still have 500.0 gazonkas of fuel available.
Take the rest of the day off, Space Trader -- you deserve it!

Testing and Submission

The Game.java file includes most of what you will need to test your classes.  It is important to confirm that the output is what you expect it to be.

The good programming practices from HW J1 need to be in this homework as well, with the exception of the test code -- you do not need to show that you tested this program.

When you are finished, submit the Inventory.java and Market.java files.