001    package edu.harvard.deas.hyperenc;
002    
003    import java.util.Iterator;
004    
005    import javax.mail.Address;
006    
007    /**
008     * A list of Contacts. Implements a subset of the List interface, and an
009     * additional method, <code>getContact</code>, that finds the Contact in the
010     * list with the given e-mail address.
011     */
012    public abstract class ContactList implements Iterable<Contact> {
013      /** Default constructor */
014      protected ContactList() {}
015      
016      /**
017       * Appends <code>c</code> to the list.
018       * @param c the contact to be added
019       */
020      public abstract void addContact(Contact c);
021      
022      /**
023       * Removes <code>c</code> from the list.
024       * @param c the contact to be removed
025       */
026      public abstract void removeContact(Contact c);
027    
028      /**
029       * Returns the contact at index <code>index</code> in the list.
030       * 
031       * @param index
032       *        an integer index between 0 and <code>this.size() - 1</code>
033       * @return the contact at the specified index
034       * @throws IndexOutOfBoundsException
035       *         if the value of <code>index</code> is illegal
036       */
037      public abstract Contact get(int index) throws IndexOutOfBoundsException;
038    
039      /**
040       * Returns an Iterator over the Contacts in this list. The Iterator returns
041       * Contacts in the order in which they appear in this list, that is, starting
042       * from index 0 and going in increasing order.
043       */
044      @Override
045      public abstract Iterator<Contact> iterator();
046      
047      /**
048       * Returns the number of contacts in the list.
049       * @return the size of this list
050       */
051      public abstract int size();
052      
053      /**
054       * Returns whether this list is empty.
055       * @return <code>true</code> iff the size of this list is 0
056       */
057      public boolean isEmpty() {
058        return size() == 0;
059      }
060      
061      /**
062       * Returns the Contact in this list with e-mail address <code>a</code>.
063       * @param a e-mail address
064       * @return the Contact with the given e-mail address
065       */
066      public abstract Contact getContact(Address a);
067    }