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

import java.io.File;
import java.util.zip.ZipFile;

import javax.swing.tree.DefaultMutableTreeNode;

import org.bodington.database.PrimaryKey;
import org.bodington.server.resources.UploadedFileSummary;

public interface UploadedFileSession
{
 
    /**
     * Specifies a file on the file system of VM implementing the session to copy into the
     * currently selected resource.  (Uses 
     * {@link #transferFile(String, String, String)}, without deleting original file.) <p>
     * <i>(WebLearn modification (method added): 02/12/2003 Colin Tatham)</i>
     * @param current_pathname The file system pathname of the file.
     * @param resource_pathname The destination of the file relative to the resource storage area. URL encoded.
     * @param mime_type The mime type of the file to record.
     * @return Reference to the file that was copied.
     * @exception java.rmi.RemoteException Thrown if the method is accessed remotely and there is a problem
     * transmitting parameters or return value.
     * @exception org.bodington.server.BuildingServerException Thrown if there is a problem servicing the method call.
     */
    public abstract UploadedFileSummary copyFile(String current_pathname,
        String resource_pathname, String mime_type) throws BuildingServerException;

    /**
     * Specifies a file on the file system of VM implementing the session to move into the
     * currently selected resource.  Most likely used by servlet running on same computer
     * to put file into resource.  Applet running on client computer would have to use another
     * 
     * @param current_pathname The file system pathname of the file.
     * @param resource_pathname The destination of the file relative to the resource storage area.
     * @param mime_type The mime type of the file to record.
     * @exception java.rmi.RemoteException Thrown if the method is accessed remotely and there is a problem
     * transmitting parameters or return value.
     * @exception org.bodington.server.BuildingServerException Thrown if there is a problem servicing the method call.
     */
    public abstract UploadedFileSummary transferFile(String current_pathname,
        String resource_pathname, String mime_type) throws BuildingServerException;

    public abstract void transferZipFile(ZipFile archive, String startfilename)
        throws BuildingServerException;

    /**
     * Create a folder in the resource for uploading files.
     * <p>
     * Some situation where this method succeds when you expect it to fail:
     * <ul>
     *  <li>If the folder that is being create already exists succed.</li>
     *  <li>If the folder already exists but is deleted undelete it.</li>
     * </ul>
     * </p> 
     * Should check with resource to see if it is capable of
     * accepting uploaded files.
     * 
     * @param pathname The pathname of the folder without separators. If null is
     * passed this this should be taken to mean the root folder.
     * @return The UploadedFileSummary of the created Folder.
     * @exception java.rmi.RemoteException Thrown if the method is accessed remotely and there is a problem
     * transmitting parameters or return value.
     * @exception org.bodington.server.BuildingServerException
     * <p>
     * Throws an error if:
     * <ul>
     *  <li>A file exists and the requested path.</li>
     *  <li>A folder is trying to be created inside a file.</li>
     *  <li>A folder is trying to be created inside a deleted folder.</li>
     *  <li>The parent folder can't be found.</li>
     *  <li>Or some lowlevel problem.</li>
     * </ul>
     * </p>
     */
    public abstract UploadedFileSummary createFolder(String pathname)
        throws BuildingServerException;

    /**
     * Create an empty file in a resource which is initially empty
     * and ready to receive data.
     * 
     * @param pathname The name of the file including folder name.
     * @param size The size of the file to create.
     * @param mime_type The mime type of the file to record.
     * @exception java.rmi.RemoteException Thrown if the method is accessed remotely and there is a problem
     * transmitting parameters or return value.
     * @exception org.bodington.server.BuildingServerException Thrown if there is a problem servicing the method call.
     */
    public abstract void createFile(String pathname, long size, String mime_type)
        throws BuildingServerException;

    /**
     * Check the validity of creating a folder in the resource.
     * 
     * @param pathname
     * @exception java.rmi.RemoteException Thrown if the method is accessed remotely and there is a problem
     * transmitting parameters or return value.
     * @exception org.bodington.server.BuildingServerException Thrown if there is a problem servicing the method call.
     */
    public abstract void checkCreateFolder(String pathname)
        throws BuildingServerException;

