/* ======================================================================
   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.logbook.server;

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

/**
 * An interface that defines the functionality of a log book session,
 * where a session represents a single user accessing a specific
 * logbook.
 * 
 * @author Jon Maber
 * @author Peter Crowther
 */
public interface LogBookSession extends BuildingSession 
	{

	/**
	 * Finds out if the user closable option is set on the LogBook by 
	 * calling the underlying LogBook object.
	 * 
	 * @return A boolean indicating the state of the option.
	 * @exception BuildingServerException
	 */
	public boolean isUserClosable() throws BuildingServerException;

	/**
	 * Can the current user change the open/closed state of the page?
	 * 
	 * @return The value of this option.
	 * @exception BuildingServerException
	 */
	public boolean canOpenOrClose( PrimaryKey page_id ) throws BuildingServerException;
		
	/**
	 * Closes the LogBook.
	 * 
	 * @param page_id The ID of the page to close or open.
	 * @param closed Whether to close or open the log book.
	 * @exception BuildingServerException
	 */
	public void setPageClosed( PrimaryKey page_id, boolean closed ) throws BuildingServerException;

	/**
	 * Sets the value of the user closable option on the LogBook by 
	 * calling the underlying LogBook object and then saves the LogBook
	 * object to the database.
	 * 
	 * @param b The new  value of the option.
	 * @exception BuildingServerException
	 */
	public void setUserClosable( boolean b ) throws BuildingServerException;

	
	/**
	 * Asks the LogBook object to load all its sections and questions and
	 * puts these into a hashtable keyed against their primary keys. 
	 * 
	 * @return A hashtable containing the sections and questions.
	 * @exception BuildingServerException
	 */
	public Hashtable getSectionAndQuestionTable() throws BuildingServerException;

	/**
	 * Get an array of the sections in their proper order.  These
	 * objects should be treated as read only.
	 * 
	 * @return An array of LogBookSection objects in order.
	 * @exception BuildingServerException
	 */
	public LogBookSection[] getSectionsInOrder() throws BuildingServerException;

	/**
	 * For a specified section get an array of the questions in 
	 * their proper order.  These objects should be treated as read 
	 * only.
	 * 
	 * @param section_id The id of the required section.
	 * @return An array of LogBookQuestion objects
	 * @exception BuildingServerException
	 */
	public LogBookQuestion[] getQuestionsInOrder( PrimaryKey section_id ) throws BuildingServerException;

	/**
	 * Create a new section at the end of the list.
	 * 
	 * @return The LogBookSection created

	 * @exception BuildingServerException
	 */
	public LogBookSection createSection() throws BuildingServerException;

	/**
	 * Create a new question at the end of a sectiont.
	 * 
	 * @return The LogBookQuestion created
	 * @exception BuildingServerException
	 */
	public LogBookQuestion createQuestion( PrimaryKey section_id ) throws BuildingServerException;

	/**
	 * Deletes a specific section.
	 * 
	 * @exception BuildingServerException
	 */
	public void deleteSection( PrimaryKey section_id ) throws BuildingServerException;

	/**
	 * Deletes a specific question.
	 * 
	 * @exception BuildingServerException
	 */
	public void deleteQuestion( PrimaryKey question_id ) throws BuildingServerException;

	/**
	 * Changes a number of properties of a specified section.
	 * It is best if the session does this rather than the calling
	 * code using the setter methods in the LogBookSection 
	 * directly so we can gather all database operations into one 
	 * class.
	 * 
	 * @param section_id An id number of a section in this log book.
	 * @param ordinal The new ordinal value to set.
	 * @param title The new title to set.
	 * @param introduction The new introduction text to set.
	 * @exception BuildingServerException
	 */
	public void changeSection( PrimaryKey section_id, int ordinal, String title, String introduction ) throws BuildingServerException;

	/**
	 * Changes a number of properties of a specified question.
	 * It is best if the session does this rather than the calling
	 * code using the setter methods in the LogBookSection 
	 * directly so we can gather all database operations into one 
	 * class.
	 * 
	 * @param ordinal The new ordinal value to set.
	 * @param title The new title to set.
	 * @param q The new question text to set.
	 * @param help The new help text to set.
	 * @exception BuildingServerException
	 */
	public void changeQuestion( PrimaryKey question_id, int ordinal, String title, String q, String help ) throws BuildingServerException;

	public LogBookPage[] getPagesInOrder()
		throws BuildingServerException;
	public LogBookPage getPageForUser( PrimaryKey user_id )
		throws BuildingServerException;
	public LogBookEntry[] getEntriesInOrder( PrimaryKey question_id, PrimaryKey user_id )
		throws BuildingServerException;
	public LogBookEntry getEntry( PrimaryKey entry_id )
		throws BuildingServerException;
	public String getUserFullName( PrimaryKey user_id )
		throws BuildingServerException;
	public void postEntry( PrimaryKey question_id, PrimaryKey user_id, String text, boolean draft, boolean isPrivate, String linked_url )
		throws BuildingServerException;
	public void editEntry( PrimaryKey entry_id, String text, boolean draft, boolean isPrivate, String linked_url )
		throws BuildingServerException;
	public void selectEntry( PrimaryKey entry_id, boolean select )
		throws BuildingServerException;
	public void markEntriesSeen( PrimaryKey question_id, PrimaryKey user_id )
		throws BuildingServerException;
	public void generateCsvQuestionFile()
		throws BuildingServerException;
    public Vector getViewUserIds()
		throws BuildingServerException;
    public Vector getPageUserIds()
		throws BuildingServerException;
	public Hashtable getLastReadEventTable()
		throws BuildingServerException;
        /**
         * Return an alphabetised list of users who have (if possible is false)
         * or could have but have not (if possible is true) visitor access to the
         * specified page.  Note that the page's author is never returned.
         * @param page The page to which the Visitors should have access.
         * @param possible if true, users who could have access but do not are returned; if false, users who have access are returned.
         */
        public Vector getPeers( LogBookPage page, boolean possible )
		throws BuildingServerException;
        
        /**
         * Add the specified user to the visitors list for the specified page.
         * @param page The page to which the visitor should be added.
         * @param user_id The user_id of the user to be added.
         */
        public void addVisitor( LogBookPage page, PrimaryKey user_id )
		throws BuildingServerException;
        
        /**
         * Remove the specified user from the visitors list for the specified page.
         * @param page The page to which the visitor should be added.
         * @param user_id The user_id of the user to be added.
         */
        public void removeVisitor( LogBookPage page, PrimaryKey user_id )
		throws BuildingServerException;
        

        }