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;
020
021import javax.naming.SizeLimitExceededException;
022
023import org.apache.commons.io.function.IOIterator;
024
025/**
026 * An iterator, as returned by {@link AbstractFileUpload#getItemIterator(RequestContext)}.
027 */
028public interface FileItemInputIterator extends IOIterator<FileItemInput> {
029
030    /**
031     * Gets the maximum size of a single file. An {@link FileUploadByteCountLimitException} will be thrown, if there is an uploaded file, which is exceeding
032     * this value. By default, this value will be copied from the {@link AbstractFileUpload#getFileSizeMax() FileUploadBase} object, however, the user may
033     * replace the default value with a request specific value by invoking {@link #setFileSizeMax(long)} on this object.
034     *
035     * @return The maximum size of a single, uploaded file. The value -1 indicates "unlimited".
036     */
037    long getFileSizeMax();
038
039    /**
040     * Gets the maximum size of the complete HTTP request. A {@link SizeLimitExceededException} will be thrown, if the HTTP request will exceed this value. By
041     * default, this value will be copied from the {@link AbstractFileUpload#getSizeMax() FileUploadBase} object, however, the user may replace the default
042     * value with a request specific value by invoking {@link #setSizeMax(long)} on this object.
043     *
044     * @return The maximum size of the complete HTTP request. The value -1 indicates "unlimited".
045     */
046    long getSizeMax();
047
048    /**
049     * Tests whether another instance of {@link FileItemInput} is available.
050     *
051     * @throws FileUploadException Parsing or processing the file item failed.
052     * @throws IOException         Reading the file item failed.
053     * @return True, if one or more additional file items are available, otherwise false.
054     */
055    @Override
056    boolean hasNext() throws IOException;
057
058    /**
059     * Returns the next available {@link FileItemInput}.
060     *
061     * @throws java.util.NoSuchElementException No more items are available. Use {@link #hasNext()} to prevent this exception.
062     * @throws FileUploadException              Parsing or processing the file item failed.
063     * @throws IOException                      Reading the file item failed.
064     * @return FileItemInput instance, which provides access to the next file item.
065     */
066    @Override
067    FileItemInput next() throws IOException;
068
069    /**
070     * Sets the maximum size of a single file. An {@link FileUploadByteCountLimitException} will be thrown, if there is an uploaded file, which is exceeding
071     * this value. By default, this value will be copied from the {@link AbstractFileUpload#getFileSizeMax() FileUploadBase} object, however, the user may
072     * replace the default value with a request specific value by invoking {@link #setFileSizeMax(long)} on this object, so there is no need to configure it
073     * here.
074     * <p>
075     * <em>Note:</em> Changing this value doesn't affect files, that have already been uploaded.
076     * </p>
077     *
078     * @param fileSizeMax The maximum size of a single, uploaded file. The value -1 indicates "unlimited".
079     */
080    void setFileSizeMax(long fileSizeMax);
081
082    /**
083     * Sets the maximum size of the complete HTTP request. A {@link SizeLimitExceededException} will be thrown, if the HTTP request will exceed this value. By
084     * default, this value will be copied from the {@link AbstractFileUpload#getSizeMax() FileUploadBase} object, however, the user may replace the default
085     * value with a request specific value by invoking {@link #setSizeMax(long)} on this object.
086     * <p>
087     * <em>Note:</em> Setting the maximum size on this object will work only, if the iterator is not yet initialized. In other words: If the methods
088     * {@link #hasNext()}, {@link #next()} have not yet been invoked.
089     * </p>
090     *
091     * @param sizeMax The maximum size of the complete HTTP request. The value -1 indicates "unlimited".
092     */
093    void setSizeMax(long sizeMax);
094}