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    *   https://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.buffer.ByteBuf;
19  import io.netty.buffer.ByteBufHolder;
20  
21  import java.io.File;
22  import java.io.IOException;
23  import java.io.InputStream;
24  import java.nio.charset.Charset;
25  
26  /**
27   * Extended interface for InterfaceHttpData
28   */
29  public interface HttpData extends InterfaceHttpData, ByteBufHolder {
30  
31      /**
32       * Returns the maxSize for this HttpData.
33       */
34      long getMaxSize();
35  
36      /**
37       * Set the maxSize for this HttpData. When limit will be reached, an exception will be raised.
38       * Setting it to (-1) means no limitation.
39       *
40       * By default, to be set from the HttpDataFactory.
41       */
42      void setMaxSize(long maxSize);
43  
44      /**
45       * Check if the new size is not reaching the max limit allowed.
46       * The limit is always computed in terms of bytes.
47       */
48      void checkSize(long newSize) throws IOException;
49  
50      /**
51       * Set the content from the ChannelBuffer (erase any previous data)
52       * <p>{@link ByteBuf#release()} ownership of {@code buffer} is transferred to this {@link HttpData}.
53       *
54       * @param buffer
55       *            must be not null
56       * @throws IOException
57       */
58      void setContent(ByteBuf buffer) throws IOException;
59  
60      /**
61       * Add the content from the ChannelBuffer
62       * <p>{@link ByteBuf#release()} ownership of {@code buffer} is transferred to this {@link HttpData}.
63       *
64       * @param buffer
65       *            must be not null except if last is set to False
66       * @param last
67       *            True of the buffer is the last one
68       * @throws IOException
69       */
70      void addContent(ByteBuf buffer, boolean last) throws IOException;
71  
72      /**
73       * Set the content from the file (erase any previous data)
74       *
75       * @param file
76       *            must be not null
77       * @throws IOException
78       */
79      void setContent(File file) throws IOException;
80  
81      /**
82       * Set the content from the inputStream (erase any previous data)
83       *
84       * @param inputStream
85       *            must be not null
86       * @throws IOException
87       */
88      void setContent(InputStream inputStream) throws IOException;
89  
90      /**
91       *
92       * @return True if the InterfaceHttpData is completed (all data are stored)
93       */
94      boolean isCompleted();
95  
96      /**
97       * Returns the size in byte of the InterfaceHttpData
98       *
99       * @return the size of the InterfaceHttpData
100      */
101     long length();
102 
103     /**
104      * Returns the defined length of the HttpData.
105      *
106      * If no Content-Length is provided in the request, the defined length is
107      * always 0 (whatever during decoding or in final state).
108      *
109      * If Content-Length is provided in the request, this is this given defined length.
110      * This value does not change, whatever during decoding or in the final state.
111      *
112      * This method could be used for instance to know the amount of bytes transmitted for
113      * one particular HttpData, for example one {@link FileUpload} or any known big {@link Attribute}.
114      *
115      * @return the defined length of the HttpData
116      */
117     long definedLength();
118 
119     /**
120      * Deletes the underlying storage for a file item, including deleting any
121      * associated temporary disk file.
122      */
123     void delete();
124 
125     /**
126      * Returns the contents of the file item as an array of bytes.<br>
127      * Note: this method will allocate a lot of memory, if the data is currently stored on the file system.
128      *
129      * @return the contents of the file item as an array of bytes.
130      * @throws IOException
131      */
132     byte[] get() throws IOException;
133 
134     /**
135      * Returns the content of the file item as a ByteBuf.<br>
136      * Note: this method will allocate a lot of memory, if the data is currently stored on the file system.
137      *
138      * @return the content of the file item as a ByteBuf
139      * @throws IOException
140      */
141     ByteBuf getByteBuf() throws IOException;
142 
143     /**
144      * Returns a ChannelBuffer for the content from the current position with at
145      * most length read bytes, increasing the current position of the Bytes
146      * read. Once it arrives at the end, it returns an EMPTY_BUFFER and it
147      * resets the current position to 0.
148      *
149      * @return a ChannelBuffer for the content from the current position or an
150      *         EMPTY_BUFFER if there is no more data to return
151      */
152     ByteBuf getChunk(int length) throws IOException;
153 
154     /**
155      * Returns the contents of the file item as a String, using the default
156      * character encoding.
157      *
158      * @return the contents of the file item as a String, using the default
159      *         character encoding.
160      * @throws IOException
161      */
162     String getString() throws IOException;
163 
164     /**
165      * Returns the contents of the file item as a String, using the specified
166      * charset.
167      *
168      * @param encoding
169      *            the charset to use
170      * @return the contents of the file item as a String, using the specified
171      *         charset.
172      * @throws IOException
173      */
174     String getString(Charset encoding) throws IOException;
175 
176     /**
177      * Set the Charset passed by the browser if defined
178      *
179      * @param charset
180      *            Charset to set - must be not null
181      */
182     void setCharset(Charset charset);
183 
184     /**
185      * Returns the Charset passed by the browser or null if not defined.
186      *
187      * @return the Charset passed by the browser or null if not defined.
188      */
189     Charset getCharset();
190 
191     /**
192      * A convenience getMethod to write an uploaded item to disk. If a previous one
193      * exists, it will be deleted. Once this getMethod is called, if successful,
194      * the new file will be out of the cleaner of the factory that creates the
195      * original InterfaceHttpData object.
196      *
197      * @param dest
198      *            destination file - must be not null
199      * @return True if the write is successful
200      * @throws IOException
201      */
202     boolean renameTo(File dest) throws IOException;
203 
204     /**
205      * Provides a hint as to whether or not the file contents will be read from
206      * memory.
207      *
208      * @return True if the file contents is in memory.
209      */
210     boolean isInMemory();
211 
212     /**
213      *
214      * @return the associated File if this data is represented in a file
215      * @exception IOException
216      *                if this data is not represented by a file
217      */
218     File getFile() throws IOException;
219 
220     @Override
221     HttpData copy();
222 
223     @Override
224     HttpData duplicate();
225 
226     @Override
227     HttpData retainedDuplicate();
228 
229     @Override
230     HttpData replace(ByteBuf content);
231 
232     @Override
233     HttpData retain();
234 
235     @Override
236     HttpData retain(int increment);
237 
238     @Override
239     HttpData touch();
240 
241     @Override
242     HttpData touch(Object hint);
243 }