001    package edu.harvard.deas.hyperenc.gui;
002    
003    import java.util.Collection;
004    
005    import edu.harvard.deas.hyperenc.Contact;
006    
007    
008    /**
009     * Stores collections of GuiMessages. Supports retrieval of all GuiMessages from
010     * a particular sender.
011     * <p>
012     * The messages stored in a MessageStorage may be stored either by value or by
013     * reference. This means that GuiMessages returned by the <code>get*</code>
014     * methods might not be identical to those that were originally stored, but will
015     * compare equal via the <code>equals</code> method. (This requirement allows
016     * for the possibility that an implementation may store messages on disk and
017     * reconstruct them later, resulting in the same message with a different object
018     * reference.)
019     * <p>
020     * <b>Thread safety:</b> Implementations of this class must be
021     * <i>unconditionally thread-safe</i>; concurrent access by multiple threads
022     * should be safe without the need for external synchronization.
023     */
024    // We use an abstract class instead of an interface for ease of class evolutions
025    // (See Effective Java 2nd Ed., Item 18)
026    public abstract class MessageStorage {
027      /**
028       * Default constructor. Does nothing.
029       */
030      public MessageStorage() {}
031    
032      
033      /**
034       * Put message in storage.
035       * 
036       * @param msg
037       *        Message to be stored.
038       */
039      public abstract void addMessage(GuiMessage msg);
040    
041      /**
042       * Get message from this storage, given its ID. The ID is that given by the
043       * <code>getID</code> method of GuiMessage.
044       * 
045       * @param id
046       *        ID of desired message.
047       * @return the message with the given ID, or <code>null</code> if
048       *         there is no such message stored.
049       */
050      public abstract GuiMessage getMessage(int id);
051    
052      /**
053       * Get all stored messages sent from a particular contact. Callers may mutate
054       * the returned Collection.
055       * 
056       * @param contact
057       *        contact of desired sender
058       * @return a Collection of all incoming messages from the specified sender. If
059       *         there are no messages stored from the specified sender, returns an
060       *         empty Collection. Changes to the returned Collection are not
061       *         reflected in this MessageStorage.
062       */
063      public abstract Collection<GuiMessage> getMessagesBySender(Contact contact);
064    
065      /**
066       * Remove a message from storage. If there is no such message, does nothing.
067       * 
068       * @param id
069       *        ID of message to be removed.
070       * @return The message with the given ID, or <code>null</code> if there is no
071       *         such message stored.
072       */
073      public abstract GuiMessage removeMessage(int id);
074    
075    }