Assignment #5 -- Designing a card deck class

Due: Mon, April 2

Objective

To practice with class design in Java, using good design principles as discussed in class. Also to gain further practice with Java compilation and execution of programs.

Task

You are to design and implement, in Java, a CardDeck class. The intent is to create a class that is versatile enough to be a re-usable module in the implementation of a variety of card games. You will create and your own design and interface, keeping with good class design principles.

Details

General class requirements
- Create a class called CardDeck, in the file CardDeck.java
- Create a class called Card, to represent a single card. You'll need this because some CardDeck methods may need to return one or more cards to the caller
- You may create other classes if you like, to be used by CardDeck. Make sure any other classes are well-documented
- Even if you create other classes, remember that the primary focus of this task is to build a card deck module (not a full program based on any specific card game).
Desired features of the Card class
Your Card class should provide at least the following features, for easy use and testability
- The ability to retrieve a card's suit or value (i.e. to the caller, not printout)
- If the caller wants to print a card, like this:
```
System.out.print(c1);  // where c1 is a Card
```
  it should be as a string in the format Vs, where V represents the value (in uppercase if a letter), and s represents the suit, in lowercase. (The one exception to this would be a Joker, which should be printed like this for easy identification: J* )
  Examples: Kh , Ad , 2s , 8c (King of hearts, Ace of diamonds, 2 of spades, 8 of clubs)
Desired features of the card deck
Your CardDeck class should provide at least the following features as part of its interface
- The ability to create a standard deck of American cards (52 cards)
- The ability to create a standard deck with 2 Jokers included (54 total cards)
- The ability to create a "deck" that consists of multiple standard decks of cards. For example:
  - Some solitaire games are played with 2 decks (104 cards) or even 4 decks (208 cards)
  - A Blackjack "shoe" might consist of many standard decks all shuffled together. A shoe of 10 decks would yield a large deck of 520 cards, for instance
- Ability to create a "deck" out of multiple decks with Jokers included
- The ability to shuffle the entire deck (however big). Shuffling should provide sufficient randomization of the cards so that their values are not predictable
- The ability to re-shuffle just a portion of a deck
  - Example: The solitaire game Gaps would use this feature, for example.
  - Gaps is just an example. The feature should be general, not specific to this one game
- The ability to "deal" a card from the deck. This feature should send one card back to the calling application
- The ability to "deal" multiple cards from the deck at once. This feature should send back multiple cards to the calling application
  - Draw Poker would use this feature, for instance, when allowing a player to discard and draw a few new cards for their hand
- The "dealing" features should work such that any call to a dealing function retrieves cards that have not yet been dealt. (A shuffle would reset this tracking to some original state)
- If the caller wants to print the whole deck for testing purposes, like this:
```
System.out.print(d1);   // where d1 is a CardDeck
```
  then it should print out all the individual cards, in their current order, in a readable format
- The ability to retrieve a count of how many cards are in the deck, total (i.e. before any dealing occurred). This value actually should not change once a deck is built
- The ability to retrieve a count of how many cards in the deck have not yet been "dealt" (since the last shuffle).
- Any other features that you believe would be useful to provide for a deck of cards.
  - Remember, CardDeck features should NOT be implementing any rules specific to one game (such as calculating Poker hand strengths) -- but should anticipate needs and provide desired features for standard operations on decks of cards. These features can be used by specific card game implementations
Documentation
- Each method or member variable you create should have a comment block before it, in this format, with how many ever lines are needed:
```
     /**  Comments go here
      *   and here
      *   and here (etc)
      */
```
  Make sure that the first line starts with the slash and two asterisks.
- Each comment block should describe the purpose of the variable or method
- Your comments on member data variables should specify any class invariants
- Your comments on methods should specify any important pre-conditions that the user must satisfy, and any post-conditions that the method will guarantee
- Write your invariants, pre-conditions, and post-conditions as briefly as possible. Where possible, use simple Boolean expressions to specify them
Remember to use good design principles
Your class will be judged partly on use of good design principles, including:
- Quality of interface: cohesion, completeness, convenience, clarity, consistency
- Following good encapsulation principles (private data, public methods, Law of Demeter)
- Clear accessors and mutators, where appropriate
- Avoiding unintended side effects. (i.e. there shouldn't be anything that takes the user by surprise!)
- Good documentation of contracts (invariants, preconditions, postconditions)
Demonstration of Class Features
Write at least one test program that demonstrates class features.
- You may write more than one "main" test program if you like.
- Some hard-coded test cases are fine, but you should include some mechanism for interactive testing, as well
  - Suggestion: One test program with hard-coded calls. One allowing interactive testing
- Some example of good interactive testing in a driver test program
  - Allow a user (from standard input) to enter what type of deck to create
  - Allow a user to choose different deck options -- like shuffling, printing the deck contents, dealing a card (or cards) and seeing what was dealt, or retrieving the value or suit of a dealt card
  - Menu driver programs are good for this kind of thing. Allowing the user to call upon different features, in the order of their choosing
- Create a "README" file (text format is fine) that explains your test program(s). Specifically, make it clear to your reader (i.e. your instructor/grader) how your test routines can be used to thoroughly demonstrate your class features, including any erroneous uses (like the caller violating a precondition) and the responses by your class. You are welcome to include any other explanatory material in your README that helps document your design

Submitting

Remember to compile and test Java code on either program.cs.fsu.edu or linprog.cs.fsu.edu.

To prepare your submission, bundle all of your files (code files, README) into a single "jar" archive called "hw5.jar". Format:

  jar cvf hw5.jar

For example, if all of the files to bundle are in one directory (and nothing else), you can pack it up with this:

  jar cfv hw5.jar *		  // packs all files in the current directory

  jar cfv hw5.jar *.java README   // or use this one, for code files and README

E-mail this jar file (hw5.jar) to me (myers@cs.fsu.edu) by the due date. Your e-mail subject should be HW5-SUBMIT. Include your name and section in the e-mail body. Please only submit ONCE, unless you make a mistake and need to correct it (before the due date) -- and minimize this. Only the last submission will be graded.

Your submission e-mail needs to come either from your CS account (preferred) or your garnet/mailer account.