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>When using the <code>DiskFileItemFactory</code>, then you should
045     * consider the following: Temporary files are automatically deleted as
046     * soon as they are no longer needed. (More precisely, when the
047     * corresponding instance of {@link java.io.File} is garbage collected.)
048     * Cleaning up those files is done by an instance of
049     * {@link FileCleaningTracker}, and an associated thread. In a complex
050     * environment, for example in a web application, you should consider
051     * terminating this thread, for example, when your web application
052     * ends. See the section on "Resource cleanup"
053     * in the users guide of commons-fileupload.</p>
054     *
055     * @author <a href="mailto:martinc@apache.org">Martin Cooper</a>
056     *
057     * @since FileUpload 1.1
058     *
059     * @version $Id: DiskFileItemFactory.java 607869 2008-01-01 16:42:17Z jochen $
060     */
061    public class DiskFileItemFactory implements FileItemFactory {
062    
063        // ----------------------------------------------------- Manifest constants
064    
065    
066        /**
067         * The default threshold above which uploads will be stored on disk.
068         */
069        public static final int DEFAULT_SIZE_THRESHOLD = 10240;
070    
071    
072        // ----------------------------------------------------- Instance Variables
073    
074    
075        /**
076         * The directory in which uploaded files will be stored, if stored on disk.
077         */
078        private File repository;
079    
080    
081        /**
082         * The threshold above which uploads will be stored on disk.
083         */
084        private int sizeThreshold = DEFAULT_SIZE_THRESHOLD;
085    
086    
087        /**
088         * <p>The instance of {@link FileCleaningTracker}, which is responsible
089         * for deleting temporary files.</p>
090         * <p>May be null, if tracking files is not required.</p>
091         */
092        private FileCleaningTracker fileCleaningTracker;
093    
094        // ----------------------------------------------------------- Constructors
095    
096    
097        /**
098         * Constructs an unconfigured instance of this class. The resulting factory
099         * may be configured by calling the appropriate setter methods.
100         */
101        public DiskFileItemFactory() {
102            this(DEFAULT_SIZE_THRESHOLD, null);
103        }
104    
105    
106        /**
107         * Constructs a preconfigured instance of this class.
108         *
109         * @param sizeThreshold The threshold, in bytes, below which items will be
110         *                      retained in memory and above which they will be
111         *                      stored as a file.
112         * @param repository    The data repository, which is the directory in
113         *                      which files will be created, should the item size
114         *                      exceed the threshold.
115         */
116        public DiskFileItemFactory(int sizeThreshold, File repository) {
117            this.sizeThreshold = sizeThreshold;
118            this.repository = repository;
119        }
120    
121        // ------------------------------------------------------------- Properties
122    
123    
124        /**
125         * Returns the directory used to temporarily store files that are larger
126         * than the configured size threshold.
127         *
128         * @return The directory in which temporary files will be located.
129         *
130         * @see #setRepository(java.io.File)
131         *
132         */
133        public File getRepository() {
134            return repository;
135        }
136    
137    
138        /**
139         * Sets the directory used to temporarily store files that are larger
140         * than the configured size threshold.
141         *
142         * @param repository The directory in which temporary files will be located.
143         *
144         * @see #getRepository()
145         *
146         */
147        public void setRepository(File repository) {
148            this.repository = repository;
149        }
150    
151    
152        /**
153         * Returns the size threshold beyond which files are written directly to
154         * disk. The default value is 10240 bytes.
155         *
156         * @return The size threshold, in bytes.
157         *
158         * @see #setSizeThreshold(int)
159         */
160        public int getSizeThreshold() {
161            return sizeThreshold;
162        }
163    
164    
165        /**
166         * Sets the size threshold beyond which files are written directly to disk.
167         *
168         * @param sizeThreshold The size threshold, in bytes.
169         *
170         * @see #getSizeThreshold()
171         *
172         */
173        public void setSizeThreshold(int sizeThreshold) {
174            this.sizeThreshold = sizeThreshold;
175        }
176    
177    
178        // --------------------------------------------------------- Public Methods
179    
180        /**
181         * Create a new {@link org.apache.commons.fileupload.disk.DiskFileItem}
182         * instance from the supplied parameters and the local factory
183         * configuration.
184         *
185         * @param fieldName   The name of the form field.
186         * @param contentType The content type of the form field.
187         * @param isFormField <code>true</code> if this is a plain form field;
188         *                    <code>false</code> otherwise.
189         * @param fileName    The name of the uploaded file, if any, as supplied
190         *                    by the browser or other client.
191         *
192         * @return The newly created file item.
193         */
194        public FileItem createItem(String fieldName, String contentType,
195                boolean isFormField, String fileName) {
196            DiskFileItem result = new DiskFileItem(fieldName, contentType,
197                    isFormField, fileName, sizeThreshold, repository);
198            FileCleaningTracker tracker = getFileCleaningTracker();
199            if (tracker != null) {
200                tracker.track(result.getTempFile(), this);
201            }
202            return result;
203        }
204    
205    
206        /**
207         * Returns the tracker, which is responsible for deleting temporary
208         * files.
209         * @return An instance of {@link FileCleaningTracker}, defaults to
210         *   {@link org.apache.commons.io.FileCleaner#getInstance()}. Null,
211         *   if temporary files aren't tracked.
212         */
213        public FileCleaningTracker getFileCleaningTracker() {
214            return fileCleaningTracker;
215        }
216    
217        /**
218         * Returns the tracker, which is responsible for deleting temporary
219         * files.
220         * @param pTracker An instance of {@link FileCleaningTracker},
221         *   which will from now on track the created files. May be null
222         *   to disable tracking.
223         */
224        public void setFileCleaningTracker(FileCleaningTracker pTracker) {
225            fileCleaningTracker = pTracker;
226        }
227    }