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 org.jboss.netty.handler.codec.http.multipart;
17  
18  import org.jboss.netty.buffer.ChannelBuffer;
19  
20  import java.io.File;
21  import java.io.IOException;
22  import java.io.InputStream;
23  import java.nio.charset.Charset;
24  
25  /**
26   * Extended interface for InterfaceHttpData
27   */
28  public interface HttpData extends InterfaceHttpData {
29      /**
30       * Set the maxSize for this HttpData. When limit will be reached, an exception will be raised.
31       * Setting it to (-1) means no limitation.
32       *
33       * By default, to be set from the HttpDataFactory.
34       * @param maxSize
35       */
36      void setMaxSize(long maxSize);
37  
38      /**
39       * Check if the new size is not reaching the max limit allowed.
40       * The limit is always computed in term of bytes.
41       * @param newSize
42       * @throws IOException
43       */
44      void checkSize(long newSize) throws IOException;
45  
46      /**
47       * Set the content from the ChannelBuffer (erase any previous data)
48       *
49       * @param buffer
50       *            must be not null
51       * @exception IOException
52       */
53      void setContent(ChannelBuffer buffer) throws IOException;
54  
55      /**
56       * Add the content from the ChannelBuffer
57       *
58       * @param buffer
59       *            must be not null except if last is set to False
60       * @param last
61       *            True of the buffer is the last one
62       * @exception IOException
63       */
64      void addContent(ChannelBuffer buffer, boolean last) throws IOException;
65  
66      /**
67       * Set the content from the file (erase any previous data)
68       *
69       * @param file
70       *            must be not null
71       * @exception IOException
72       */
73      void setContent(File file) throws IOException;
74  
75      /**
76       * Set the content from the inputStream (erase any previous data)
77       *
78       * @param inputStream
79       *            must be not null
80       * @exception IOException
81       */
82      void setContent(InputStream inputStream) throws IOException;
83  
84      /**
85       *
86       * @return True if the InterfaceHttpData is completed (all data are stored)
87       */
88      boolean isCompleted();
89  
90      /**
91       * Returns the size in byte of the InterfaceHttpData
92       *
93       * @return the size of the InterfaceHttpData
94       */
95      long length();
96  
97      /**
98       * Deletes the underlying storage for a file item, including deleting any
99       * associated temporary disk file.
100      */
101     void delete();
102 
103     /**
104      * Returns the contents of the file item as an array of bytes.
105      *
106      * @return the contents of the file item as an array of bytes.
107      * @exception IOException
108      */
109     byte[] get() throws IOException;
110 
111     /**
112      * Returns the content of the file item as a ChannelBuffer
113      *
114      * @return the content of the file item as a ChannelBuffer
115      * @throws IOException
116      */
117     ChannelBuffer getChannelBuffer() throws IOException;
118 
119     /**
120      * Returns a ChannelBuffer for the content from the current position with at
121      * most length read bytes, increasing the current position of the Bytes
122      * read. Once it arrives at the end, it returns an EMPTY_BUFFER and it
123      * resets the current position to 0.
124      *
125      * @return a ChannelBuffer for the content from the current position or an
126      *         EMPTY_BUFFER if there is no more data to return
127      */
128     ChannelBuffer getChunk(int length) throws IOException;
129 
130     /**
131      * Returns the contents of the file item as a String, using the default
132      * character encoding.
133      *
134      * @return the contents of the file item as a String, using the default
135      *         character encoding.
136      */
137     String getString() throws IOException;
138 
139     /**
140      * Returns the contents of the file item as a String, using the specified
141      * charset.
142      *
143      * @param encoding
144      *            the charset to use
145      * @return the contents of the file item as a String, using the specified
146      *         charset.
147      * @exception IOException
148      */
149     String getString(Charset encoding) throws IOException;
150 
151     /**
152      * Set the Charset passed by the browser if defined
153      *
154      * @param charset
155      *            Charset to set - must be not null
156      */
157     void setCharset(Charset charset);
158 
159     /**
160      * Returns the Charset passed by the browser or null if not defined.
161      *
162      * @return the Charset passed by the browser or null if not defined.
163      */
164     Charset getCharset();
165 
166     /**
167      * A convenience method to write an uploaded item to disk. If a previous one
168      * exists, it will be deleted. Once this method is called, if successful,
169      * the new file will be out of the cleaner of the factory that creates the
170      * original InterfaceHttpData object.
171      *
172      * @param dest
173      *            destination file - must be not null
174      * @return True if the write is successful
175      * @exception IOException
176      */
177     boolean renameTo(File dest) throws IOException;
178 
179     /**
180      * Provides a hint as to whether or not the file contents will be read from
181      * memory.
182      *
183      * @return True if the file contents is in memory.
184      */
185     boolean isInMemory();
186 
187     /**
188      *
189      * @return the associated File if this data is represented in a file
190      * @exception IOException
191      *                if this data is not represented by a file
192      */
193     File getFile() throws IOException;
194 
195 }