1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 package org.apache.commons.fileupload; 18 19 import java.io.File; 20 import java.io.IOException; 21 import java.io.InputStream; 22 import java.io.OutputStream; 23 import java.io.UnsupportedEncodingException; 24 25 /** 26 * <p> This class represents a file or form item that was received within a 27 * {@code multipart/form-data} POST request. 28 * 29 * <p> After retrieving an instance of this class from a {@link 30 * org.apache.commons.fileupload.FileUpload FileUpload} instance (see 31 * {@link org.apache.commons.fileupload.servlet.ServletFileUpload 32 * #parseRequest(javax.servlet.http.HttpServletRequest)}), you may 33 * either request all contents of the file at once using {@link #get()} or 34 * request an {@link java.io.InputStream InputStream} with 35 * {@link #getInputStream()} and process the file without attempting to load 36 * it into memory, which may come handy with large files. 37 * 38 * <p> While this interface does not extend 39 * {@code javax.activation.DataSource} per se (to avoid a seldom used 40 * dependency), several of the defined methods are specifically defined with 41 * the same signatures as methods in that interface. This allows an 42 * implementation of this interface to also implement 43 * {@code javax.activation.DataSource} with minimal additional work. 44 * 45 * @since 1.3 additionally implements FileItemHeadersSupport 46 */ 47 public interface FileItem extends FileItemHeadersSupport { 48 49 /** 50 * Deletes the underlying storage for a file item, including deleting any 51 * associated temporary disk file. Although this storage will be deleted 52 * automatically when the {@code FileItem} instance is garbage 53 * collected, this method can be used to ensure that this is done at an 54 * earlier time, thus preserving system resources. 55 */ 56 void delete(); 57 58 /** 59 * Returns the contents of the file item as an array of bytes. 60 * 61 * @return The contents of the file item as an array of bytes. 62 */ 63 byte[] get(); 64 65 /** 66 * Returns the content type passed by the browser or {@code null} if 67 * not defined. 68 * 69 * @return The content type passed by the browser or {@code null} if 70 * not defined. 71 */ 72 String getContentType(); 73 74 /** 75 * Returns the name of the field in the multipart form corresponding to 76 * this file item. 77 * 78 * @return The name of the form field. 79 */ 80 String getFieldName(); 81 82 /** 83 * Returns an {@link java.io.InputStream InputStream} that can be 84 * used to retrieve the contents of the file. 85 * 86 * @return An {@link java.io.InputStream InputStream} that can be 87 * used to retrieve the contents of the file. 88 * 89 * @throws IOException if an error occurs. 90 */ 91 InputStream getInputStream() throws IOException; 92 93 /** 94 * Returns the original file name in the client's file system, as provided by 95 * the browser (or other client software). In most cases, this will be the 96 * base file name, without path information. However, some clients, such as 97 * the Opera browser, do include path information. 98 * 99 * @return The original file name in the client's file system. 100 * @throws InvalidFileNameException The file name contains a NUL character, 101 * which might be an indicator of a security attack. If you intend to 102 * use the file name anyways, catch the exception and use 103 * InvalidFileNameException#getName(). 104 */ 105 String getName(); 106 107 /** 108 * Returns an {@link java.io.OutputStream OutputStream} that can 109 * be used for storing the contents of the file. 110 * 111 * @return An {@link java.io.OutputStream OutputStream} that can be used 112 * for storing the contents of the file. 113 * 114 * @throws IOException if an error occurs. 115 */ 116 OutputStream getOutputStream() throws IOException; 117 118 /** 119 * Returns the size of the file item. 120 * 121 * @return The size of the file item, in bytes. 122 */ 123 long getSize(); 124 125 /** 126 * Returns the contents of the file item as a String, using the default 127 * character encoding. This method uses {@link #get()} to retrieve the 128 * contents of the item. 129 * 130 * @return The contents of the item, as a string. 131 */ 132 String getString(); 133 134 /** 135 * Returns the contents of the file item as a String, using the specified 136 * encoding. This method uses {@link #get()} to retrieve the 137 * contents of the item. 138 * 139 * @param encoding The character encoding to use. 140 * @return The contents of the item, as a string. 141 * @throws UnsupportedEncodingException if the requested character 142 * encoding is not available. 143 */ 144 String getString(String encoding) throws UnsupportedEncodingException; 145 146 /** 147 * Determines whether or not a {@code FileItem} instance represents 148 * a simple form field. 149 * 150 * @return {@code true} if the instance represents a simple form 151 * field; {@code false} if it represents an uploaded file. 152 */ 153 boolean isFormField(); 154 155 /** 156 * Provides a hint as to whether or not the file contents will be read 157 * from memory. 158 * 159 * @return {@code true} if the file contents will be read from memory; 160 * {@code false} otherwise. 161 */ 162 boolean isInMemory(); 163 164 /** 165 * Sets the field name used to reference this file item. 166 * 167 * @param name The name of the form field. 168 */ 169 void setFieldName(String name); 170 171 /** 172 * Specifies whether or not a {@code FileItem} instance represents 173 * a simple form field. 174 * 175 * @param state {@code true} if the instance represents a simple form 176 * field; {@code false} if it represents an uploaded file. 177 */ 178 void setFormField(boolean state); 179 180 /** 181 * A convenience method to write an uploaded item to disk. The client code 182 * is not concerned with whether or not the item is stored in memory, or on 183 * disk in a temporary location. They just want to write the uploaded item 184 * to a file. 185 * <p> 186 * This method is not guaranteed to succeed if called more than once for 187 * the same item. This allows a particular implementation to use, for 188 * example, file renaming, where possible, rather than copying all of the 189 * underlying data, thus gaining a significant performance benefit. 190 * 191 * @param file The {@code File} into which the uploaded item should 192 * be stored. 193 * 194 * @throws Exception if an error occurs. 195 */ 196 void write(File file) throws Exception; 197 198 }