    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;
    021
    022/**
    023 * Provides access to a file or form item that was received within a {@code multipart/form-data} POST request.
    024 * <p>
    025 * The items contents are retrieved by calling {@link #getInputStream()}.
    026 * </p>
    027 * <p>
    028 * Instances of this class are created by accessing the iterator, returned by {@link AbstractFileUpload#getItemIterator(RequestContext)}.
    029 * </p>
    030 * <p>
    031 * <em>Note</em>: There is an interaction between the iterator and its associated instances of {@link FileItemInput}: By invoking
    032 * {@link java.util.Iterator#hasNext()} on the iterator, you discard all data, which hasn't been read so far from the previous data.
    033 * </p>
    034 */
    035public interface FileItemInput extends FileItemHeadersProvider<FileItemInput> {
    036
    037    /**
    038     * This exception is thrown, if an attempt is made to read data from the {@link InputStream}, which has been returned by
    039     * {@link FileItemInput#getInputStream()}, after {@link java.util.Iterator#hasNext()} has been invoked on the iterator, which created the
    040     * {@link FileItemInput}.
    041     */
    042    class ItemSkippedException extends FileUploadException {
    043
    044        /**
    045         * The exceptions serial version UID, which is being used when serializing an exception instance.
    046         */
    047        private static final long serialVersionUID = 2;
    048
    049        /**
    050         * Constructs an instance with a given detail message.
    051         *
    052         * @param message The detail message (which is saved for later retrieval by the {@link #getMessage()} method)
    053         */
    054        ItemSkippedException(final String message) {
    055            super(message);
    056        }
    057
    058    }
    059
    060    /**
    061     * Gets the content type passed by the browser or {@code null} if not defined.
    062     *
    063     * @return The content type passed by the browser or {@code null} if not defined.
    064     */
    065    String getContentType();
    066
    067    /**
    068     * Gets the name of the field in the multipart form corresponding to this file item.
    069     *
    070     * @return The name of the form field.
    071     */
    072    String getFieldName();
    073
    074    /**
    075     * Opens an {@link InputStream}, which allows to read the items contents.
    076     *
    077     * @return The input stream, from which the items data may be read.
    078     * @throws IllegalStateException The method was already invoked on this item. It is not possible to recreate the data stream.
    079     * @throws IOException           An I/O error occurred.
    080     * @see ItemSkippedException
    081     */
    082    InputStream getInputStream() throws IOException;
    083
    084    /**
    085     * 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
    086     * name, without path information. However, some clients, such as the Opera browser, do include path information.
    087     *
    088     * @return The original file name in the client's file system.
    089     */
    090    String getName();
    091
    092    /**
    093     * Tests whether or not a {@code FileItem} instance represents a simple form field.
    094     *
    095     * @return {@code true} if the instance represents a simple form field; {@code false} if it represents an uploaded file.
    096     */
    097    boolean isFormField();
    098
    099}