/* ======================================================================
The Bodington System Software License, Version 1.0
  
Copyright (c) 2001 The University of Leeds.  All rights reserved.
  
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

1.  Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.

2.  Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

3.  The end-user documentation included with the redistribution, if any,
must include the following acknowledgement:  "This product includes
software developed by the University of Leeds
(http://www.bodington.org/)."  Alternately, this acknowledgement may
appear in the software itself, if and wherever such third-party
acknowledgements normally appear.

4.  The names "Bodington", "Nathan Bodington", "Bodington System",
"Bodington Open Source Project", and "The University of Leeds" must not be
used to endorse or promote products derived from this software without
prior written permission. For written permission, please contact
d.gardner@leeds.ac.uk.

5.  The name "Bodington" may not appear in the name of products derived
from this software without prior written permission of the University of
Leeds.

THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO,  TITLE,  THE IMPLIED WARRANTIES 
OF QUALITY  AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO 
EVENT SHALL THE UNIVERSITY OF LEEDS OR ITS CONTRIBUTORS BE LIABLE FOR 
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 
ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
POSSIBILITY OF SUCH DAMAGE.
=========================================================

This software was originally created by the University of Leeds and may contain voluntary 
contributions from others.  For more information on the Bodington Open Source Project, please 
see http://bodington.org/

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

package org.bodington.messaging;

import java.rmi.*;
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 java.rmi.RemoteException Thrown if session is accessed remotely and there is a problem
	 * transfering arguments or return value.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	
	public boolean containsMessage( PrimaryKey mid )
		throws RemoteException, 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 java.rmi.RemoteException Thrown if session is accessed remotely and there is a problem
	 * transfering arguments or return value.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
     */
    public boolean canPostDraft( PrimaryKey key )
		throws RemoteException, 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 java.rmi.RemoteException Thrown if session is accessed remotely and there is a problem
	 * transfering arguments or return value.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
     */
    public boolean canEditMessage( PrimaryKey key )
		throws RemoteException, 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 java.rmi.RemoteException Thrown if session is accessed remotely and there is a problem
	 * transfering arguments or return value.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
     */
    public Vector getReaders( PrimaryKey key, boolean with_dates )
		throws RemoteException, 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 java.rmi.RemoteException Thrown if session is accessed remotely and there is a problem
	 * transfering arguments or return value.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
     */
    public Vector getNonReaders( PrimaryKey key )
		throws RemoteException, 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 java.rmi.RemoteException Thrown if session is accessed remotely and there is a problem
	 * transfering arguments or return value.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
     */
    public Vector getParticipants( int style )
		throws RemoteException, 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 java.rmi.RemoteException Thrown if session is accessed remotely and there is a problem
	 * transfering arguments or return value.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public PrimaryKey postMessage( String subject, String message, int style )
		throws RemoteException, 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 java.rmi.RemoteException Thrown if session is accessed remotely and there is a problem
	 * transfering arguments or return value.
	 * @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 RemoteException, 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 java.rmi.RemoteException Thrown if session is accessed remotely and there is a problem
	 * transfering arguments or return value.
	 * @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 RemoteException, 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 java.rmi.RemoteException Thrown if session is accessed remotely and there is a problem
	 * transfering arguments or return value.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
        public MessageTreeNode[] getMessageTreeNodes( int sort_type )
            throws RemoteException, BuildingServerException;
        
	/**
	 * Obtains an object that defines the structure of all the messages
	 * in the room.
	 * 
	 * @return The root node of a tree structure.
	 * @exception java.rmi.RemoteException Thrown if session is accessed remotely and there is a problem
	 * transfering arguments or return value.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public MessageTreeNode getMessageTree()
		throws RemoteException, 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 java.rmi.RemoteException Thrown if session is accessed remotely and there is a problem
	 * transfering arguments or return value.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public String getMessageText( PrimaryKey key, String mime_type )
		throws RemoteException, 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 java.rmi.RemoteException Thrown if session is accessed remotely and there is a problem
	 * transfering arguments or return value.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public String getMessageTextSample( PrimaryKey key, int max_length )
		throws RemoteException, BuildingServerException;
        
	/**
	 * Get a class containing properties for the message.
	 * 
	 * @param key The ID of the message.
	 * @return A MessageSummary object for the message.
	 * @exception java.rmi.RemoteException Thrown if session is accessed remotely and there is a problem
	 * transfering arguments or return value.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public MessageSummary getMessageSummary( PrimaryKey key )
		throws RemoteException, BuildingServerException;
		
	/**
	 * Get a table of message properties for all messages in the
	 * room.
	 * 
	 * @return A hashtable with all messages hashed against their ID.
	 * @exception java.rmi.RemoteException Thrown if session is accessed remotely and there is a problem
	 * transfering arguments or return value.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public Hashtable getMessageSummaries()
		throws RemoteException, 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 java.rmi.RemoteException Thrown if session is accessed remotely and there is a problem
	 * transfering arguments or return value.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public Hashtable getMoreMessageSummaries()
		throws RemoteException, 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 java.rmi.RemoteException Thrown if session is accessed remotely and there is a problem
	 * transfering arguments or return value.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public PrimaryKey getSelectedMessage()
		throws RemoteException, BuildingServerException;
		
	/**
	 * Select a message.
	 * 
	 * @param mid The ID of the message to be selected.
	 * @exception java.rmi.RemoteException Thrown if session is accessed remotely and there is a problem
	 * transfering arguments or return value.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public void selectMessage( PrimaryKey mid )
		throws RemoteException, BuildingServerException;
		
	/**
	 * Select a message, collapse cousin braches and collapse grandchild branches.
	 * 
	 * @param mid The ID of the message to be selected.
	 * @exception java.rmi.RemoteException Thrown if session is accessed remotely and there is a problem
	 * transfering arguments or return value.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public void selectMessageAndSimplifyTree( PrimaryKey mid )
		throws RemoteException, BuildingServerException;

	/**
	 * Select a message and expand just enough branches to make it visible.
	 * 
	 * @param mid The ID of the message to be selected.
	 * @exception java.rmi.RemoteException Thrown if session is accessed remotely and there is a problem
	 * transfering arguments or return value.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
        public void selectMessageAndMakeVisible( PrimaryKey mid )
            throws RemoteException, 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 java.rmi.RemoteException Thrown if session is accessed remotely and there is a problem
	 * transfering arguments or return value.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public Hashtable getVisibleMessages()
		throws RemoteException, 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 java.rmi.RemoteException Thrown if session is accessed remotely and there is a problem
	 * transfering arguments or return value.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public void openMessageBranch( PrimaryKey mid )
		throws RemoteException, BuildingServerException;
		
	/**
	 * Make all descendents of this message invisible and mark
	 * this message as closed.
	 * 
	 * @param mid The ID of the message to close.
	 * @exception java.rmi.RemoteException Thrown if session is accessed remotely and there is a problem
	 * transfering arguments or return value.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public void closeMessageBranch( PrimaryKey mid )
		throws RemoteException, BuildingServerException;

	/**
	 * Make all messages visible and open.
	 * 
	 * @exception java.rmi.RemoteException Thrown if session is accessed remotely and there is a problem
	 * transfering arguments or return value.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public void openAllMessageBranches()
		throws RemoteException, BuildingServerException;
		
	/**
	 * Mark the top level messages as closed and make all other messages
	 * invisible. (Doesn't make the top level messages invisible.)
	 * 
	 * @exception java.rmi.RemoteException Thrown if session is accessed remotely and there is a problem
	 * transfering arguments or return value.
	 * @exception org.bodington.server.BuildingServerException Thrown if there is a problem fulfilling request.
	 */
	public void closeAllMessageBranches()
		throws RemoteException, BuildingServerException;
	}