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.fileupload2.core;
18
19 import java.io.IOException;
20 import java.io.InputStream;
21 import java.io.OutputStream;
22 import java.io.UncheckedIOException;
23 import java.nio.charset.Charset;
24 import java.nio.file.InvalidPathException;
25 import java.nio.file.Path;
26
27 /**
28 * <p>
29 * This class represents a file or form item that was received within a {@code multipart/form-data} POST request.
30 * </p>
31 * <p>
32 * After retrieving an instance of this class from a {@link AbstractFileUpload FileUpload} instance (see
33 * {@code org.apache.commons.fileupload2.core.servlet.ServletFileUpload #parseRequest(javax.servlet.http.HttpServletRequest)}), you may either request all
34 * contents of the file at once using {@link #get()} or request an {@link InputStream} with {@link #getInputStream()} and process the file without attempting to
35 * load it into memory, which may come handy with large files.
36 * </p>
37 * <p>
38 * While this interface does not extend {@code javax.activation.DataSource} (to avoid a seldom used dependency), several of the defined methods are specifically
39 * defined with the same signatures as methods in that interface. This allows an implementation of this interface to also implement
40 * {@code javax.activation.DataSource} with minimal additional work.
41 * </p>
42 *
43 * @param <F> The FileItem type.
44 */
45 public interface FileItem<F extends FileItem<F>> extends FileItemHeadersProvider<F> {
46
47 /**
48 * 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
49 * earlier time, to preserve resources.
50 *
51 * @return this
52 * @throws IOException if an error occurs.
53 */
54 F delete() throws IOException;
55
56 /**
57 * Gets the contents of the file item as a byte array.
58 *
59 * @return The contents of the file item as a byte array.
60 *
61 * @throws UncheckedIOException if an I/O error occurs
62 */
63 byte[] get() throws UncheckedIOException;
64
65 /**
66 * Gets the content type passed by the browser or {@code null} if not defined.
67 *
68 * @return The content type passed by the browser or {@code null} if not defined.
69 */
70 String getContentType();
71
72 /**
73 * Gets the name of the field in the multipart form corresponding to this file item.
74 *
75 * @return The name of the form field.
76 */
77 String getFieldName();
78
79 /**
80 * Gets an {@link java.io.InputStream InputStream} that can be used to retrieve the contents of the file.
81 *
82 * @return An {@link java.io.InputStream InputStream} that can be used to retrieve the contents of the file.
83 *
84 * @throws IOException if an error occurs.
85 */
86 InputStream getInputStream() throws IOException;
87
88 /**
89 * 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
90 * name, without path information. However, some clients, such as the Opera browser, do include path information.
91 *
92 * @return The original file name in the client's file system.
93 * @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
94 * anyways, catch the exception and use InvalidFileNameException#getName().
95 */
96 String getName();
97
98 /**
99 * Gets an {@link java.io.OutputStream OutputStream} that can be used for storing the contents of the file.
100 *
101 * @return An {@link java.io.OutputStream OutputStream} that can be used for storing the contents of the file.
102 *
103 * @throws IOException if an error occurs.
104 */
105 OutputStream getOutputStream() throws IOException;
106
107 /**
108 * Gets the size of the file item.
109 *
110 * @return The size of the file item, in bytes.
111 */
112 long getSize();
113
114 /**
115 * 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
116 * item.
117 *
118 * @return The contents of the item, as a string.
119 */
120 String getString();
121
122 /**
123 * 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.
124 *
125 * @param toCharset The character encoding to use.
126 *
127 * @return The contents of the item, as a string.
128 *
129 * @throws IOException if an I/O error occurs
130 */
131 String getString(Charset toCharset) throws IOException;
132
133 /**
134 * Tests whether or not a {@code FileItem} instance represents a simple form field.
135 *
136 * @return {@code true} if the instance represents a simple form field; {@code false} if it represents an uploaded file.
137 */
138 boolean isFormField();
139
140 /**
141 * Tests a hint as to whether or not the file contents will be read from memory.
142 *
143 * @return {@code true} if the file contents will be read from memory; {@code false} otherwise.
144 */
145 boolean isInMemory();
146
147 /**
148 * Sets the field name used to reference this file item.
149 *
150 * @param name The name of the form field.
151 * @return this
152 */
153 F setFieldName(String name);
154
155 /**
156 * Sets whether or not a {@code FileItem} instance represents a simple form field.
157 *
158 * @param state {@code true} if the instance represents a simple form field; {@code false} if it represents an uploaded file.
159 * @return this
160 */
161 F setFormField(boolean state);
162
163 /**
164 * Writes an uploaded item to disk.
165 * <p>
166 * 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
167 * uploaded item to a file.
168 * </p>
169 * <p>
170 * 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
171 * renaming, where possible, rather than copying all of the underlying data, thus gaining a significant performance benefit.
172 * </p>
173 *
174 * @param file The {@code File} into which the uploaded item should be stored.
175 * @throws IOException if an error occurs.
176 * @return this
177 */
178 F write(Path file) throws IOException;
179
180 }