/* ======================================================================
   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.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.
     * 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, if null then the system determines the mime type.
     * 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.
     * 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.
     * 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
     * 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
     * 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
     * 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.
     * This should update the mime type to the mime type of the new filename.
     * If the file has a custom mime type then it should be reset to an automatic one.
     * @param pathname
     * 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
     * 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
     * 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
     * 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.
     * 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
     * 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
     * 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.
     * 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
     * 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.
     * 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.
     * 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
     * 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
     * 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.
     * transmitting parameters or return value.
     * @param omit_deleted If <code>true</code> the don't include the deleted 
     * resources.
     * @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.
     * 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.
     * 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;
    
    /**
     * Sets the Uploaded Files quota for the current resource only if there
     * isn't already a quota set.
     * @param quota The quota limit.
     * @throws BuildingServerException If there is already a quota or something
     * went wrong.
     */
    public void createQuota(long quota) throws BuildingServerException;
    
    /**
     * Check that the current uploaded file quota is correct.
     * @return <code>true</code> if the quota is correct.
     */
    public boolean checkFileQuota() throws BuildingServerException;
}
