/* ======================================================================
   Parts Copyright 2006 University of Leeds, Oxford University, University of the Highlands and Islands.

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

====================================================================== */

package org.bodington.messaging;

import java.util.Hashtable;
import java.util.Vector;
import org.bodington.server.BuildingSession;
import org.bodington.server.BuildingServerException;
import org.bodington.database.PrimaryKey;

/**
 * Defines the interface for Messaging Room Sessions. Implementations
 * of this represent a session for one user onto one messaging room.
 * The session references the messaging room and stores
 * temporary data about messages, selections etc.
 * 
 * @author Jon Maber
 * @version 1.0
 */
public interface MessagingRoomSession extends BuildingSession
	{
	/**
	 * Finds out if specified message belongs to the MessagingRoom.
	 * 
	 * @param mid The id of the message.
	 * @return True if the message exists and belongs to the room referenced
	 * by this session.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	
	public boolean containsMessage( PrimaryKey mid )
		throws BuildingServerException;
		
    /**
     * Eventually will signal if the user can post a draft.  Drafting
     * of messages is not implemented yet.
     * 
     * @param key The id of the draft message.
     * @return Always returns false at present.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
     */
    public boolean canPostDraft( PrimaryKey key )
		throws BuildingServerException;

    /**
     * Finds out if the message can be edited.
     * 
     * @param key The ID of the message.
     * @return True if at present the user can edit the message.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
     */
    public boolean canEditMessage( PrimaryKey key )
		throws BuildingServerException;
	
    /**
     * Fetches a list of names for readers of the specified message.
     * 
     * @param key The ID of the message of interest.
     * @param with_dates True if a chronological log is required.
     * @return A vector with each entry set to a String.  This is either a 
     * list of names, alphabetical by surname or a list of Strings
     * comprising a date/time and a name in chronological order.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
     */
    public Vector getReaders( PrimaryKey key, boolean with_dates )
		throws BuildingServerException;
	
    /**
     * Fetches a list of names of people with view access to the
     * room who haven't read the message.
     * 
     * @param key The ID of the message.
     * @return Vector contains Strings of the names of the non-readers in
     * alphabetical order by surname.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
     */
    public Vector getNonReaders( PrimaryKey key )
		throws BuildingServerException;
	
    /**
     * Fetches list of participants by one of a number of definititions
     * of participant.
     * 
     * @param style The required type of list.
     * @return A Vector containing Strings of the names of the participants
     * in alphabetical order by surname.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
     */
    public Vector getParticipants( int style )
		throws BuildingServerException;
	
	/**
	 * Post a new message to the room.
	 * 
	 * @param subject The subject of the message.
	 * @param message The text of the message.
	 * @param style The message style. (Plain, smart, HTML).
	 * @return The ID of the new message.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public PrimaryKey postMessage( String subject, String message, int style )
		throws BuildingServerException;
		
	/**
	 * Posts a new message in reply to another message.
	 * 
	 * @param subject The subject of the message.
	 * @param message The text of the message.
	 * @param style The message style.
	 * @param inreplyto The ID of the message this is in reply to.
	 * @param branch True if the new message is a sub topic of the message it is
	 * replying to.
	 * @return The ID of the new message.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public PrimaryKey postMessage( String subject, String message, int style, PrimaryKey inreplyto, boolean branch )
		throws BuildingServerException;
		
	/**
	 * Updates and saves an existing message.
	 * 
	 * @param subject The new subject.
	 * @param message The new message text.
	 * @param style The new style.
	 * @param mid The ID of the message to change.
	 * @param branch The branch option to use.  (Currently changes to branching are not supported.)
	 * @return The ID of the saved message.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public PrimaryKey saveMessage( String subject, String message, int style, PrimaryKey mid, boolean branch )
		throws BuildingServerException;
		
        
        
	/**
	 * Gets a sorted list of tree nodes.
	 * 
	 * @param sort_type Defines the order - use constant from MessageTreeNodeComparator.
	 * @return The root node of a tree structure.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
        public MessageTreeNode[] getMessageTreeNodes( int sort_type )
            throws BuildingServerException;
        
	/**
	 * Obtains an object that defines the structure of all the messages
	 * in the room.
	 * 
	 * @return The root node of a tree structure.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public MessageTreeNode getMessageTree()
		throws BuildingServerException;

	/**
	 * Get's the text of a specific message.
	 * 
	 * @param key The ID of the message.
	 * @param mime_type The mime type to convert to.  (To display message ask for
	 * text/html, to quote ask for text/plain.)
	 * @return The (processed) text of the message.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public String getMessageText( PrimaryKey key, String mime_type )
		throws BuildingServerException;

	/**
	 * Get's a small sample of the the text of a specific message.  The message
         * won't be marked as read and no event will be logged.
	 * 
	 * @param key The ID of the message.
	 * @param max_length The maximum number of chars in sample.
	 * text/html, to quote ask for text/plain.)
	 * @return The (processed) text of the message.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public String getMessageTextSample( PrimaryKey key, int max_length )
		throws BuildingServerException;
        
	/**
	 * Get a class containing properties for the message.
	 * 
	 * @param key The ID of the message.
	 * @return A MessageSummary object for the message.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public MessageSummary getMessageSummary( PrimaryKey key )
		throws BuildingServerException;
		
	/**
	 * Get a table of message properties for all messages in the
	 * room.
	 * 
	 * @return A hashtable with all messages hashed against their ID.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public Hashtable getMessageSummaries()
		throws BuildingServerException;

	/**
	 * Get the messages that have been posted to the room since
	 * the last time message summaries were fetched via this
	 * session.
	 * 
	 * @return A hashtable of message summaries keyed against ID.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public Hashtable getMoreMessageSummaries()
		throws BuildingServerException;
		
	/**
	 * Get the ID of the currently selected message. (Each user
	 * in each session can have one message selected.)
	 * 
	 * @return The ID of the currently selected message.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public PrimaryKey getSelectedMessage()
		throws BuildingServerException;
		
	/**
	 * Select a message.
	 * 
	 * @param mid The ID of the message to be selected.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public void selectMessage( PrimaryKey mid )
		throws BuildingServerException;
		
	/**
	 * Select a message, collapse cousin braches and collapse grandchild branches.
	 * 
	 * @param mid The ID of the message to be selected.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public void selectMessageAndSimplifyTree( PrimaryKey mid )
		throws BuildingServerException;

	/**
	 * Select a message and expand just enough branches to make it visible.
	 * 
	 * @param mid The ID of the message to be selected.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
        public void selectMessageAndMakeVisible( PrimaryKey mid )
            throws BuildingServerException;
        
        
	/**
	 * Get a table indicating the visibility of all the messages.
	 * The session can keep track of the expansion and collapse
	 * of branches of the tree of messages.  This data structure
	 * is used to show the current state of play for the messages.
	 * It is possible that newly posted messages won't be listed in
	 * the table and you will have to make assumptions about whether
	 * to display them or not.
	 * 
	 * @return A hashtable whose elements are of type 
	 * org.bodington.util.Visibility which are keyed against the
	 * IDs of the messages in the room.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public Hashtable getVisibleMessages()
		throws BuildingServerException;
		
	/**
	 * Make the children of the specified message visibile and
	 * mark this message as open.  This leaves the grandchildren
	 * of the message invisible.
	 * 
	 * @param mid The ID of the message to open.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public void openMessageBranch( PrimaryKey mid )
		throws BuildingServerException;
		
	/**
	 * Make all descendents of this message invisible and mark
	 * this message as closed.
	 * 
	 * @param mid The ID of the message to close.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public void closeMessageBranch( PrimaryKey mid )
		throws BuildingServerException;

	/**
	 * Make all messages visible and open.
	 * 
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public void openAllMessageBranches()
		throws BuildingServerException;
		
	/**
	 * Mark the top level messages as closed and make all other messages
	 * invisible. (Doesn't make the top level messages invisible.)
	 * 
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public void closeAllMessageBranches()
		throws BuildingServerException;
	}
