View Javadoc
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 (or for PUT, PATCH or OPTIONS).
24   *
25   * You <strong>MUST</strong> call {@link #destroy()} after completion to release all resources.
26   *
27   */
28  public interface InterfaceHttpPostRequestDecoder {
29      /**
30       * True if this request is a Multipart request
31       *
32       * @return True if this request is a Multipart request
33       */
34      boolean isMultipart();
35  
36      /**
37       * Set the amount of bytes after which read bytes in the buffer should be discarded.
38       * Setting this lower gives lower memory usage but with the overhead of more memory copies.
39       * Use {@code 0} to disable it.
40       */
41      void setDiscardThreshold(int discardThreshold);
42  
43      /**
44       * Return the threshold in bytes after which read data in the buffer should be discarded.
45       */
46      int getDiscardThreshold();
47  
48      /**
49       * This getMethod returns a List of all HttpDatas from body.<br>
50       *
51       * If chunked, all chunks must have been offered using offer() getMethod. If
52       * not, NotEnoughDataDecoderException will be raised.
53       *
54       * @return the list of HttpDatas from Body part for POST getMethod
55       * @throws HttpPostRequestDecoder.NotEnoughDataDecoderException
56       *             Need more chunks
57       */
58      List<InterfaceHttpData> getBodyHttpDatas();
59  
60      /**
61       * This getMethod returns a List of all HttpDatas with the given name from
62       * body.<br>
63       *
64       * If chunked, all chunks must have been offered using offer() getMethod. If
65       * not, NotEnoughDataDecoderException will be raised.
66       *
67       * @return All Body HttpDatas with the given name (ignore case)
68       * @throws HttpPostRequestDecoder.NotEnoughDataDecoderException
69       *             need more chunks
70       */
71      List<InterfaceHttpData> getBodyHttpDatas(String name);
72  
73      /**
74       * This getMethod returns the first InterfaceHttpData with the given name from
75       * body.<br>
76       *
77       * If chunked, all chunks must have been offered using offer() getMethod. If
78       * not, NotEnoughDataDecoderException will be raised.
79       *
80       * @return The first Body InterfaceHttpData with the given name (ignore
81       *         case)
82       * @throws HttpPostRequestDecoder.NotEnoughDataDecoderException
83       *             need more chunks
84       */
85      InterfaceHttpData getBodyHttpData(String name);
86  
87      /**
88       * Initialized the internals from a new chunk
89       *
90       * @param content
91       *            the new received chunk
92       * @throws HttpPostRequestDecoder.ErrorDataDecoderException
93       *             if there is a problem with the charset decoding or other
94       *             errors
95       */
96      InterfaceHttpPostRequestDecoder offer(HttpContent content);
97  
98      /**
99       * True if at current getStatus, there is an available decoded
100      * InterfaceHttpData from the Body.
101      *
102      * This getMethod works for chunked and not chunked request.
103      *
104      * @return True if at current getStatus, there is a decoded InterfaceHttpData
105      * @throws HttpPostRequestDecoder.EndOfDataDecoderException
106      *             No more data will be available
107      */
108     boolean hasNext();
109 
110     /**
111      * Returns the next available InterfaceHttpData or null if, at the time it
112      * is called, there is no more available InterfaceHttpData. A subsequent
113      * call to offer(httpChunk) could enable more data.
114      *
115      * Be sure to call {@link InterfaceHttpData#release()} after you are done
116      * with processing to make sure to not leak any resources
117      *
118      * @return the next available InterfaceHttpData or null if none
119      * @throws HttpPostRequestDecoder.EndOfDataDecoderException
120      *             No more data will be available
121      */
122     InterfaceHttpData next();
123 
124     /**
125      * Destroy the {@link InterfaceHttpPostRequestDecoder} and release all it resources. After this method
126      * was called it is not possible to operate on it anymore.
127      */
128     void destroy();
129 
130     /**
131      * Clean all HttpDatas (on Disk) for the current request.
132      */
133     void cleanFiles();
134 
135     /**
136      * Remove the given FileUpload from the list of FileUploads to clean
137      */
138     void removeHttpDataFromClean(InterfaceHttpData data);
139 }