001 package de.deepamehta.plugins.files;
002
003 import org.apache.commons.fileupload.FileItem;
004
005 import java.io.File;
006 import 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("de.deepamehta.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 */
022 public class UploadedFile {
023
024 // ---------------------------------------------------------------------------------------------- Instance Variables
025
026 private FileItem fileItem;
027
028 // ---------------------------------------------------------------------------------------------------- Constructors
029
030 public UploadedFile(FileItem fileItem) {
031 this.fileItem = fileItem;
032 }
033
034 // -------------------------------------------------------------------------------------------------- Public Methods
035
036 // === File Metadata ===
037
038 /**
039 * Returns the original filename in the client's filesystem, as provided by the browser (or other client software).
040 * In most cases, this will be the base file name, without path information. However, some clients, such as the
041 * Opera browser, do include path information.
042 */
043 public String getName() {
044 return fileItem.getName();
045 }
046
047 /**
048 * Returns the size of the file.
049 */
050 public long getSize() {
051 return fileItem.getSize();
052 }
053
054 /**
055 * Returns the content type passed by the browser or <code>null</code> if not defined.
056 */
057 public String getMediaType() {
058 return fileItem.getContentType();
059 }
060
061 // === File Content ===
062
063 /**
064 * Returns the contents of the uploaded file as a String, using the default character encoding.
065 */
066 public String getString() {
067 return fileItem.getString();
068 }
069
070 /**
071 * Returns the contents of the uploaded file as a String, using the specified encoding.
072 */
073 public String getString(String encoding) {
074 try {
075 return fileItem.getString(encoding); // throws UnsupportedEncodingException
076 } catch (Exception e) {
077 throw new RuntimeException("Getting contents of uploaded file failed (" + this + ")", e);
078 }
079 }
080
081 /**
082 * Returns the contents of the uploaded file as an array of bytes.
083 */
084 public byte[] getBytes() {
085 return fileItem.get();
086 }
087
088 /**
089 * Returns an InputStream that can be used to retrieve the contents of the uploaded file.
090 */
091 public InputStream getInputStream() {
092 try {
093 return fileItem.getInputStream(); // throws IOException
094 } catch (Exception e) {
095 throw new RuntimeException("Getting input stream of uploaded file failed (" + this + ")", e);
096 }
097 }
098
099 // === Storage ===
100
101 /**
102 * A convenience method to write the uploaded file to disk.
103 */
104 public void write(File file) {
105 try {
106 fileItem.write(file); // throws Exception
107 } catch (Exception e) {
108 throw new RuntimeException("Writing uploaded file to disk failed (" + this + ")", e);
109 }
110 }
111
112 // ===
113
114 @Override
115 public String toString() {
116 return "file \"" + getName() + "\" (" + getMediaType() + "), " + getSize() + " bytes";
117 }
118 }