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
    22  /**
    23   * Provides access to a file or form item that was received within a {@code multipart/form-data} POST request.
    24   * <p>
    25   * The items contents are retrieved by calling {@link #getInputStream()}.
    26   * </p>
    27   * <p>
    28   * Instances of this class are created by accessing the iterator, returned by {@link AbstractFileUpload#getItemIterator(RequestContext)}.
    29   * </p>
    30   * <p>
    31   * <em>Note</em>: There is an interaction between the iterator and its associated instances of {@link FileItemInput}: By invoking
    32   * {@link java.util.Iterator#hasNext()} on the iterator, you discard all data, which hasn't been read so far from the previous data.
    33   * </p>
    34   */
    35  public interface FileItemInput extends FileItemHeadersProvider<FileItemInput> {
    36
    37      /**
    38       * This exception is thrown, if an attempt is made to read data from the {@link InputStream}, which has been returned by
    39       * {@link FileItemInput#getInputStream()}, after {@link java.util.Iterator#hasNext()} has been invoked on the iterator, which created the
    40       * {@link FileItemInput}.
    41       */
    42      class ItemSkippedException extends FileUploadException {
    43
    44          /**
    45           * The exceptions serial version UID, which is being used when serializing an exception instance.
    46           */
    47          private static final long serialVersionUID = 2;
    48
    49          /**
    50           * Constructs an instance with a given detail message.
    51           *
    52           * @param message The detail message (which is saved for later retrieval by the {@link #getMessage()} method)
    53           */
    54          ItemSkippedException(final String message) {
    55              super(message);
    56          }
    57
    58      }
    59
    60      /**
    61       * Gets the content type passed by the browser or {@code null} if not defined.
    62       *
    63       * @return The content type passed by the browser or {@code null} if not defined.
    64       */
    65      String getContentType();
    66
    67      /**
    68       * Gets the name of the field in the multipart form corresponding to this file item.
    69       *
    70       * @return The name of the form field.
    71       */
    72      String getFieldName();
    73
    74      /**
    75       * Opens an {@link InputStream}, which allows to read the items contents.
    76       *
    77       * @return The input stream, from which the items data may be read.
    78       * @throws IllegalStateException The method was already invoked on this item. It is not possible to recreate the data stream.
    79       * @throws IOException           An I/O error occurred.
    80       * @see ItemSkippedException
    81       */
    82      InputStream getInputStream() throws IOException;
    83
    84      /**
    85       * 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
    86       * name, without path information. However, some clients, such as the Opera browser, do include path information.
    87       *
    88       * @return The original file name in the client's file system.
    89       */
    90      String getName();
    91
    92      /**
    93       * Tests whether or not a {@code FileItem} instance represents a simple form field.
    94       *
    95       * @return {@code true} if the instance represents a simple form field; {@code false} if it represents an uploaded file.
    96       */
    97      boolean isFormField();
    98
    99  }