Music Example

In this example we describe a music player as if we were operating it. We will see two kinds of tables in use, action and row. The action tables list things actions to be performed, step-by-step, one row at a time. Some actions will involve searching for music. We will check to be sure we've found the right music using a second kind of table, a row table. In the row table we will simply list each song, one per row, with columns showing different attributes of each song. We'll use these fixtures.

We'll write the remainder of this page as if it were describing stories for the music library/player. We'll use italics when we want to point out features of the framework. You might as well run the example now before you continue reading.

This is our most realistic example short of the SampleApplications. See the MusicExampleObjectModel to understand all of the objects in play here.

Browsing Music

The music browser starts up looking at the whole library of songs. We specify the library (an advanced feature) so that we know what we are talking about in this document.

enter library Music.txt
check total songs 37

This is a the file that library reads. It is tab separated text. Try downloading it and looking at it with a spreadsheet. http:Release/Source/eg/music/Music.txt

We can pick songs and see details of our selection as we go.

enter select 1
check title Akila
check artist Toure Kunda
enter select 2
check title American Tango
check artist Weather Report
check album Mysterious Traveller
check year 1974
check time 3.70
check track 2 of 7

ActionFixture interprets the words in the first column. The actions operate on fields and buttons on the Browser screen we started in the first table. The Browser (or what ever other Fixtures we start) interprets the names in the second column. Each name maps to a method of the Browser. The third column provides data that are pass as arguments to Browser methods or compared with Browser method results. See MusicExampleWithErrors to see how errors are reported.

Playing Music

Once we've picked a song, we can play it. We can continue operating the Brower while music is playing. Since this sequence is long, we'll explain what we are doing in an unused column. time split
press play   play this song 10000 1
check status loading   10001 0
pause 2    10001 2
check status loading watch it load 10003 0
pause 2    10003 2
check status playing   10005 0
check playing American Tango   10005 0
check time 3.70   10005 0
press pause   make it stop 10005 1
check status pause   10006 0
check remaining 3.66 expected
3.67 actual
  10006 0
pause 60    10006 60
check remaining 3.66 expected
3.67 actual
  10066 0
press play   make it go 10066 1
check status playing   10067 0
pause 60    10067 60
check remaining 2.66 expected
2.67 actual
  10127 0
await play complete   enjoy the music 10127 160
check status ready   10287 0
enter select 4 try another 10287 1
press play    10288 1
pause 1    10289 1
fail load jam   uh oh 10290 0
check message load jamed   10290 0
press ok   dispatch the notifier 10290 1
check status ready   10291 0

This table is interpreted by Realtime, a Fixture that adds actions having to do with realtime operation of the music player. This fixture calls on a simulator to keep track of system events. We do so here only because the application we are testing isn't a real music player. Our toy application cooperates with the simulator to keep track of time. A real player would do things that take real time and it would use the computer's realtime clock to keep track of time. We could still use a fixture with actions like pause and await but there wouldn't need to be a simulator too.

Searching for Music

There are buttons on the browser to find more songs like the one we have picked. time split
enter select 2 pick an album 10291 1
press same album   find more like it 10292 1
check status searching   10293 0
await search complete    10293 1
check status ready   10294 0
check selected songs 2   10294 0

Our searches take a few seconds to complete. Eventually we will want to try mashing buttons faster than the computer can respond. For now we will be polite and await completion of our searches.

The selected songs are displayed in a table.
title artist album year time() track()
Scarlet Woman Weather Report Mysterious Traveller 1974 5.72 6 of 7
American Tango Weather Report Mysterious Traveller 1974 3.70 2 of 7

Here we use Display (a RowFixture) to directly examine the Music object found by our search. Things like artist and track() are fields and methods of the domain objects.

We can find songs related in different ways. Each new way produces a (possibly) different list of songs. Show all restores the display to the initial conditions. time split
press show all   recall all the songs 10294 1
await search complete    10295 3
check selected songs 37   10298 0
enter select 3 pick a James Taylor song 10298 1
check artist James Taylor   10299 0
press same artist   find more by him 10299 1
await search complete    10300 2
check selected songs 5   10302 0

Yielding the display:
title artist album year time() track()
Handy Man James Taylor JT 1977 3.30 7 of 12
Sailing To Philadelphia James Taylor October Rose 2001 5.47 3 of 3
Ananas James Taylor Hourglass 1997 5.73 5 of 13
Another Grey Morning James Taylor JT 1977 2.73 4 of 12
Copperline James Taylor New Moon Shine 1991 4.37 1 of 12

Domain objects typically have lots more fields and methods than we can conveniently look at in a single table. We compose a table specific to our needs by choosing column headings of interest. Here is another look at the results of the previous search.
title album genre size date
Another Grey Morning JT Pop 3284199 9/7/02 11:32 PM
Ananas Hourglass Pop 6897450 9/7/02 11:47 PM
Copperline New Moon Shine Pop 5248087 9/7/02 9:52 PM
Handy Man JT Pop 3976956 9/7/02 11:36 PM
Sailing To Philadelphia October Rose Pop 6581911 9/7/02 10:45 PM

Notice that the songs in the two tables are not in the same order. That is because we didn't type the tables in the same order, and the order we type is preserved. RowFixture(s) use the left hand columns to line up the search results with the table values. Check out MusicExampleWithErrors to see how this works when the rows don't match up.

The kaffe jvm/library has trouble with date formatting so you may see errors when running this from wiki.

This completes the MusicExample.

We've run quite a few test. We'll call up one more Fixture that will add a summary to the end of our document.

counts 92 right, 3 wrong, 0 ignores, 0 exceptions
run date Fri Oct 25 20:56:14 2002


Last edited October 11, 2002
Return to WelcomeVisitors