View Javadoc

1   /*
2    * Copyright 2003-2005 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://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,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.commons.fileupload;
17  
18  
19  import java.io.File;
20  import java.util.List;
21  
22  import javax.portlet.ActionRequest;
23  
24  
25  /***
26   * <p>High level API for processing file uploads.</p>
27   *
28   * <p>This class handles multiple files per single HTML widget, sent using
29   * <code>multipart/mixed</code> encoding type, as specified by
30   * <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>.  Use {@link
31   * #parseRequest(ActionRequest)} to acquire a list of {@link
32   * org.apache.commons.fileupload.FileItem}s associated with a given HTML
33   * widget.</p>
34   *
35   * <p>Individual parts will be stored in temporary disk storage or in memory,
36   * depending on their size, and will be available as {@link
37   * org.apache.commons.fileupload.FileItem}s.</p>
38   *
39   * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
40   * @author <a href="mailto:dlr@collab.net">Daniel Rall</a>
41   * @author <a href="mailto:jvanzyl@apache.org">Jason van Zyl</a>
42   * @author <a href="mailto:jmcnally@collab.net">John McNally</a>
43   * @author <a href="mailto:martinc@apache.org">Martin Cooper</a>
44   * @author Sean C. Sullivan
45   *
46   * @version $Id: PortletDiskFileUpload.java,v 1.1 2003/10/01 22:21:43 jsackett Exp $
47   */
48  public class PortletDiskFileUpload
49      extends PortletFileUploadBase
50   {
51  
52      // ----------------------------------------------------------- Data members
53  
54  
55      /***
56       * The factory to use to create new form items.
57       */
58      private DefaultFileItemFactory fileItemFactory;
59  
60  
61      // ----------------------------------------------------------- Constructors
62  
63  
64      /***
65       * Constructs an instance of this class which uses the default factory to
66       * create <code>FileItem</code> instances.
67       *
68       * @see #PortletDiskFileUpload(DefaultFileItemFactory fileItemFactory)
69       */
70      public PortletDiskFileUpload()
71      {
72          super();
73          this.fileItemFactory = new DefaultFileItemFactory();
74      }
75  
76  
77      /***
78       * Constructs an instance of this class which uses the supplied factory to
79       * create <code>FileItem</code> instances.
80       *
81       * @see #PortletDiskFileUpload()
82       */
83      public PortletDiskFileUpload(DefaultFileItemFactory fileItemFactory)
84      {
85          super();
86          this.fileItemFactory = fileItemFactory;
87      }
88  
89  
90      // ----------------------------------------------------- Property accessors
91  
92  
93      /***
94       * Returns the factory class used when creating file items.
95       *
96       * @return The factory class for new file items.
97       */
98      public FileItemFactory getFileItemFactory()
99      {
100         return fileItemFactory;
101     }
102 
103 
104     /***
105      * Sets the factory class to use when creating file items. The factory must
106      * be an instance of <code>DefaultFileItemFactory</code> or a subclass
107      * thereof, or else a <code>ClassCastException</code> will be thrown.
108      *
109      * @param factory The factory class for new file items.
110      */
111     public void setFileItemFactory(FileItemFactory factory)
112     {
113         this.fileItemFactory = (DefaultFileItemFactory) factory;
114     }
115 
116 
117     /***
118      * Returns the size threshold beyond which files are written directly to
119      * disk.
120      *
121      * @return The size threshold, in bytes.
122      *
123      * @see #setSizeThreshold(int)
124      */
125     public int getSizeThreshold()
126     {
127         return fileItemFactory.getSizeThreshold();
128     }
129 
130 
131     /***
132      * Sets the size threshold beyond which files are written directly to disk.
133      *
134      * @param sizeThreshold The size threshold, in bytes.
135      *
136      * @see #getSizeThreshold()
137      */
138     public void setSizeThreshold(int sizeThreshold)
139     {
140         fileItemFactory.setSizeThreshold(sizeThreshold);
141     }
142 
143 
144     /***
145      * Returns the location used to temporarily store files that are larger
146      * than the configured size threshold.
147      *
148      * @return The path to the temporary file location.
149      *
150      * @see #setRepositoryPath(String)
151      */
152     public String getRepositoryPath()
153     {
154         return fileItemFactory.getRepository().getPath();
155     }
156 
157 
158     /***
159      * Sets the location used to temporarily store files that are larger
160      * than the configured size threshold.
161      *
162      * @param repositoryPath The path to the temporary file location.
163      *
164      * @see #getRepositoryPath()
165      */
166     public void setRepositoryPath(String repositoryPath)
167     {
168         fileItemFactory.setRepository(new File(repositoryPath));
169     }
170 
171 
172     // --------------------------------------------------------- Public methods
173 
174 
175     /***
176      * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
177      * compliant <code>multipart/form-data</code> stream. If files are stored
178      * on disk, the path is given by <code>getRepository()</code>.
179      *
180      * @param req           The servlet request to be parsed. Must be non-null.
181      * @param sizeThreshold The max size in bytes to be stored in memory.
182      * @param sizeMax       The maximum allowed upload size, in bytes.
183      * @param path          The location where the files should be stored.
184      *
185      * @return A list of <code>FileItem</code> instances parsed from the
186      *         request, in the order that they were transmitted.
187      *
188      * @exception FileUploadException if there are problems reading/parsing
189      *                                the request or storing files.
190      */
191     public List /* FileItem */ parseRequest(ActionRequest req,
192                                             int sizeThreshold,
193                                             long sizeMax, String path)
194         throws FileUploadException
195     {
196         setSizeThreshold(sizeThreshold);
197         setSizeMax(sizeMax);
198         setRepositoryPath(path);
199         return parseRequest(req);
200     }
201 
202 }