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