    /**
     * Check the validity of creating a file.
     * 
     * @param pathname
     * @param size
     * @exception java.rmi.RemoteException Thrown if the method is accessed remotely and there is a problem
     * transmitting parameters or return value.
     * @exception org.bodington.server.BuildingServerException Thrown if there is a problem servicing the method call.
     */
    public abstract void checkCreateFile(String pathname, long size)
        throws BuildingServerException;

    /**
     * Delete the specified file or folder.
     * 
     * @param pathname
     * @exception java.rmi.RemoteException Thrown if the method is accessed remotely and there is a problem
     * transmitting parameters or return value.
     * @exception org.bodington.server.BuildingServerException Thrown if there is a problem servicing the method call.
     */
    public abstract void deleteFile(String pathname) throws BuildingServerException;

    /**
     * Delete the specified file or folder.
     * 
     * @param pathname
     * @exception java.rmi.RemoteException Thrown if the method is accessed remotely and there is a problem
     * transmitting parameters or return value.
     * @exception org.bodington.server.BuildingServerException Thrown if there is a problem servicing the method call.
     */
    public abstract void renameFile(String pathname, String newname)
        throws BuildingServerException;

    /**
     * UnDelete the specified file or folder.
     * 
     * @param pathname
     * @exception java.rmi.RemoteException Thrown if the method is accessed remotely and there is a problem
     * transmitting parameters or return value.
     * @exception org.bodington.server.BuildingServerException Thrown if there is a problem servicing the method call.
     */
    public abstract void undeleteFile(String pathname, boolean recurse)
        throws BuildingServerException;

    /**
     * Put bytes into the file at the end of where bytes were last put.
     * Method will check offset parameter to see if this call has come
     * in sequence and will check the CRC32 against the data received.
     * 
     * @param pathname
     * @param offset
     * @param data
     * @param crc32
     * @exception java.rmi.RemoteException Thrown if the method is accessed remotely and there is a problem
     * transmitting parameters or return value.
     * @exception org.bodington.server.BuildingServerException Thrown if there is a problem servicing the method call.
     */
    public abstract void writeToFile(String pathname, long offset, byte[] data,
        int crc32) throws BuildingServerException;

    /**
     * Looks at the data segment in the file and calculates a CRC32.
     * Checks the calculated CRC32 against the crc32 parameter.
     * 
     * @param pathname
     * @param offset
     * @param length
     * @param crc32
     * @exception java.rmi.RemoteException Thrown if the method is accessed remotely and there is a problem
     * transmitting parameters or return value.
     * @exception org.bodington.server.BuildingServerException Thrown if there is a problem servicing the method call.
     */
    public abstract void compareWithFile(String pathname, long offset,
        long length, int crc32) throws BuildingServerException;

    /**
     * Fetches a set of bytes from the file.
     * 
     * @param pathname
     * @param offset
     * @param data
     * @return The crc32 of the requested bytes.
     * @exception java.rmi.RemoteException Thrown if the method is accessed remotely and there is a problem
     * transmitting parameters or return value.
     * @exception org.bodington.server.BuildingServerException Thrown if there is a problem servicing the method call.
     */
    public abstract int readFromFile(String pathname, long offset, byte[] data)
        throws BuildingServerException;

    /**
     * If the resource published the file on the web return the URL that reference where
     * the file is actually stored.  This is not to be published on a page.
     * 
     * @param uf_id Id of the file
     * @exception java.rmi.RemoteException Thrown if the method is accessed remotely and there is a problem
     * transmitting parameters or return value.
     * @exception org.bodington.server.BuildingServerException Thrown if there is a problem servicing the method call.
     */
    public abstract String getRealURL(PrimaryKey uf_id) throws BuildingServerException;

    /**
     * If the resource published the file on the web return the URL that can be published as
     * a reference to it.
     * 
     * @param uf_id Id of the file
     * @exception java.rmi.RemoteException Thrown if the method is accessed remotely and there is a problem
     * transmitting parameters or return value.
     * @exception org.bodington.server.BuildingServerException Thrown if there is a problem servicing the method call.
     */
    public abstract String getPublishedURL(PrimaryKey uf_id)
        throws BuildingServerException;

    /**
     * Get the MIME type of a file.
     * 
     * @param pathname
     * @return The MIME type.
     * @exception java.rmi.RemoteException Thrown if the method is accessed remotely and there is a problem
     * transmitting parameters or return value.
     * @exception org.bodington.server.BuildingServerException Thrown if there is a problem servicing the method call.
     */
    public abstract String getFileMimeType(String pathname)
        throws BuildingServerException;

