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