View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *   http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.apache.myfaces.trinidad.webapp;
20  
21  import java.io.IOException;
22  
23  import org.apache.myfaces.trinidad.model.UploadedFile;
24  
25  /**
26   * Interface responsible for processing file uploads.  An Apache Trinidad
27   * application has a single <code>UploadedFileProcessor</code> instance. For
28   * more simpler, multiple chained UploadedFileProcessor option please look at
29   * {@link  org.apache.myfaces.trinidad.webapp.ChainedUploadedFileProcessor}.
30   * UploadedFileProcessor is accessible from the {@link org.apache.myfaces.trinidad.context.RequestContext},
31   * but will be invoked automatically by the framework as needed.  Developers
32   * can replace the standard processor using the
33   * <code>trinidad-config.xml</code> file.
34   * <p>
35   * To configure file uploads, the default instance supports three context
36   * initialization parameters :
37   * <ul>
38   * <li>org.apache.myfaces.trinidad.UPLOAD_MAX_MEMORY: the maximum amount of memory
39   *  that can be used in a single request to store
40   *  uploaded files. (Default of 100K)
41   * <li>org.apache.myfaces.trinidad.UPLOAD_MAX_DISK_SPACE: the maximum amount of
42   *  disk space that can be used in a single request to store
43   *  uploaded files.  (Default of 2000K)
44   * <li>org.apache.myfaces.trinidad.UPLOAD_MAX_FILE_SIZE: the maximum
45   *  file size that can be uploaded.  (Default of 2000K)
46   * <li>org.apache.myfaces.trinidad.UPLOAD_TEMP_DIR: the name of a directory
47   *   to store temporary files.  (Defaults to the user's temporary directory)
48   * <li>org.apache.myfaces.trinidad.UPLOAD_MAX_CHUNK_SIZE: the maximum
49   *  chunk size that large files will be split into during upload.  (Default of 2000M)
50   * </ul>
51   * 
52   * @see org.apache.myfaces.trinidad.model.UploadedFile
53   */
54  public interface UploadedFileProcessor
55  {
56    /**
57     * Initialization parameter for the default
58     * <code>UploadedFileProcessor</code> that configures the maximum
59     * amount of memory that can be used in a single request to store
60     * uploaded files.  Any requirements above this will be stored on disk.
61     * The default is 100 kilobytes.
62     */
63    public static final String MAX_MEMORY_PARAM_NAME = "org.apache.myfaces.trinidad.UPLOAD_MAX_MEMORY";
64  
65    /**
66     * Initialization parameter for the default
67     * <code>UploadedFileProcessor</code> that configures the maximum
68     * amount of disk space that can be used in a single request to store
69     * uploaded files.  The default is 2000 kilobytes.  Any requests that
70     * exceed this size will result in an EOFException being thrown
71     * on that request.
72     */
73    public static final String MAX_DISK_SPACE_PARAM_NAME = "org.apache.myfaces.trinidad.UPLOAD_MAX_DISK_SPACE";
74  
75    /**
76     * Initialization parameter for the default
77     * <code>UploadedFileProcessor</code> that configures the 
78     * to the directory where temporary files should be stored while
79     * uploading.  This defaults to the the application server's temporary
80     * directory, as provided by the "javax.servlet.context.tempdir"
81     * property.  If that is not set, the System "java.io.tempdir" property
82     * will be used as a backup.
83     */
84    public static final String TEMP_DIR_PARAM_NAME = "org.apache.myfaces.trinidad.UPLOAD_TEMP_DIR";
85  
86    /**
87     * Initialization parameter for the default
88     * <code>UploadedFileProcessor</code> that configures the maximum
89     * file size that can be uploaded. The default is -1 (unlimited).  Any requests that
90     * exceed this size will result in an EOFException being thrown
91     * on that request.
92     */
93    public static final String MAX_FILE_SIZE_PARAM_NAME = "org.apache.myfaces.trinidad.UPLOAD_MAX_FILE_SIZE";
94    
95    /**
96     * Initialization parameter for the default
97     * <code>UploadedFileProcessor</code> that configures the maximum
98     * chunk size that large files will be split into during upload. 
99     * The default is 2000M and is also the maximum allowed value.
100    */
101   public static final String MAX_CHUNK_SIZE_PARAM_NAME = "org.apache.myfaces.trinidad.UPLOAD_MAX_CHUNK_SIZE";
102   
103   /**
104    * Initialization parameter default value of 100 kilobytes for the default
105    * <code>UploadedFileProcessor</code> parameter MAX_MEMORY_PARAM_NAME.
106    */
107   public static final long DEFAULT_MAX_MEMORY = 102400L;
108   
109   /**
110    * Initialization parameter default value of 2000 kilobytes for the default
111    * <code>UploadedFileProcessor</code> parameter MAX_DISK_SPACE_PARAM_NAME.
112    */
113   public static final long DEFAULT_MAX_DISK_SPACE = 2048000L;
114   
115   /**
116    * Initialization parameter default value of 2000 kilobytes for the default
117    * <code>UploadedFileProcessor</code> parameter MAX_FILE_SIZE_PARAM_NAME.
118    */
119   public static final long DEFAULT_MAX_FILE_SIZE = -1L;
120   
121   /**
122    * Initialization parameter default value of 2000 megabytes for the default
123    * <code>UploadedFileProcessor</code> parameter MAX_CHUNK_PARAM_NAME.
124    */
125   public static final long DEFAULT_MAX_CHUNK_SIZE = 2000000000L;
126   
127   /**
128    * Initialize the UploadedFileProcessor with access to the current
129    * web application context. 
130    * 
131    * @param context the current ServletContext or PortletContext
132    */
133   public void init(Object context);
134 
135   /**
136    * Process a single uploaded file, moving it from temporary
137    *   storage to per-request storage.  An implementation of this
138    *   method must process an incoming <code>UploadedFile</code> object
139    *   and return a new <code>UploadedFile</code> instance that will
140    *   remain valid for the duration of this request.  The incoming
141    *   <code>UploadedFile</code>
142    *   object is a temporary file object that has a number of 
143    *   restrictions:
144    *  <ul>
145    *    <li>{@link UploadedFile#getInputStream} may only be called once</li>
146    *    <li>{@link UploadedFile#getLength} returns -1, since the length is not yet available</li>
147    *    <li>{@link UploadedFile#getFilename} has not yet been internationalized;  users should not
148    *      rely on its value, but simply use it unmodified in the
149    *      outgoing <code>UploadedFile</code></li>
150    *  </ul>
151    *  <p>
152    *  The <code>UploadedFile</code> object returned from this method
153    *  must remain valid for the duration of this request.  The framework
154    *  guarantees that {@link UploadedFile#dispose}</code> will be called before
155    *  the request completes.
156    *  </p>
157    *  <p>
158    *  If any implementation of this method throws an IOException, it is considered that there is a 
159    *  error in processing the uploaded file, and the message contained in the IOException is shown 
160    *  to the user as a value conversion warning.
161    *  If the processing failure is less severe, and if the failure need to be meaningfully reported 
162    *  to the end users, the length of the returned UploadedFile should be set to -1, and its 
163    *  getOpaqueData() should provide the error details. The object returned by getOpaqueData() 
164    *  should implement a toString() that returns a detailed error message. During the JSF life cycle 
165    *  later, the input file component would show this message as value conversion warning to the 
166    *  user.
167    *  @see UploadedFile#getLength()
168    *  @see UploadedFile#getOpaqueData()
169    *  </p>
170    * @param request the current servlet or portlet request
171    * @param file a temporary file object
172    * @return a new instance of UploadedFile.  It is legal to return null,
173    *   in which case the file will not be available later in the request.
174    */
175   public UploadedFile processFile(
176     Object request, UploadedFile file) throws IOException;
177 }