10.2. Designing the Interface

At this point, Tim and I were not sure how we were going to obtain the data for the catalog. Sam had mentioned a couple of Internet sites where it might be available. I figured a CD-ROM or two probably was available with the data. After all, a CD-ROM with equivalent information exists for books. At worst, we might put his staff to work when they had nothing else to do. They could input the information from the CD cases.

How we were going to implement the catalog was irrelevant at that point. What we needed was the search interface. Based on the use cases given in the previous section, we came up with a rough class outline that looked like this:

 class Song         CommonString the_title     class CD         UPCCode the_upc_code         CommonString the_title         Performer [] the_performers         Song [] the_songs         // Other Info to display (e.g. producer).     class Performer         Name the_name 

Based on these classes, we developed the following interface. The return values are shown as groups (arrays). They could become collections if we started to add functionality to the groups (such as sort by producer).

 interface CDCatalog         Song [] search_for_song_by_title(CommonString string_to_match)         CD []  retrieve_cds_for_song(Song a_song)  // From the song list         Performer [] search_for_performers_by_name(CommonString string_to_match)         CD [] retrieve_cds_for_a_performer(Performer a_performer)              // From performer list         CD [] search_for_cds_by_name(CommonString string_to_match) 

10.2.1. What's a CD?

Now, what about the term CD ? In the initial system design, we created CDDisc and CDRelease to distinguish clearly between those two concepts. Should this interface return arrays of CDRelease s? Well, maybe.

The CD information retrieved from this catalog is not the same as the CDRelease in Sam's system. The CDRelease that Sam and I created contains just a UPCCode and a title, whereas the CD class additionally contains a performer list, a song list, and other information such as the producer. There is not a one-to-one correlation between CDs and CDRelease s. CDRelease objects exist only for CDDisc s that Sam owns (or perhaps owned previously). However, CDs that are retrieved from the catalog can correspond to CDDisc s that Sam has never owned. Thus, the CD here is not a CDRelease . The two are separate concepts with separate purposes. It is easier to split them at this point and lump them later if we find we really are using these two classes in the same way.

Sam and I already agreed that CD is a nebulous term. So Tim and I needed to come up with another name for the CD class in the preceding example. If Sam thinks it is incorrect, a global search and replace can change it easily. We termed the concept CDCatalogItem . This is a little wordy, but certainly distinctive and easily searchable. The interface becomes:

 class CDCatalogItem         CommonString the_title         UPCCode theupc_code         Song [] the_songs         Performer [] the_performers     interface CDCatalogItemCollection         Song [] search_for_song_by_title(CommonString string_to_match)         CDCatalogItem [] retrieve_cd_catalog_items_for_song(Song a_song)             // From the song list         Performer [] search_for_performers_by_name(CommonString string_to_match)         CDCatalogItem [] retrieve_cd_catalog_items_for_a_performer(             Performer a_performer) // From performer list         CDCatalogItem [] search_for_cd_catalog_items_by_title(             CommonString string_to_match) 

10.2.2. A Little Premature Worry

A performance- concerned developer might worry about the performance of this interface. CDCatalogItem [] contains the matching CDCatalogItem s. Each item in the list contains a good deal of information. The search system could take a big performance hit if CDCatalogItem [] returns a lot of matching items. In many cases, Tim and I believe, most of the information in each CDCatalogItem will never be viewed .

We could make CDCatalogItem do a lazy fill-in of its data (a lazy lookup ). When an item on the list is created, the object will fill in only its identifier and the title. When the information on an item is actually requested , the object will go back to the catalog and read in the rest of the details.

Alternatively, the performance-concerned developer might change the interface. An additional class could be added that contains only the minimal information required for a display of matching CDCatalogItem s (e.g., title). For example, we could create the CDCatalogItemInfo class:

 class  CDCatalogItemInfo         Identifier the_identifier         CommonString the_title     interface CDCatalogItemCollection          Song [] search_for_song_by_title(CommonString string_to_match)         CDCatalogItemInfo [] retrieve_cd_catalog_items_for_song (Song a_song)             // From the song list         Performer [] search_for_performers_by_name(CommonString string_to_match)         CDCatalogItemInfo [] retrieve_cd_catalog_items_for_a_performer(             Performer a_performer)             // From performer list         CDCatalogItemInfo [] search_for_cd_catalog_items_by_title (             CommonString string_to_match)         CDCatalogItem retrieve_item_for_cd_catalog_item_info (             CDCatalogItemInfo cd_info) 

An implementation of this interface will probably run faster than the previous one that does not use lazy lookup. Should we worry about performance at this time? For now, we could write down our concern, and the possible solutions, in our design journal ("Don't Speed Until You Know Where You Are Going"). Then we could code the first implementation, without the lazy lookup. When we test that implementation of the interface, we will see the actual performance. If it is too slow, we can implement lazy lookup for CDCatalogItem . If it is still too slow, we can try the CDCatalogItemInfo approach.