View Javadoc

    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 }