README for Tanager V5.0 This is Tanager V5.0, released 04 February 2007. Tanager is a digital music player and is a case study in Object Oriented Analysis and Design (OOAD) using iterative development practices. It is written as part of the requirements for my Master of Science degree at Iowa State University. For more information about Tanager, please see www.cs.iastate.edu/~rjlavey/Tanager 1.0 Executing Tanager from a fat jar file ========================================= 1) download the fat jar file from: www.cs.iastate.edu/~rjlavey/Tanager/Elaboration03/TanagerJava_fat.jar 2) make sure you have a JRE 1.5.0 (or later) loaded on your system (java.sun.com/javase/downloads/index_jdk5.jsp) 3) make sure you have a Java Media Framework (JMF) 2.1.1e (or later) loaded on your system (java.sun.com/products/java-media/jmf/2.1.1/download.html) 4) double-click the TanagerJava_fat.jar file 2.0 Building Tanager ==================== If you received Tanager as part of a zip file, you can build the executable from the source using Eclipse 3.2. 2.1 Prerequisites ----------------- 1) JRE 1.5.0 (or later) is installed (java.sun.com/javase/downloads/index_jdk5.jsp) 2) Eclipse 3.2 (or later) is installed (www.eclipse.org/) 3) Java Media Framework (JMF) 2.1.1e (or later) is installed (java.sun.com/products/java-media/jmf/2.1.1/download.html) 4) if you want to run the unit tests, you'll also need to make sure JUnit 4.1 (or later) is installed (junit.sourceforge.net/) 2.2 Building/Executing in Eclipse --------------------------------- 1) download the zip file from www.cs.iastate.edu/~rjlavey/Tanager/Elaboration03/TanagerJEclipseProject.zip 2) create a new, empty Eclipse project named Tanager 3) import the zip file archive into the Tanager Eclipse project 4) add included archives to the build path (right click and Add to Build Path in Eclipse) 4a) add the JavaPolygonButtons.jar file to the build path 4b) add the JUnitNonPublicHelpers.jar file to the build path 4c) add the Mp3FileAttributes.jar file to the build path 4d) add the JID3.jar file to the build path 5) execute as a java application using org.tanager.application.Tanager as the main class 3.0 User's Guide ================ Starting the Tanager player brings up a UI with 3 main sections: 1) the text area that displays the current status of the player while not in the menus, and which it also used to display the menus 2) the control button area with the menu, stop, and on/off buttons 2a) if you are not in the menus, pressing the menu button will put you into the menus; if you are in the menus (or are in a display that was accessed through the menus, such as the View Playlist display or the Download a Song display), pressing the menu button will completely exit the menus 2b) if you are in the menus, pressing the stop button has no affect if you are not in the menus and a song is playing, pressing the stop button will stop the playing song; if you are in the menus and a song is paused, pressing the stop button will cancel the paused song - after stopping, the playlist will start from the beginning the next time you play music 2c) pressing the on/off button will stop the playing song, if one is playing, and it will exit the Tanager application 3) the context-sensitive navigation button area with up, down, left, right, and middle buttons 3a) while not in the menus, the up and down buttons adjust the volume, and while in the menus they move up and down from the currently-highlights item to the one above or below 3b) while not in the menus, the left button restarts the current song or skips to the previous song if you are already at the beginning of the current song, and while in the menus, it jumps to the previous menu 3c) while not in the menus, the right button skips to the next song, and it has no effect while in the menus 3d) while not in the menus and playing a song, the middle button pauses the song; while not in the menus and not playing a song, the middle button begins playing the first song in the playlist; while not in the menus and a song is paused, the middle button restarts the paused song; while in the menus, the middle button selects the highlighted item Tanager can be powered off by pressing the On/Off button. A song can be downloaded to Tanager by pressing the menu button and then selecting "Download a Song" from the displayed menu. A downloaded song can be deleted from Tanager by pressing the menu button and then selecting "Delete a Song" from the displayed menu. The current playlist can be viewed by pressing the menu button and then selecting "View Playlist" from the displayed menu. A song can be played by pressing the play button. A song can be stopped by pressing the stop button. A song can be paused by pressing the pause button. The volume can be adjusted by pressing the up and down buttons while not in the menus. A paused song can be restarted by pressing the play button. A paused song can be stopped by pressing the stop button. 4.0 Troubleshooting =================== 1) If you hang with the Initializing message at power on, it's likely that you have an incompatible version of the TanagerSongCollection file in your working directory. Try exiting the Tanager player, deleting the TanagerSongCollection file, and power on again. 2) If you download a song and try to play it but nothing happens, make sure you have JMF 2.1.1.e installed. There is very little error handling code in this early version, and if the system is unable to play the song, the state machine will hang waiting for the song to begin. The play icon will be removed from the middle button, but the pause button will not be displayed in this case. 5.0 Version History =================== Version 5.0 - Elaboration Phase 4 --------------------------------- o The fat jar for this version of Tanager can be found at www.cs.iastate.edu/~rjlavey/Tanager/Elaboration04/TanagerJava_fat.jar o Implemented Select Playlist Type use case. o Implementde Restart Current Song use case. o Implemented Skip To Next Song use case. o Implemented Skip to Previous Song use case. o Implemented Save System State use case. o Implemented alternate scenarios for Power On use case (using saved system state) o Refactored UI button handling. I originally implemented this with the CButtonPane handling the buttons for the default screen (the CDisplayPane's textArea_), but I found a defect where pressing the left button while in the menus and playing a song caused the menus to be exited and the song to be restarted. Clearly I needed to have a way to remove the button handlers for the default screen while the menus were being displayed. It also became apparent that the textArea_ attribute in CDisplayPane needed to be its own object (handling its own buttons). Version 4.0 - Elaboration Phase 3 --------------------------------- o The fat jar for this version of Tanager can be found at www.cs.iastate.edu/~rjlavey/Tanager/Elaboration03/TanagerJava_fat.jar o Implemented Stop Music use case. o Implemented View Playlist use case. o Implemented Delete a Song use case. o Implemented Volume Adjustments use case. o Refactored menu system. This had been part of the Download a Song use case, but it needs to be a standalone use case, Enter and Exit Menus. I had implemented this in a very simple way using a JPopup, but user feedback told me that it would be better if the menus were displayed in the main display screen of the Tanager UI. o Refactored state machine handling. I originally implemented this as simple switch/case statements in those methods that required state handling, but the complexity of the state machine has grown, and using the State Pattern is a better solution for non-trivial state machines. o Added ability to save/retreive the last known downloaded song's path, so it's easier to download multiple songs. Version 3.0 - Elaboration Phase 2 --------------------------------- o The fat jar for this version of Tanager can be found at www.cs.iastate.edu/~rjlavey/Tanager/Elaboration02/TanagerJava_fat.jar o Implemented alternate use case for Download a Song, invalid audio file selected. o Implemented a basic scenario for the Play Music use case: play music when system is not paused. o Implemented alternate scenario for the Play Music use case: play music when system is paused. o Implemented a basic scenario for the Pause Music use case: pause music when music is playing. Version 2.0 - Elaboration Phase 1 --------------------------------- o The fat jar for this version of Tanager can be found at www.cs.iastate.edu/~rjlavey/Tanager/Elaboration01/TanagerJava_fat.jar o Implemented a basic scenario for the Power On use case: power on to default state. No checking for saved system state is done. o Implemented a basic scenario for the Power Off use case: system state is not saved. o Implemented a basic scenario for the Download A Song use case: download a song with no error checking. No checking for existence of music file is done.