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
21 import javax.naming.SizeLimitExceededException;
22
23 import org.apache.commons.io.function.IOIterator;
24
25 /**
26 * An iterator, as returned by {@link AbstractFileUpload#getItemIterator(RequestContext)}.
27 */
28 public interface FileItemInputIterator extends IOIterator<FileItemInput> {
29
30 /**
31 * Gets the maximum size of a single file. An {@link FileUploadByteCountLimitException} will be thrown, if there is an uploaded file, which is exceeding
32 * this value. By default, this value will be copied from the {@link AbstractFileUpload#getFileSizeMax() FileUploadBase} object, however, the user may
33 * replace the default value with a request specific value by invoking {@link #setFileSizeMax(long)} on this object.
34 *
35 * @return The maximum size of a single, uploaded file. The value -1 indicates "unlimited".
36 */
37 long getFileSizeMax();
38
39 /**
40 * Gets the maximum size of the complete HTTP request. A {@link SizeLimitExceededException} will be thrown, if the HTTP request will exceed this value. By
41 * default, this value will be copied from the {@link AbstractFileUpload#getSizeMax() FileUploadBase} object, however, the user may replace the default
42 * value with a request specific value by invoking {@link #setSizeMax(long)} on this object.
43 *
44 * @return The maximum size of the complete HTTP request. The value -1 indicates "unlimited".
45 */
46 long getSizeMax();
47
48 /**
49 * Tests whether another instance of {@link FileItemInput} is available.
50 *
51 * @throws FileUploadException Parsing or processing the file item failed.
52 * @throws IOException Reading the file item failed.
53 * @return True, if one or more additional file items are available, otherwise false.
54 */
55 @Override
56 boolean hasNext() throws IOException;
57
58 /**
59 * Returns the next available {@link FileItemInput}.
60 *
61 * @throws java.util.NoSuchElementException No more items are available. Use {@link #hasNext()} to prevent this exception.
62 * @throws FileUploadException Parsing or processing the file item failed.
63 * @throws IOException Reading the file item failed.
64 * @return FileItemInput instance, which provides access to the next file item.
65 */
66 @Override
67 FileItemInput next() throws IOException;
68
69 /**
70 * Sets the maximum size of a single file. An {@link FileUploadByteCountLimitException} will be thrown, if there is an uploaded file, which is exceeding
71 * this value. By default, this value will be copied from the {@link AbstractFileUpload#getFileSizeMax() FileUploadBase} object, however, the user may
72 * 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
73 * here.
74 * <p>
75 * <em>Note:</em> Changing this value doesn't affect files, that have already been uploaded.
76 * </p>
77 *
78 * @param fileSizeMax The maximum size of a single, uploaded file. The value -1 indicates "unlimited".
79 */
80 void setFileSizeMax(long fileSizeMax);
81
82 /**
83 * Sets the maximum size of the complete HTTP request. A {@link SizeLimitExceededException} will be thrown, if the HTTP request will exceed this value. By
84 * default, this value will be copied from the {@link AbstractFileUpload#getSizeMax() FileUploadBase} object, however, the user may replace the default
85 * value with a request specific value by invoking {@link #setSizeMax(long)} on this object.
86 * <p>
87 * <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
88 * {@link #hasNext()}, {@link #next()} have not yet been invoked.
89 * </p>
90 *
91 * @param sizeMax The maximum size of the complete HTTP request. The value -1 indicates "unlimited".
92 */
93 void setSizeMax(long sizeMax);
94 }