External Interfaces/API

Description of Function phonebook

The major tasks performed by phonebook are:

1. Determine the Data Directory and Full Filename

The first statement assigns the phone book filename, 'myphonebook', to the variable pbname. If the phonebook program is running on a PC, it calls the java.lang.System static method getProperty to find the directory to use for the data dictionary. This will be set to the user's current working directory. Otherwise, it uses MATLAB function getenv to determine the directory, using the system variable HOME which you can define beforehand to anything you like. It then assigns to pbname the full pathname, consisting of the data directory and filename 'myphonebook'.

• function phonebook(varargin)
  pbname = 'myphonebook'; % name of data dictionary
  if ispc
     datadir = char(java.lang.System.getProperty('user.dir'));
  else
     datadir = getenv('HOME');
  end;
  pbname = fullfile(datadir, pbname);
  

2. If Needed, Create a File Output Stream

If the phonebook file does not already exist, phonebook asks the user whether to create a new one. If the user answers y, phonebook creates a new phone book by constructing a FileOutputStream object. In the try clause of a try-catch block, the argument pbname passed to the FileOutputStream constructor is the full name of the file that the constructor creates and opens. The next statement closes the file by calling close on the FileOutputStream object FOS. If the output stream constructor fails, the catch statement prints a message and terminates the program.

• if ~exist(pbname)
     disp(sprintf('Data file %s does not exist.', pbname));
     r = input('Create a new phone book (y/n)?','s');
     if r == 'y',
        try
           FOS = java.io.FileOutputStream(pbname);
           FOS.close
        catch
           error(sprintf('Failed to create %s', pbname));
        end;
     else
        return; 
     end;
  end;
  

3. Create a Hash Table

The example constructs a java.util.Properties object to serve as the hash table for the data dictionary.

• pb_htable = java.util.Properties;
  

4. Create a File Input Stream

In a try block, the example invokes a FileInputStream constructor with the name of the phone book file, assigning the object to FIS. If the call fails, the catch statement displays an error message and terminates the program.

• try
     FIS = java.io.FileInputStream(pbname);
  catch
     error(sprintf('Failed to open %s for reading.', pbname));
  end;
  

5. Load the Phone Book Keys and Close the File Input Stream

The example calls load on the FileInputStream object FIS, to load the phone book keys and their values (if any) into the hash table. It then closes the file input stream.

• pb_htable.load(FIS);
  FIS.close;
  

6. Display the Action Menu and Get the User's Selection

Within a while loop, several disp statements display a menu of actions that the user can perform on the phone book. Then, an input statement requests the user's typed selection.

• while 1
     disp ' '
     disp ' Phonebook Menu:'
     disp ' '
     disp ' 1. Look up a phone number'
     disp ' 2. Add an entry to the phone book'
     disp ' 3. Remove an entry from the phone book'
     disp ' 4. Change the contents of an entry in the phone book'
     disp ' 5. Display entire contents of the phone book'
     disp ' 6. Exit this program'
     disp ' '
     s = input('Please type the number for a menu selection: ','s');
  

7. Invoke the Function to Perform A Phone Book Action

Still within the while loop, a switch statement provides a case to handle each user selection. Each of the first five cases invokes the function to perform a phone book action.

Case 1 prompts for a name that is a key to an entry. It calls isempty to determine whether the user has entered a name. If a name has not been entered, it calls disp to display an error message. If a name has been input, it passes it to pb_lookup. The pb_lookup routine looks up the entry and, if it finds it, displays the entry contents.

• switch s
     case '1',
        name = input('Enter the name to look up: ','s');
        if isempty(name)
           disp 'No name entered'
        else
           pb_lookup(pb_htable, name);
        end;
  

Case 2 calls pb_add, which prompts the user for a new entry and then adds it to the phone book.

•    case '2',
        pb_add(pb_htable);
  

Case 3 uses input to prompt for the name of an entry to remove. If a name has not been entered, it calls disp to display an error message. If a name has been input, it passes it to pb_remove.

•    case '3',
        name=input('Enter the name of the entry to remove: ', 's');
        if isempty(name)
           disp 'No name entered'
        else
           pb_remove(pb_htable, name);
        end;
  

Case 4 uses input to prompt for the name of an entry to change. If a name has not been entered, it calls disp to display an error message. If a name has been input, it passes it to pb_change.

•    case '4',
        name=input('Enter the name of the entry to change: ', 's');
        if isempty(name)
           disp 'No name entered'
        else
           pb_change(pb_htable, name);
        end;
  

Case 5 calls pb_listall to display all entries.

•    case '5',
        pb_listall(pb_htable);
  

8. Exit by Creating an Output Stream and Saving the Phone Book

If the user has selected case 6 to exit the program, a try statement calls the constructor for a FileOuputStream object, passing it the name of the phone book. If the constructor fails, the catch statement displays an error message.

If the object is created, the next statement saves the phone book data by calling save on the Properties object pb_htable, passing the FileOutputStream object FOS and a descriptive header string. It then calls close on the FileOutputStream object, and returns.

•    case '6',
        try
           FOS = java.io.FileOutputStream(pbname);
        catch
           error(sprintf('Failed to open %s for writing.',...
                           pbname));
        end;
        pb_htable.save(FOS,'Data file for phonebook program');
        FOS.close;
        return;
     otherwise
        disp 'That selection is not on the menu.'
     end;
  end;
  

Example - Creating and Using a Phone Book

Description of Function pb_lookup