##### Coverage Report - org.apache.commons.fileupload.FileItem

Classes in this File | Line Coverage | Branch Coverage | Complexity
FileItem |
N/A | N/A
N/A | N/A
| 1.0;1

1 |  |
     /*
2 |  |
      * Licensed to the Apache Software Foundation (ASF) under one or more
3 |  |
      * contributor license agreements.  See the NOTICE file distributed with
4 |  |
      * this work for additional information regarding copyright ownership.
5 |  |
      * The ASF licenses this file to You under the Apache License, Version 2.0
6 |  |
      * (the "License"); you may not use this file except in compliance with
7 |  |
      * the License.  You may obtain a copy of the License at
8 |  |
      *
9 |  |
      *      http://www.apache.org/licenses/LICENSE-2.0
10 |  |
      *
11 |  |
      * Unless required by applicable law or agreed to in writing, software
12 |  |
      * distributed under the License is distributed on an "AS IS" BASIS,
13 |  |
      * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 |  |
      * See the License for the specific language governing permissions and
15 |  |
      * limitations under the License.
16 |  |
      */
17 |  |
     package org.apache.commons.fileupload;
18 |  |
19 |  |
     import java.io.File;
20 |  |
     import java.io.IOException;
21 |  |
     import java.io.InputStream;
22 |  |
     import java.io.OutputStream;
23 |  |
     import java.io.UnsupportedEncodingException;
24 |  |
25 |  |
     /**
26 |  |
      * <p> This class represents a file or form item that was received within a
27 |  |
      * <code>multipart/form-data</code> POST request.
28 |  |
      *
29 |  |
      * <p> After retrieving an instance of this class from a {@link
30 |  |
      * org.apache.commons.fileupload.FileUpload FileUpload} instance (see
31 |  |
      * {@link org.apache.commons.fileupload.servlet.ServletFileUpload
32 |  |
      * #parseRequest(javax.servlet.http.HttpServletRequest)}), you may
33 |  |
      * either request all contents of the file at once using {@link #get()} or
34 |  |
      * request an {@link java.io.InputStream InputStream} with
35 |  |
      * {@link #getInputStream()} and process the file without attempting to load
36 |  |
      * it into memory, which may come handy with large files.
37 |  |
      *
38 |  |
      * <p> While this interface does not extend
39 |  |
      * <code>javax.activation.DataSource</code> per se (to avoid a seldom used
40 |  |
      * dependency), several of the defined methods are specifically defined with
41 |  |
      * the same signatures as methods in that interface. This allows an
42 |  |
      * implementation of this interface to also implement
43 |  |
      * <code>javax.activation.DataSource</code> with minimal additional work.
44 |  |
      *
45 |  |
      * @since 1.3 additionally implements FileItemHeadersSupport
46 |  |
      */
