001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017 package org.apache.commons.fileupload.disk;
018
019 import java.io.File;
020
021 import org.apache.commons.fileupload.FileItem;
022 import org.apache.commons.fileupload.FileItemFactory;
023 import org.apache.commons.io.FileCleaningTracker;
024
025
026 /**
027 * <p>The default {@link org.apache.commons.fileupload.FileItemFactory}
028 * implementation. This implementation creates
029 * {@link org.apache.commons.fileupload.FileItem} instances which keep their
030 * content either in memory, for smaller items, or in a temporary file on disk,
031 * for larger items. The size threshold, above which content will be stored on
032 * disk, is configurable, as is the directory in which temporary files will be
033 * created.</p>
034 *
035 * <p>If not otherwise configured, the default configuration values are as
036 * follows:
037 * <ul>
038 * <li>Size threshold is 10KB.</li>
039 * <li>Repository is the system default temp directory, as returned by
040 * <code>System.getProperty("java.io.tmpdir")</code>.</li>
041 * </ul>
042 * </p>
043 *
044 * <p>Temporary files, which are created for file items, should be
045 * deleted later on. The best way to do this is using a
046 * {@link FileCleaningTracker}, which you can set on the
047 * {@link DiskFileItemFactory}. However, if you do use such a tracker,
048 * then you must consider the following: Temporary files are automatically
049 * deleted as soon as they are no longer needed. (More precisely, when the
050 * corresponding instance of {@link java.io.File} is garbage collected.)
051 * This is done by the so-called reaper thread, which is started
052 * automatically when the class {@link org.apache.commons.io.FileCleaner}
053 * is loaded.
054 * It might make sense to terminate that thread, for example, if
055 * your web application ends. See the section on "Resource cleanup"
056 * in the users guide of commons-fileupload.</p>
057 *
058 * @author <a href="mailto:martinc@apache.org">Martin Cooper</a>
059 *
060 * @since FileUpload 1.1
061 *
062 * @version $Id: DiskFileItemFactory.java 735374 2009-01-18 02:18:45Z jochen $
063 */
064 public class DiskFileItemFactory implements FileItemFactory {
065
066 // ----------------------------------------------------- Manifest constants
067
068
069 /**
070 * The default threshold above which uploads will be stored on disk.
071 */
072 public static final int DEFAULT_SIZE_THRESHOLD = 10240;
073
074
075 // ----------------------------------------------------- Instance Variables
076
077
078 /**
079 * The directory in which uploaded files will be stored, if stored on disk.
080 */
081 private File repository;
082
083
084 /**
085 * The threshold above which uploads will be stored on disk.
086 */
087 private int sizeThreshold = DEFAULT_SIZE_THRESHOLD;
088
089
090 /**
091 * <p>The instance of {@link FileCleaningTracker}, which is responsible
092 * for deleting temporary files.</p>
093 * <p>May be null, if tracking files is not required.</p>
094 */
095 private FileCleaningTracker fileCleaningTracker;
096
097 // ----------------------------------------------------------- Constructors
098
099
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 }