    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 this
    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     *
    061     * @throws UncheckedIOException if an I/O error occurs
    062     */
    063    byte[] get() throws UncheckedIOException;
    064
    065    /**
    066     * Gets the content type passed by the browser or {@code null} if not defined.
    067     *
    068     * @return The content type passed by the browser or {@code null} if not defined.
    069     */
    070    String getContentType();
    071
    072    /**
    073     * Gets the name of the field in the multipart form corresponding to this file item.
    074     *
    075     * @return The name of the form field.
    076     */
    077    String getFieldName();
    078
    079    /**
    080     * Gets an {@link java.io.InputStream InputStream} that can be used to retrieve the contents of the file.
    081     *
    082     * @return An {@link java.io.InputStream InputStream} that can be used to retrieve the contents of the file.
    083     *
    084     * @throws IOException if an error occurs.
    085     */
    086    InputStream getInputStream() throws IOException;
    087
    088    /**
    089     * 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
    090     * name, without path information. However, some clients, such as the Opera browser, do include path information.
    091     *
    092     * @return The original file name in the client's file system.
    093     * @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
    094     *                              anyways, catch the exception and use InvalidFileNameException#getName().
    095     */
    096    String getName();
    097
    098    /**
    099     * 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}