    /**
     * Change the MIME type of an existing file.
     * 
     * @param pathname
     * @param mime_type
     * @exception java.rmi.RemoteException Thrown if the method is accessed remotely and there is a problem
     * transmitting parameters or return value.
     * @exception org.bodington.server.BuildingServerException Thrown if there is a problem servicing the method call.
     */
    public abstract void setFileMimeType(String pathname, String mime_type)
        throws BuildingServerException;

    /**
     * Get properties of file.
     * 
     * @param pathname Pathname of folder or null to indicate the root.
     * @exception java.rmi.RemoteException Thrown if the method is accessed remotely and there is a problem
     * transmitting parameters or return value.
     * @exception org.bodington.server.BuildingServerException Thrown if there is a problem servicing the method call.
     */
    public abstract UploadedFileSummary getFileSummary(String pathname)
        throws BuildingServerException;

    /**
     * Get properties of file.
     * 
     * @param path Pathname, split into parts of folder.
     * @exception java.rmi.RemoteException Thrown if the method is accessed remotely and there is a problem
     * transmitting parameters or return value.
     * @exception org.bodington.server.BuildingServerException Thrown if there is a problem servicing the method call.
     */
    public abstract UploadedFileSummary getFileSummary(String[] path)
        throws BuildingServerException;

    /**
     * Get properties of file.
     * 
     * @param id ID of file in database
     * @exception java.rmi.RemoteException Thrown if the method is accessed remotely and there is a problem
     * transmitting parameters or return value.
     * @exception org.bodington.server.BuildingServerException Thrown if there is a problem servicing the method call.
     */
    public abstract UploadedFileSummary getFileSummary(PrimaryKey id)
        throws BuildingServerException;

    /**
     * Get reference to the file in the host file system.
     * 
     * @param id ID of file in database
     * @exception java.rmi.RemoteException Thrown if the method is accessed remotely and there is a problem
     * transmitting parameters or return value.
     * @exception org.bodington.server.BuildingServerException Thrown if there is a problem servicing the method call.
     */
    public abstract File getFile(PrimaryKey id) throws BuildingServerException;

    /**
     * Get properties of file and its descendents in visitation model order.
     * 
     * @param pathname Pathname of folder or null to indicate the root.
     * @exception java.rmi.RemoteException Thrown if the method is accessed remotely and there is a problem
     * transmitting parameters or return value.
     * @exception org.bodington.server.BuildingServerException Thrown if there is a problem servicing the method call.
     */
    public abstract UploadedFileSummary[] getFileAndDescendentSummaries(
        String pathname, boolean omit_deleted) throws BuildingServerException;

    /**
     * Get properties of file and its ancestors from root to the file itself.
     * 
     * @param pathname Pathname of folder or null to indicate the root.
     * @exception java.rmi.RemoteException Thrown if the method is accessed remotely and there is a problem
     * transmitting parameters or return value.
     * @exception org.bodington.server.BuildingServerException Thrown if there is a problem servicing the method call.
     */
    public abstract UploadedFileSummary[] getFileAndAncestorSummaries(
        String pathname) throws BuildingServerException;

    /**
     * Get properties of file and its descendents in visitation model order.
     * 
     * @param pathname Pathname of folder or null to indicate the root.
     * @exception java.rmi.RemoteException Thrown if the method is accessed remotely and there is a problem
     * transmitting parameters or return value.
     * @exception org.bodington.server.BuildingServerException Thrown if there is a problem servicing the method call.
     */
    public DefaultMutableTreeNode getFileAndDescendentSummaryTree( String pathname, boolean omit_deleted  )
        throws BuildingServerException;
    
    
    /**
     * Find the Uploaded Files quota for the current resource.
     * The quota will include all child resources that don't have thier own 
     * quota set. 
     * @return The quota for the current resource, <code>null</code> if there
     * isn't a quota.
     */
    public Quota getQuota() throws BuildingServerException;
    
    /**
     * Set the Uploaded Files quota for the current resource.
     * @param quota The quota limit.
     * @throws BuildingServerException If there is a problem setting the quota
     * for example the resource doesn't already have a quota set and has children.
     * @throws PermissionDeniedException If the current user doesn't have
     * permission to set the quota.
     */
    public void setQuota(long quota) throws BuildingServerException;
    
}