Purpose: Practice the use of collections and learn about the Java standard libraries. This is a Pairs Programming project.
Problem: You have to implement a simple software jukebox, starting from hand-out code provided with the assignment. This section specifies what the completed jukebox implementation will be capable of. Exactly what you have to finish and turn in is described in greater detail below.
Jukebox functionality: The jukebox manages a collection of audio records, organized into play lists. Jukebox users can search through the play lists to create a new, temporary, active play list. The jukebox can then be told to play the new play list. (The play function is only simulated -- no actual audio in this project). Once the play list has been played another list can be created and played, etc.
Play lists: Each play list has a name, a description and a collection of tracks. Play lists can be combined. Play lists also have search functionality. Optionally, you can implement duplicate track elimination within a play list.
Tracks: Each track has a title, the artist name, and the playing time (or track length). Optionally, if you want to do duplicate track elimination within play lists then you should also implement track comparison.
Play list files: The jukebox reads play lists from text files (like this example). The jukebox reads the text, uses it to create play list objects, and adds the play list object to its internal play list collection. The playlist files can be specified with an absolute path on your hard drive, or with a URL to a file on a web site. If only the filename is given, the file can be in directory you start DrJava in, on the root of your C: drive, in a directory on Java's classpath, or near one of those locations.
Format of the playlist files: Each play list is stored in a single file. The first line specifies the play list name and description, in that order. Subsequent lines specify the tracks in the play list. The track lines start with the track name, then comes the artist name and finally the track length in seconds. Read comments in the ReadPlayList.java for more information.
Jukebox searching: The jukebox can do three (optionally four) kinds of searches, for substrings of (1) artist names, (2) track names, (3) any of the above, and optionally (4) sequences of any of the above. Jukebox searches are run on every play list in the box. The result of any search is a new play list.
Play list searching: Play lists can search through their collection of tracks. Jukebox searches simply invoke play list search on each play list in the jukebox collection.
Playing: The jukebox has a media player component but not one that can actually play music. Instead the player simply prints track information. This makes writing and testing the jukebox much easier. The interaction between the jukebox and player is as follows. First the jukebox tells the player to play a play list. Then the player takes over and prints the track information of each track. When the player is done it returns and the jukebox takes control again.
Examples:
You can search the jukebox collection of play lists for all tracks with artist names containing the string "eatle", or the string "olling Stone".
Similarly you could try searching for all tracks with track names containing the string "walrus" or the string "eggman".
In both cases you get back a single new play list containing all the tracks that were found. If you search artist names for the substring "olling Stone", you get all tracks by the Rolling Stones, as well as the Scrolling Stonemen.
For fun: To do a disjunctive ("or") search you can search twice and combine the two play lists.
For fun: To do a conjunctive ("and") search you can search and then run another search on the results of the first.
Source code:
We’re providing you with starter code in the files JukeBox.java, PlayList.java, and Track.java. There is completed code in MediaPlayer.java and PlayListReader.java that your program should use but which you should not modify (please report suspected bugs!). Your task will be to complete the implementation of classes JukeBox, PlayList and Track, including both state (instance variables) and behavior (methods), as described below.
Turn-in and due date: Please read and follow the turn-in instructions carefully. There are two separate turn-in dates for this assignment. The source code files only need to be turned in once per pair (or three person group). Each group member must turn in the report in part 3 individually.
Part 1 has electronic turn-in, using a
web turn-in form, with a due date of Wednesday 7 at
Part 2 has electronic turn-in only, using another web turn-in form. The due date is Tuesday May 13 at 9 pm.
Part 3 requires turning in a paper copy of your report. The due date is Wednesday May 14 at the beginning of lecture.
You are not required to print the receipts for electronic turn-in. However, if you would like your TA to give you written feedback (as opposed to just a score) then you're free to turn in the receipt. In that case the printed and stapled receipt should be turned in at the beginning of lecture on Wednesday May 14.
Time: It is difficult to estimate how much time a given individual will need to spend to complete the project. If you plan well and have a good understanding of the programming concepts, you might spend at least 4-6 hours on it, spread out over the full 11 days you have to complete the assignment. Start today!
Purpose: Get familiar with the project, learn to create and populate Java collections, experiment with reading playlist files, create a text file with a play list for you and others to search through in part 2.
Procedure:
Using the sample play list file as a template, create an original play list text file containing at least 10 tracks and turn it in. Be careful to ensure that your play list matches the format of the original, otherwise it will be useless in part two. You can create .txt files using WordPad, NotePad, or DrJava (or any java IDE). Avoid Word or other word-procesing programs unless you know how to convert the result into text format. Turned-in play lists will be shared with the whole class after the Part 1 deadline has passed. To facilitate this, give your file a name that contains the string "play", but is otherwise a unique name, something that other teams are unlikely to think of. The extension of a text file is typically .txt, but you can use any reasonable extension.
As soon as possible, experiment in DrJava (in the Interactions Pane) with the PlayListReader class. By typing only a few simple lines, you should be able to read in a playlist file and display the resulting ArrayList which it produces. Try this with the sample playlists you are given, and with your own playlist(s). (You do NOT need to modify any java classes to do this!). Capture a screen snapshot of this and turn it in (see below).
Fully implement the class Track.java. The toString should return a string will all the information about the track, in a nice compact but readable form (for example, something like "Beatles - I Am The Walrus - 4:35").
Partially implement PlayList.java. In particular, you should implement at least the constructor and the addTrack method; other methods can be left until later.
If you want to jump start part 2, a good place to continue is PlayList.toString.
Before continuing to Part 2, think through the work that remains to be done. Identify any questions you have about what the requirements of the assignment are. Note especially any ambiguities or uncertainties that might prevent you from continuing to make progress. Write these up in a short written report, one per team. If you have no questions about the project, then your report can simply say "no questions". Call this your "issues report".
Turn-in: Turn in playlist.txt, Track.java and PlayList.java using the part 1 web turn-in form. Also, in DrJava, read in and display your playlist file (see step 2 above). While you have it showing on the screen, do a screen snapshot (don't stress if your file is so long that only part of it shows on the screen). Capture the snapshot, print it, write your names and section on it, and turn it in. The electronic due date is Wednesday May 7 at 9 pm; bring printed receipts and snapshots to quiz section on Thursday, along with the Issues Report. One electronic turn-in per team; one hardcopy per team; make sure both partners' names are on everything.
Hints:
DO NOT CHANGE PlayListReader.java OR MediaPlayer.java (OR JukeBox.java, until Part 2).
Read all the comments in Track.java and PlayList.java.
To compile PlayListReader.java, your IDE must have the Java 1.4 assert statement enabled. In DrJava, you find this option via Edit/Preferences/Miscellaneous.
A note on pathnames: Windows uses the backslash character as a file separator, as is C:\testfile.txt. In Java, \ is the escape character, so if you want to use it in a String, you must escape it (with itself!), as in "C:\\testfile.txt".
All the collections in parts 1 and 2 should be implemented using the class java.util.ArrayList.
Documentation on java.util. ArrayList is available here. In fact, documentation on all the standard Java library classes is available there - click around and see what you come up with. Don't worry if it seems like a lot of complicated stuff, you only have to make sense of a couple of library classes to finish the assignment.
Java standard library classes have to be imported before you can use them, with the single exception of the classes in the java.lang package; see textbook and lecture notes for details. Probably the only imports you will need in this project are java.util.ArrayList and (for Part 2) java.util.Iterator.
Purpose: Learn to iterate and search through collections, work more with standard Java library classes.
Procedure: Finish implementing the PlayList class and also implement the JukeBox class.
Implement PlayList.toString. This is for debugging, but you might try making the returned string look exactly like the contents of the play list files. You need to learn to iterate through ArrayLists to do this.
Fix JukeBox.loadPlayListFromFile so that it works with your PlayList and Track classes. Then you can read play lists from files. Use PlayList.toString to debug while you work on JukeBox.loadPlayListFromFile.
Implement the search methods in the PlayList class. Again use PlayList.toString to debug the search results.
Implement PlayList.combinePlayList, which adds all the tracks in a parameter play list to the track collection of the current instance.
Implement the search methods in the JukeBox. This just takes a simple loop that repeatedly calls the play list search methods, and combines the resulting play lists. In other words, make sure you get play list search and combine right before you do this.
Implement JukeBox.addPlayListToRequestQueue and JukeBox.play, and you're done with the programming!
In DrJava, execute some steps in the Interactions Pane to demonstrate your code at work. Take a screen snapshot. In particular, your snapshot should show a partial-match query and its result. Print the snapshot to hand in.
Note that although we're not asking you to turn in a test harness, it's a good practice to make one anyway. In fact you'll probably finish coding the homework solution faster if you make a simple test harness with methods that create a play list object, search play lists, run the jukebox, etc.
Turn-in: Turn in Track.java, PlayList.java and JukeBox.java using the part 2 web turn-in form. The due date is Tuesday May 13 at 9 pm. Turn in any paperwork, including the snapshot, in lecture on the following day.
Hints:
DO NOT CHANGE PlayListReader.java OR MediaPlayer.java.
The code has hints and comments. Be sure you understand all of them before changing anything.
The JukeBox.loadPlayListFromFile should not be a lot of work! Just fix the places where your PlayList and Track classes don't match the provided code. The jukebox reads play lists from text files (like this example). (Earlier in the instructions you can find information about where to place files so they can be found, and how to create such files).
For full credit, the search methods should find partial matches, as mentioned earlier; for example, searching for artist "oon" would match a track by "Artis the Spoonman". This is a bit tricky, and will require you to figure out some stuff about strings that will not be covered in lecture! Some hints follow. You should first get exact matching to work perfectly, and only then work on the fancier stuff.
The java.lang.String.equals method implements exact string comparison - this helps in searching.
The java.lang.String.indexOf method returns the index of a substring, which is useful for approximate string comparison.
The java.lang.String.substr method may also come in handy, depending on what you decide to do.
You can find documentation on String methods here.
If str1 = "Martin Dickey", then str1.indexOf("tin") will return the value 3, indicating the "tin" starts at the 3rd (counting from 0) character in the string. This will come in handy when searching for incomplete artist names (like "olling Stone").
PlayList.combinePlayList just requires one loop that iterates through the parameter collection and adds the tracks to the current play list.
When you combine play lists, the parameter play list should not be changed. More detailed comments are in the hand-out code.
3 – Pair Programming Report
The third part of this assignment is to write and turn in an individual pair programming report. Your report may not be longer than one page. It should summarize your experience working on homework 4 with your partner. You should indicate your involvement and contribution in the whole design and implementation process, and the amount of time spent individually and together on the homework. This report should be different for each person and you shouldn't work as a team to prepare your reports. Please turn in a paper copy of the report. The due date is Wednesday May 14 at the beginning of lecture.
4 – Special Note: Service and Participation Point
The text files turned in with Part 1 will be made available for all teams to use for testing. This constitutes a service to your classmates, and one service point will be given to everyone who turns in an acceptable file. "Acceptable" means that it has non-trivial data, has no errors in format, and is named properly. (We might give an additional point to a few teams whose files are particularly noteworthy). If for some reason you do not want your file shared with the class, please inform the instructors. You will not earn the service point, but it will not affect your Homework #4 score.