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.fileupload2.core; 018 019import java.io.IOException; 020import java.io.InputStream; 021import java.io.OutputStream; 022import java.nio.charset.Charset; 023import java.nio.file.InvalidPathException; 024import java.nio.file.Path; 025 026/** 027 * <p> 028 * This class represents a file or form item that was received within a {@code multipart/form-data} POST request. 029 * </p> 030 * <p> 031 * After retrieving an instance of this class from a {@link AbstractFileUpload FileUpload} instance (see 032 * {@code org.apache.commons.fileupload2.core.servlet.ServletFileUpload #parseRequest(javax.servlet.http.HttpServletRequest)}), you may either request all 033 * contents of the file at once using {@link #get()} or request an {@link InputStream} with {@link #getInputStream()} and process the file without attempting to 034 * load it into memory, which may come handy with large files. 035 * </p> 036 * <p> 037 * While this interface does not extend {@code javax.activation.DataSource} (to avoid a seldom used dependency), several of the defined methods are specifically 038 * defined with the same signatures as methods in that interface. This allows an implementation of this interface to also implement 039 * {@code javax.activation.DataSource} with minimal additional work. 040 * </p> 041 * 042 * @param <F> The FileItem type. 043 */ 044public interface FileItem<F extends FileItem<F>> extends FileItemHeadersProvider<F> { 045 046 /** 047 * Deletes the underlying storage for a file item, including deleting any associated temporary disk file. Use this method to ensure that this is done at an 048 * earlier time, to preserve resources. 049 * 050 * @return {@code this} instance. 051 * @throws IOException if an error occurs. 052 */ 053 F delete() throws IOException; 054 055 /** 056 * Gets the contents of the file item as a byte array. 057 * 058 * @return The contents of the file item as a byte array. 059 * @throws IOException if an I/O error occurs 060 */ 061 byte[] get() throws IOException; 062 063 /** 064 * Gets the content type passed by the browser or {@code null} if not defined. 065 * 066 * @return The content type passed by the browser or {@code null} if not defined. 067 */ 068 String getContentType(); 069 070 /** 071 * Gets the name of the field in the multipart form corresponding to this file item. 072 * 073 * @return The name of the form field. 074 */ 075 String getFieldName(); 076 077 /** 078 * Gets an {@link java.io.InputStream InputStream} that can be used to retrieve the contents of the file. 079 * 080 * @return An {@link java.io.InputStream InputStream} that can be used to retrieve the contents of the file. 081 * @throws IOException if an error occurs. 082 */ 083 InputStream getInputStream() throws IOException; 084 085 /** 086 * Gets the original file name in the client's file system, as provided by the browser (or other client software). In most cases, this will be the base file 087 * name, without path information. However, some clients, such as the Opera browser, do include path information. 088 * 089 * @return The original file name in the client's file system. 090 * @throws InvalidPathException The file name contains a NUL character, which might be an indicator of a security attack. If you intend to use the file name 091 * anyways, catch the exception and use InvalidFileNameException#getName(). 092 */ 093 String getName(); 094 095 /** 096 * Gets an {@link java.io.OutputStream OutputStream} that can be used for storing the contents of the file. 097 * 098 * @return An {@link java.io.OutputStream OutputStream} that can be used for storing the contents of the file. 099 * @throws IOException if an error occurs. 100 */ 101 OutputStream getOutputStream() throws IOException; 102 103 /** 104 * Gets the size of the file item. 105 * 106 * @return The size of the file item, in bytes. 107 */ 108 long getSize(); 109 110 /** 111 * Gets the contents of the file item as a String, using the default character encoding. This method uses {@link #get()} to retrieve the contents of the 112 * item. 113 * 114 * @return The contents of the item, as a string. 115 * 116 * @throws IOException if an I/O error occurs 117 */ 118 String getString() throws IOException; 119 120 /** 121 * Gets the contents of the file item as a String, using the specified encoding. This method uses {@link #get()} to retrieve the contents of the item. 122 * 123 * @param toCharset The character encoding to use. 124 * @return The contents of the item, as a string. 125 * @throws IOException if an I/O error occurs 126 */ 127 String getString(Charset toCharset) throws IOException; 128 129 /** 130 * Tests whether or not a {@code FileItem} instance represents a simple form field. 131 * 132 * @return {@code true} if the instance represents a simple form field; {@code false} if it represents an uploaded file. 133 */ 134 boolean isFormField(); 135 136 /** 137 * Tests a hint as to whether or not the file contents will be read from memory. 138 * 139 * @return {@code true} if the file contents will be read from memory; {@code false} otherwise. 140 */ 141 boolean isInMemory(); 142 143 /** 144 * Sets the field name used to reference this file item. 145 * 146 * @param name The name of the form field. 147 * @return {@code this} instance. 148 */ 149 F setFieldName(String name); 150 151 /** 152 * Sets whether or not a {@code FileItem} instance represents a simple form field. 153 * 154 * @param state {@code true} if the instance represents a simple form field; {@code false} if it represents an uploaded file. 155 * @return {@code this} instance. 156 */ 157 F setFormField(boolean state); 158 159 /** 160 * Writes an uploaded item to disk. 161 * <p> 162 * The client code is not concerned with whether or not the item is stored in memory, or on disk in a temporary location. They just want to write the 163 * uploaded item to a file. 164 * </p> 165 * <p> 166 * This method is not guaranteed to succeed if called more than once for the same item. This allows a particular implementation to use, for example, file 167 * renaming, where possible, rather than copying all of the underlying data, thus gaining a significant performance benefit. 168 * </p> 169 * 170 * @param file The {@code File} into which the uploaded item should be stored. 171 * @throws IOException if an error occurs. 172 * @return {@code this} instance. 173 */ 174 F write(Path file) throws IOException; 175 176}