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       * @exception 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       * @exception 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       * @exception 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       * @exception 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      * Deletes the underlying storage for a file item, including deleting any
103      * associated temporary disk file.
104      */
105     void delete();
106 
107     /**
108      * Returns the contents of the file item as an array of bytes.
109      *
110      * @return the contents of the file item as an array of bytes.
111      * @exception IOException
112      */
113     byte[] get() throws IOException;
114 
115     /**
116      * Returns the content of the file item as a ByteBuf
117      *
118      * @return the content of the file item as a ByteBuf
119      * @throws IOException
120      */
121     ByteBuf getByteBuf() throws IOException;
122 
123     /**
124      * Returns a ChannelBuffer for the content from the current position with at
125      * most length read bytes, increasing the current position of the Bytes
126      * read. Once it arrives at the end, it returns an EMPTY_BUFFER and it
127      * resets the current position to 0.
128      *
129      * @return a ChannelBuffer for the content from the current position or an
130      *         EMPTY_BUFFER if there is no more data to return
131      */
132     ByteBuf getChunk(int length) throws IOException;
133 
134     /**
135      * Returns the contents of the file item as a String, using the default
136      * character encoding.
137      *
138      * @return the contents of the file item as a String, using the default
139      *         character encoding.
140      * @exception IOException
141      */
142     String getString() throws IOException;
143 
144     /**
145      * Returns the contents of the file item as a String, using the specified
146      * charset.
147      *
148      * @param encoding
149      *            the charset to use
150      * @return the contents of the file item as a String, using the specified
151      *         charset.
152      * @exception IOException
153      */
154     String getString(Charset encoding) throws IOException;
155 
156     /**
157      * Set the Charset passed by the browser if defined
158      *
159      * @param charset
160      *            Charset to set - must be not null
161      */
162     void setCharset(Charset charset);
163 
164     /**
165      * Returns the Charset passed by the browser or null if not defined.
166      *
167      * @return the Charset passed by the browser or null if not defined.
168      */
169     Charset getCharset();
170 
171     /**
172      * A convenience getMethod to write an uploaded item to disk. If a previous one
173      * exists, it will be deleted. Once this getMethod is called, if successful,
174      * the new file will be out of the cleaner of the factory that creates the
175      * original InterfaceHttpData object.
176      *
177      * @param dest
178      *            destination file - must be not null
179      * @return True if the write is successful
180      * @exception IOException
181      */
182     boolean renameTo(File dest) throws IOException;
183 
184     /**
185      * Provides a hint as to whether or not the file contents will be read from
186      * memory.
187      *
188      * @return True if the file contents is in memory.
189      */
190     boolean isInMemory();
191 
192     /**
193      *
194      * @return the associated File if this data is represented in a file
195      * @exception IOException
196      *                if this data is not represented by a file
197      */
198     File getFile() throws IOException;
199 
200     @Override
201     HttpData copy();
202 
203     @Override
204     HttpData duplicate();
205 
206     @Override
207     HttpData retain();
208 
209     @Override
210     HttpData retain(int increment);
211 
212     @Override
213     HttpData touch();
214 
215     @Override
216     HttpData touch(Object hint);
217 }