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.
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      * Returns the current InterfaceHttpData if currently in decoding status,
125      * meaning all data are not yet within, or null if there is no InterfaceHttpData
126      * currently in decoding status (either because none yet decoded or none currently partially
127      * decoded). Full decoded ones are accessible through hasNext() and next() methods.
128      *
129      * @return the current InterfaceHttpData if currently in decoding status or null if none.
130      */
131     InterfaceHttpData currentPartialHttpData();
132 
133     /**
134      * Destroy the {@link InterfaceHttpPostRequestDecoder} and release all it resources. After this method
135      * was called it is not possible to operate on it anymore.
136      */
137     void destroy();
138 
139     /**
140      * Clean all HttpDatas (on Disk) for the current request.
141      */
142     void cleanFiles();
143 
144     /**
145      * Remove the given FileUpload from the list of FileUploads to clean
146      */
147     void removeHttpDataFromClean(InterfaceHttpData data);
148 }