47 |  |
     public interface FileItem extends FileItemHeadersSupport {
48 |  |
49 |  |
         // ------------------------------- Methods from javax.activation.DataSource
50 |  |
51 |  |
         /**
52 |  |
          * Returns an {@link java.io.InputStream InputStream} that can be
53 |  |
          * used to retrieve the contents of the file.
54 |  |
          *
55 |  |
          * @return An {@link java.io.InputStream InputStream} that can be
56 |  |
          *         used to retrieve the contents of the file.
57 |  |
          *
58 |  |
          * @throws IOException if an error occurs.
59 |  |
          */
60 |  |
         InputStream getInputStream() throws IOException;
61 |  |
62 |  |
         /**
63 |  |
          * Returns the content type passed by the browser or <code>null</code> if
64 |  |
          * not defined.
65 |  |
          *
66 |  |
          * @return The content type passed by the browser or <code>null</code> if
67 |  |
          *         not defined.
68 |  |
          */
69 |  |
         String getContentType();
70 |  |
71 |  |
         /**
72 |  |
          * Returns the original filename in the client's filesystem, as provided by
73 |  |
          * the browser (or other client software). In most cases, this will be the
74 |  |
          * base file name, without path information. However, some clients, such as
75 |  |
          * the Opera browser, do include path information.
76 |  |
          *
77 |  |
          * @return The original filename in the client's filesystem.
78 |  |
          * @throws InvalidFileNameException The file name contains a NUL character,
79 |  |
          *   which might be an indicator of a security attack. If you intend to
80 |  |
          *   use the file name anyways, catch the exception and use
81 |  |
          *   InvalidFileNameException#getName().
82 |  |
          */
83 |  |
         String getName();
84 |  |
85 |  |
         // ------------------------------------------------------- FileItem methods
86 |  |
87 |  |
         /**
88 |  |
          * Provides a hint as to whether or not the file contents will be read
89 |  |
          * from memory.
90 |  |
          *
91 |  |
          * @return <code>true</code> if the file contents will be read from memory;
92 |  |
          *         <code>false</code> otherwise.
93 |  |
          */
94 |  |
         boolean isInMemory();
95 |  |
96 |  |
         /**
97 |  |
          * Returns the size of the file item.
98 |  |
          *
99 |  |
          * @return The size of the file item, in bytes.
100 |  |
          */
101 |  |
         long getSize();
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 |  |
          */
108 |  |
         byte[] get();
109 |  |
110 |  |
         /**
111 |  |
          * Returns the contents of the file item as a String, using the specified
112 |  |
          * encoding.  This method uses {@link #get()} to retrieve the
113 |  |
          * contents of the item.
114 |  |
          *
115 |  |
          * @param encoding The character encoding to use.
116 |  |
          *
117 |  |
          * @return The contents of the item, as a string.
118 |  |
          *
119 |  |
          * @throws UnsupportedEncodingException if the requested character
120 |  |
          *                                      encoding is not available.
121 |  |
          */
122 |  |
         String getString(String encoding) throws UnsupportedEncodingException;
123 |  |
124 |  |
         /**
125 |  |
          * Returns the contents of the file item as a String, using the default
126 |  |
          * character encoding.  This method uses {@link #get()} to retrieve the
127 |  |
          * contents of the item.
128 |  |
          *
129 |  |
          * @return The contents of the item, as a string.
130 |  |
          */
131 |  |
         String getString();
132 |  |
133 |  |
         /**
134 |  |
          * A convenience method to write an uploaded item to disk. The client code
135 |  |
          * is not concerned with whether or not the item is stored in memory, or on
136 |  |
          * disk in a temporary location. They just want to write the uploaded item
137 |  |
          * to a file.
138 |  |
          * <p>
139 |  |
          * This method is not guaranteed to succeed if called more than once for
140 |  |
          * the same item. This allows a particular implementation to use, for
141 |  |
          * example, file renaming, where possible, rather than copying all of the
142 |  |
          * underlying data, thus gaining a significant performance benefit.
143 |  |
          *
144 |  |
          * @param file The <code>File</code> into which the uploaded item should
145 |  |
          *             be stored.
146 |  |
          *
147 |  |
          * @throws Exception if an error occurs.
148 |  |
          */
149 |  |
         void write(File file) throws Exception;
150 |  |
151 |  |
         /**
152 |  |
          * Deletes the underlying storage for a file item, including deleting any
153 |  |
          * associated temporary disk file. Although this storage will be deleted
154 |  |
          * automatically when the <code>FileItem</code> instance is garbage
155 |  |
          * collected, this method can be used to ensure that this is done at an
156 |  |
          * earlier time, thus preserving system resources.
157 |  |
          */
158 |  |
         void delete();
159 |  |
160 |  |
         /**
161 |  |
          * Returns the name of the field in the multipart form corresponding to
162 |  |
          * this file item.
163 |  |
          *
164 |  |
          * @return The name of the form field.
165 |  |
          */
166 |  |
         String getFieldName();
167 |  |
168 |  |
         /**
169 |  |
          * Sets the field name used to reference this file item.
170 |  |
          *
171 |  |
          * @param name The name of the form field.
172 |  |
          */
173 |  |
         void setFieldName(String name);
174 |  |
175 |  |
         /**
176 |  |
          * Determines whether or not a <code>FileItem</code> instance represents
177 |  |
          * a simple form field.
178 |  |
          *
179 |  |
          * @return <code>true</code> if the instance represents a simple form
180 |  |
          *         field; <code>false</code> if it represents an uploaded file.
181 |  |
          */
182 |  |
         boolean isFormField();
183 |  |
184 |  |
         /**
185 |  |
          * Specifies whether or not a <code>FileItem</code> instance represents
186 |  |
          * a simple form field.
187 |  |
          *
188 |  |
          * @param state <code>true</code> if the instance represents a simple form
189 |  |
          *              field; <code>false</code> if it represents an uploaded file.
190 |  |
          */
191 |  |
         void setFormField(boolean state);
192 |  |
193 |  |
         /**
194 |  |
          * Returns an {@link java.io.OutputStream OutputStream} that can
195 |  |
          * be used for storing the contents of the file.
196 |  |
          *
197 |  |
          * @return An {@link java.io.OutputStream OutputStream} that can be used
198 |  |
          *         for storing the contensts of the file.
199 |  |
          *
200 |  |
          * @throws IOException if an error occurs.
201 |  |
          */
202 |  |
         OutputStream getOutputStream() throws IOException;
203 |  |
204 |  |
     }