FileData

//
// $Id: FileData.java 95 2007-05-02 03:27:05Z
// /C=DE/ST=Baden-Wuerttemberg/O=ISDN4Linux/OU=Fritz
// Elfert/CN=svn-felfert@isdn4linux.de/emailAddress=fritz@fritz-elfert.de $
//
// jupload - A file upload applet.
// Copyright 2007 The JUpload Team
//
// Created: 2006-11-20
// Creator: etienne_sf
// Last modified: $Date: 2015-03-14 15:13:43 +0100 (sam., 14 mars 2015) $
//
// This program is free software; you can redistribute it and/or modify it under
// the terms of the GNU General Public License as published by the Free Software
// Foundation; either version 2 of the License, or (at your option) any later
// version. This program is distributed in the hope that it will be useful, but
// WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
// FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
// details. You should have received a copy of the GNU General Public License
// along with this program; if not, write to the Free Software Foundation, Inc.,
// 675 Mass Ave, Cambridge, MA 02139, USA.

package wjhk.jupload2.filedata;

import java.io.File;
import java.io.InputStream;
import java.util.Date;

import wjhk.jupload2.exception.JUploadException;
import wjhk.jupload2.exception.JUploadIOException;
import wjhk.jupload2.gui.filepanel.treeview.TreeFileDataNode;
import wjhk.jupload2.policies.UploadPolicy;
import wjhk.jupload2.upload.FileUploadThread;
import wjhk.jupload2.upload.helper.ByteArrayEncoder;

/**
 * This class contains all data and methods for a file to upload. The current
 * {@link wjhk.jupload2.policies.UploadPolicy} contains the necessary parameters to personalize the way files must be
 * handled. <BR>
 * The JUpload package provides a default implementation of this class in {@link DefaultFileData}. This default
 * implementation contains all necessary methods to allow upload. You can override it to add new file behaviour. For
 * instance, you could add a XMLFileData, that would check that XML is valid before upload. See the <a
 * href="package-summary.html">package summary</a> for more details about that. <BR>
 * This class is the interface that all FileData must implement. The {@link DefaultFileData} class contains the default
 * implementation for this interface. The {@link PictureFileData} contains another implementation of this interface,
 * adapted to manage pictures (rotation, resizing...). <BR>
 * The instance of FileData is created by the {@link UploadPolicy#createFileData(File, File)} method. This method can be
 * overrided in a new upoad policy, to create an instance of another FileData. See {@link PictureFileData} for an
 * example about FileData customization.
 *
 * @author etienne_sf
 */

public interface FileData {

    /**
     * Called during the upload, by the {@link FileUploadThread}. The FileData instance should then call the
     * {@link ByteArrayEncoder#appendTextProperty(String, String, int)} method to add each file property to the current
     * upload.
     *
     * @param bae The byte encoder, where the properties must be added
     * @param index Index of the file concerned by this value. -1 if this is a global parameter.
     * @throws JUploadIOException Encapsulation of the IOException, if any would occurs.
     * @see ByteArrayEncoder#appendTextProperty(String, String, int)
     */
    public void appendFileProperties(ByteArrayEncoder bae, int index) throws JUploadIOException;

    /**
     * Prepare the fileData to upload. For instance, picture data can be resized before upload (see
     * {@link PictureFileData}. This method is called before the upload of this file. If no exception is thrown, then
     * the file is correctly prepared.
     *
     * @param uploadFileRoot The biggest path which is common to all uploaded files. Used to calculate the relativeDir
     *            to this root path, for each file. This relative path is sent as metadata during the upload
     * @throws JUploadException Encapsulation of the Exception, if any error would occurs.
     * @see FileUploadThread
     * @see #getRelativeDir()
     */
    public void beforeUpload(String uploadFileRoot) throws JUploadException;

