001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.commons.fileupload; 018 019import java.io.File; 020import java.io.IOException; 021import java.io.InputStream; 022import java.io.OutputStream; 023import java.io.UnsupportedEncodingException; 024 025/** 026 * <p> This class represents a file or form item that was received within a 027 * {@code multipart/form-data} POST request. 028 * 029 * <p> After retrieving an instance of this class from a {@link 030 * org.apache.commons.fileupload.FileUpload FileUpload} instance (see 031 * {@link org.apache.commons.fileupload.servlet.ServletFileUpload 032 * #parseRequest(javax.servlet.http.HttpServletRequest)}), you may 033 * either request all contents of the file at once using {@link #get()} or 034 * request an {@link java.io.InputStream InputStream} with 035 * {@link #getInputStream()} and process the file without attempting to load 036 * it into memory, which may come handy with large files. 037 * 038 * <p> While this interface does not extend 039 * {@code javax.activation.DataSource} per se (to avoid a seldom used 040 * dependency), several of the defined methods are specifically defined with 041 * the same signatures as methods in that interface. This allows an 042 * implementation of this interface to also implement 043 * {@code javax.activation.DataSource} with minimal additional work. 044 * 045 * @since 1.3 additionally implements FileItemHeadersSupport 046 */ 047public interface FileItem extends FileItemHeadersSupport { 048 049 /** 050 * Deletes the underlying storage for a file item, including deleting any 051 * associated temporary disk file. Although this storage will be deleted 052 * automatically when the {@code FileItem} instance is garbage 053 * collected, this method can be used to ensure that this is done at an 054 * earlier time, thus preserving system resources. 055 */ 056 void delete(); 057 058 /** 059 * Returns the contents of the file item as an array of bytes. 060 * 061 * @return The contents of the file item as an array of bytes. 062 */ 063 byte[] get(); 064 065 /** 066 * Returns the content type passed by the browser or {@code null} if 067 * not defined. 068 * 069 * @return The content type passed by the browser or {@code null} if 070 * not defined. 071 */ 072 String getContentType(); 073 074 /** 075 * Returns the name of the field in the multipart form corresponding to 076 * this file item. 077 * 078 * @return The name of the form field. 079 */ 080 String getFieldName(); 081 082 /** 083 * Returns an {@link java.io.InputStream InputStream} that can be 084 * used to retrieve the contents of the file. 085 * 086 * @return An {@link java.io.InputStream InputStream} that can be 087 * used to retrieve the contents of the file. 088 * 089 * @throws IOException if an error occurs. 090 */ 091 InputStream getInputStream() throws IOException; 092 093 /** 094 * Returns the original file name in the client's file system, as provided by 095 * the browser (or other client software). In most cases, this will be the 096 * base file name, without path information. However, some clients, such as 097 * the Opera browser, do include path information. 098 * 099 * @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}