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 }