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.disk;
18
19 import java.io.File;
20
21 import org.apache.commons.fileupload.FileItem;
22 import org.apache.commons.fileupload.FileItemFactory;
23 import org.apache.commons.io.FileCleaningTracker;
24
25
26 /**
27 * <p>The default {@link org.apache.commons.fileupload.FileItemFactory}
28 * implementation. This implementation creates
29 * {@link org.apache.commons.fileupload.FileItem} instances which keep their
30 * content either in memory, for smaller items, or in a temporary file on disk,
31 * for larger items. The size threshold, above which content will be stored on
32 * disk, is configurable, as is the directory in which temporary files will be
33 * created.</p>
34 *
35 * <p>If not otherwise configured, the default configuration values are as
36 * follows:
37 * <ul>
38 * <li>Size threshold is 10KB.</li>
39 * <li>Repository is the system default temp directory, as returned by
40 * <code>System.getProperty("java.io.tmpdir")</code>.</li>
41 * </ul>
42 * </p>
43 *
44 * <p>Temporary files, which are created for file items, should be
45 * deleted later on. The best way to do this is using a
46 * {@link FileCleaningTracker}, which you can set on the
47 * {@link DiskFileItemFactory}. However, if you do use such a tracker,
48 * then you must consider the following: Temporary files are automatically
49 * deleted as soon as they are no longer needed. (More precisely, when the
50 * corresponding instance of {@link java.io.File} is garbage collected.)
51 * This is done by the so-called reaper thread, which is started
52 * automatically when the class {@link org.apache.commons.io.FileCleaner}
53 * is loaded.
54 * It might make sense to terminate that thread, for example, if
55 * your web application ends. See the section on "Resource cleanup"
56 * in the users guide of commons-fileupload.</p>
57 *
58 * @author <a href="mailto:martinc@apache.org">Martin Cooper</a>
59 *
60 * @since FileUpload 1.1
61 *
62 * @version $Id: DiskFileItemFactory.java 735374 2009-01-18 02:18:45Z jochen $
63 */
64 public class DiskFileItemFactory implements FileItemFactory {
65
66 // ----------------------------------------------------- Manifest constants
67
68
69 /**
70 * The default threshold above which uploads will be stored on disk.
71 */
72 public static final int DEFAULT_SIZE_THRESHOLD = 10240;
73
74
75 // ----------------------------------------------------- Instance Variables
76
77
78 /**
79 * The directory in which uploaded files will be stored, if stored on disk.
80 */
81 private File repository;
82
83
84 /**
85 * The threshold above which uploads will be stored on disk.
86 */
87 private int sizeThreshold = DEFAULT_SIZE_THRESHOLD;
88
89
90 /**
91 * <p>The instance of {@link FileCleaningTracker}, which is responsible
92 * for deleting temporary files.</p>
93 * <p>May be null, if tracking files is not required.</p>
94 */
95 private FileCleaningTracker fileCleaningTracker;
96
97 // ----------------------------------------------------------- Constructors
98
99
100 /**
101 * Constructs an unconfigured instance of this class. The resulting factory
102 * may be configured by calling the appropriate setter methods.
103 */
104 public DiskFileItemFactory() {
105 this(DEFAULT_SIZE_THRESHOLD, null);
106 }
107
108
109 /**
110 * Constructs a preconfigured instance of this class.
111 *
112 * @param sizeThreshold The threshold, in bytes, below which items will be
113 * retained in memory and above which they will be
114 * stored as a file.
115 * @param repository The data repository, which is the directory in
116 * which files will be created, should the item size
117 * exceed the threshold.
118 */
119 public DiskFileItemFactory(int sizeThreshold, File repository) {
120 this.sizeThreshold = sizeThreshold;
121 this.repository = repository;
122 }
123
124 // ------------------------------------------------------------- Properties
125
126
127 /**
128 * Returns the directory used to temporarily store files that are larger
129 * than the configured size threshold.
130 *
131 * @return The directory in which temporary files will be located.
132 *
133 * @see #setRepository(java.io.File)
134 *
135 */
136 public File getRepository() {
137 return repository;
138 }
139
140
141 /**
142 * Sets the directory used to temporarily store files that are larger
143 * than the configured size threshold.
144 *
145 * @param repository The directory in which temporary files will be located.
146 *
147 * @see #getRepository()
148 *
149 */
150 public void setRepository(File repository) {
151 this.repository = repository;
152 }
153
154
155 /**
156 * Returns the size threshold beyond which files are written directly to
157 * disk. The default value is 10240 bytes.
158 *
159 * @return The size threshold, in bytes.
160 *
161 * @see #setSizeThreshold(int)
162 */
163 public int getSizeThreshold() {
164 return sizeThreshold;
165 }
166
167
168 /**
169 * Sets the size threshold beyond which files are written directly to disk.
170 *
171 * @param sizeThreshold The size threshold, in bytes.
172 *
173 * @see #getSizeThreshold()
174 *
175 */
176 public void setSizeThreshold(int sizeThreshold) {
177 this.sizeThreshold = sizeThreshold;
178 }
179
180
181 // --------------------------------------------------------- Public Methods
182
183 /**
184 * Create a new {@link org.apache.commons.fileupload.disk.DiskFileItem}
185 * instance from the supplied parameters and the local factory
186 * configuration.
187 *
188 * @param fieldName The name of the form field.
189 * @param contentType The content type of the form field.
190 * @param isFormField <code>true</code> if this is a plain form field;
191 * <code>false</code> otherwise.
192 * @param fileName The name of the uploaded file, if any, as supplied
193 * by the browser or other client.
194 *
195 * @return The newly created file item.
196 */
197 public FileItem createItem(String fieldName, String contentType,
198 boolean isFormField, String fileName) {
199 DiskFileItem result = new DiskFileItem(fieldName, contentType,
200 isFormField, fileName, sizeThreshold, repository);
201 FileCleaningTracker tracker = getFileCleaningTracker();
202 if (tracker != null) {
203 tracker.track(result.getTempFile(), this);
204 }
205 return result;
206 }
207
208
209 /**
210 * Returns the tracker, which is responsible for deleting temporary
211 * files.
212 * @return An instance of {@link FileCleaningTracker}, or null
213 * (default), if temporary files aren't tracked.
214 */
215 public FileCleaningTracker getFileCleaningTracker() {
216 return fileCleaningTracker;
217 }
218
219 /**
220 * Sets the tracker, which is responsible for deleting temporary
221 * files.
222 * @param pTracker An instance of {@link FileCleaningTracker},
223 * which will from now on track the created files, or null
224 * (default), to disable tracking.
225 */
226 public void setFileCleaningTracker(FileCleaningTracker pTracker) {
227 fileCleaningTracker = pTracker;
228 }
229 }