    /**
     * Get size of upload, which may be different from the actual file length. This call is valid only after a call to
     * {@link #beforeUpload()} and before the call to {@link #afterUpload()}.
     *
     * @return The length of upload. In this class, this is the size of the file, as it isn't transformed for upload.
     *         This size may change if encoding is necessary (needs a new FileData class), or if picture is to be
     *         resized or rotated.
     * @see PictureFileData
     */
    public long getUploadLength();

    /**
     * This function is called after upload, whether it is successful or not. It allows fileData to free any resource
     * created for the upload. For instance, {@link PictureFileData#afterUpload()} removes the temporary file, if any
     * was created.
     */
    public void afterUpload();

    /**
     * This function creates an InputStream from this file. The {@link FileUploadThread} class then reads bytes from it
     * and transfers them to the webserver. The caller is responsible for closing this stream.<BR>
     * This method may only be called when {@link #isPreparedForUpload()} returns true.
     *
     * @throws JUploadException Encapsulation of the Exception, if any would occurs.
     * @throws IllegalStateException When the upload is not prepared (before a call to {@link #beforeUpload()} or after
     *             a call to {@link #afterUpload()}
     * @return An InputStream, representing this instance.
     */
    public InputStream getInputStream() throws JUploadException;

    /**
     * Get the original filename. This is the name of the file, into the local hardrive
     *
     * @return The original filename
     */
    public String getFileName();

    /**
     * @return The extension for the original file.
     */
    public String getFileExtension();

    /**
     * @return The length of the original file.
     */
    public long getFileLength();

    /**
     * @return The original file date.
     */
    public Date getLastModified();

    /**
     * Indicates whether the check box is checked or not. That is: whether the file should be uploaded or not.
     *
     * @return
     */
    public boolean getUploadFlag();

    /**
     * Allows to set or unset the upload flag.
     *
     * @return
     */
    public void setUploadFlag(boolean uploadFlag);

    /**
     * Get the directory of the file.
     *
     * @return The directory where this file is stored.
     */
    public String getDirectory();

    /**
     * Retrieves the MD5 sum of the file.<BR>
     * Since 5.0.0, this method is is in DefaultFileData, and is calculated depending on the sendMD5Sum applet
     * parameter, during the file preparation file.
     *
     * @return The corresponding MD5 sum.
     * @throws JUploadException
     * @see #beforeUpload()
     */
    public String getMD5() throws JUploadException;

    /**
     * This function return the FileData content type.
     *
     * @return The mimeType for the file.
     */
    public String getMimeType();

    /**
     * Indicate if this file can be read. Take care of the File.canRead() methods, that seems to be wrong from time to
     * time.
     *
     * @return indicates whether the file can be read or not.
     */
    public boolean canRead();

    /**
     * Retrieves the path of this file relative to the root directory
     *
     * @return This instance's relative path or an empty string if it was not created using a root parameter.
     */
    public String getRelativeDir();

    /**
     * Returns the absolute path, as it will be sent during the upload. In standard mode, it is the concatenation of the
     * root and the relative path, that is: the absolute path of the File to upload on the local file system. In
     * hierarchical mode, it is the path relative to the (empty) upload root.
     *
     * @return
     */
    public String getAbsolutePath();

    /**
     * Indicates whether the file can be uploaded or not. This boolean should be set to true in the call to
     * {@link #beforeUpload()}, and the to false in the call to {@link #afterUpload()}.
     *
     * @return True if the file is ready for upload.
     * @throws IllegalStateException When the upload is not prepared (before a call to {@link #beforeUpload()} or after
     *             a call to {@link #afterUpload()}
     */
    public boolean isPreparedForUpload();

    /**
     * Links this FileData to the associated {@link TreeFileDataNode}, from the hierarchical view.
     *
     * @return
     */
    public TreeFileDataNode getTreeFileDataNode();

    /**
     * Setters for the to the associated {@link TreeFileDataNode}, from the hierarchical view. Allows link between the
     * flat and hierarchical view.
     *
     * @return
     */
    public void setTreeFileDataNode(TreeFileDataNode node);
}