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 }