1 /*
2 * Copyright 2012 The Netty Project
3 *
4 * The Netty Project licenses this file to you under the Apache License,
5 * version 2.0 (the "License"); you may not use this file except in compliance
6 * with the License. You may obtain a copy of the License at:
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations
14 * under the License.
15 */
16 package io.netty.handler.codec.http.multipart;
17
18 import io.netty.handler.codec.http.HttpContent;
19
20 import java.util.List;
21
22 /**
23 * This decoder will decode Body and can handle POST BODY.
24 *
25 * You <strong>MUST</strong> call {@link #destroy()} after completion to release all resources.
26 */
27 public interface InterfaceHttpPostRequestDecoder {
28 /**
29 * True if this request is a Multipart request
30 *
31 * @return True if this request is a Multipart request
32 */
33 boolean isMultipart();
34
35 /**
36 * Set the amount of bytes after which read bytes in the buffer should be discarded.
37 * Setting this lower gives lower memory usage but with the overhead of more memory copies.
38 * Use {@code 0} to disable it.
39 */
40 void setDiscardThreshold(int discardThreshold);
41
42 /**
43 * Return the threshold in bytes after which read data in the buffer should be discarded.
44 */
45 int getDiscardThreshold();
46
47 /**
48 * This getMethod returns a List of all HttpDatas from body.<br>
49 *
50 * If chunked, all chunks must have been offered using offer() getMethod. If
51 * not, NotEnoughDataDecoderException will be raised.
52 *
53 * @return the list of HttpDatas from Body part for POST getMethod
54 * @throws HttpPostRequestDecoder.NotEnoughDataDecoderException
55 * Need more chunks
56 */
57 List<InterfaceHttpData> getBodyHttpDatas();
58
59 /**
60 * This getMethod returns a List of all HttpDatas with the given name from
61 * body.<br>
62 *
63 * If chunked, all chunks must have been offered using offer() getMethod. If
64 * not, NotEnoughDataDecoderException will be raised.
65 *
66 * @return All Body HttpDatas with the given name (ignore case)
67 * @throws HttpPostRequestDecoder.NotEnoughDataDecoderException
68 * need more chunks
69 */
70 List<InterfaceHttpData> getBodyHttpDatas(String name);
71
72 /**
73 * This getMethod returns the first InterfaceHttpData with the given name from
74 * body.<br>
75 *
76 * If chunked, all chunks must have been offered using offer() getMethod. If
77 * not, NotEnoughDataDecoderException will be raised.
78 *
79 * @return The first Body InterfaceHttpData with the given name (ignore
80 * case)
81 * @throws HttpPostRequestDecoder.NotEnoughDataDecoderException
82 * need more chunks
83 */
84 InterfaceHttpData getBodyHttpData(String name);
85
86 /**
87 * Initialized the internals from a new chunk
88 *
89 * @param content
90 * the new received chunk
91 * @throws HttpPostRequestDecoder.ErrorDataDecoderException
92 * if there is a problem with the charset decoding or other
93 * errors
94 */
95 InterfaceHttpPostRequestDecoder offer(HttpContent content);
96
97 /**
98 * True if at current getStatus, there is an available decoded
99 * InterfaceHttpData from the Body.
100 *
101 * This getMethod works for chunked and not chunked request.
102 *
103 * @return True if at current getStatus, there is a decoded InterfaceHttpData
104 * @throws HttpPostRequestDecoder.EndOfDataDecoderException
105 * No more data will be available
106 */
107 boolean hasNext();
108
109 /**
110 * Returns the next available InterfaceHttpData or null if, at the time it
111 * is called, there is no more available InterfaceHttpData. A subsequent
112 * call to offer(httpChunk) could enable more data.
113 *
114 * Be sure to call {@link InterfaceHttpData#release()} after you are done
115 * with processing to make sure to not leak any resources
116 *
117 * @return the next available InterfaceHttpData or null if none
118 * @throws HttpPostRequestDecoder.EndOfDataDecoderException
119 * No more data will be available
120 */
121 InterfaceHttpData next();
122
123 /**
124 * Destroy the {@link InterfaceHttpPostRequestDecoder} and release all it resources. After this method
125 * was called it is not possible to operate on it anymore.
126 */
127 void destroy();
128
129 /**
130 * Clean all HttpDatas (on Disk) for the current request.
131 */
132 void cleanFiles();
133
134 /**
135 * Remove the given FileUpload from the list of FileUploads to clean
136 */
137 void removeHttpDataFromClean(InterfaceHttpData data);
138 }