001package systems.dmx.files;
002
003import org.apache.commons.fileupload.FileItem;
004
005import java.io.File;
006import java.io.InputStream;
007
008
009
010/**
011 * An uploaded file.
012 * <p>
013 * Files are uploaded via the REST API by POSTing <code>multipart/form-data</code> to a resource method
014 * which consumes <code>multipart/form-data</code> and has UploadedFile as its entity parameter.
015 * <p>
016 * Client-side support: the public API of the Files plugin provides a method
017 * <code>dm4c.get_plugin("systems.dmx.files").open_upload_dialog()</code> that allows the user to
018 * choose and upload a file.</p>
019 *
020 * @author <a href="mailto:jri@deepamehta.de">Jörg Richter</a>
021 */
022public class UploadedFile {
023
024    // ---------------------------------------------------------------------------------------------- Instance Variables
025
026    private FileItem fileItem;
027    private DiskQuotaCheck diskQuotaCheck;
028
029    // ---------------------------------------------------------------------------------------------------- Constructors
030
031    public UploadedFile(FileItem fileItem, DiskQuotaCheck diskQuotaCheck) {
032        this.fileItem = fileItem;
033        this.diskQuotaCheck = diskQuotaCheck;
034    }
035
036    // -------------------------------------------------------------------------------------------------- Public Methods
037
038
039
040    // === File Metadata ===
041
042    /**
043     * Returns the original filename in the client's filesystem, as provided by the browser (or other client software).
044     * In most cases, this will be the base file name, without path information. However, some clients, such as the
045     * Opera browser, do include path information.
046     */
047    public String getName() {
048        return fileItem.getName();
049    }
050
051    /**
052     * Returns the size of the file.
053     */
054    public long getSize() {
055        return fileItem.getSize();
056    }
057
058    /**
059     * Returns the content type passed by the browser or <code>null</code> if not defined.
060     */
061    public String getMediaType() {
062        return fileItem.getContentType();
063    }
064
065
066
067    // === File Content ===
068
069    /**
070     * Returns the contents of the uploaded file as a String, using the default character encoding.
071     */
072    public String getString() {
073        return fileItem.getString();
074    }
075
076    /**
077     * Returns the contents of the uploaded file as a String, using the specified encoding.
078     */
079    public String getString(String encoding) {
080        try {
081            return fileItem.getString(encoding);    // throws UnsupportedEncodingException
082        } catch (Exception e) {
083            throw new RuntimeException("Getting contents of uploaded file failed (" + this + ")", e);
084        }
085    }
086
087    /**
088     * Returns the contents of the uploaded file as an array of bytes.
089     */
090    public byte[] getBytes() {
091        return fileItem.get();
092    }
093
094    /**
095     * Returns an InputStream that can be used to retrieve the contents of the uploaded file.
096     */
097    public InputStream getInputStream() {
098        try {
099            return fileItem.getInputStream();       // throws IOException
100        } catch (Exception e) {
101            throw new RuntimeException("Getting input stream of uploaded file failed (" + this + ")", e);
102        }
103    }
104
105
106
107    // === Storage ===
108
109    /**
110     * A convenience method to write the uploaded file to disk.
111     */
112    public void write(File file) {
113        try {
114            diskQuotaCheck.check(getSize());
115            fileItem.write(file);                   // throws Exception
116        } catch (Exception e) {
117            throw new RuntimeException("Writing uploaded file to disk failed (" + this + ")", e);
118        }
119    }
120
121
122
123    // === Java API ===
124
125    @Override
126    public String toString() {
127        return "file \"" + getName() + "\" (" + getMediaType() + ", " + getSize() + " bytes)";
128    }
129}