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