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_TEMP_DIR: the name of a directory
45   *   to store temporary files.  (Defaults to the user's temporary directory)
46   * </ul>
47   * 
48   * @see org.apache.myfaces.trinidad.model.UploadedFile
49   */
50  public interface UploadedFileProcessor
51  {
52    /**
53     * Initialization parameter for the default
54     * <code>UploadedFileProcessor</code> that configures the maximum
55     * amount of memory that can be used in a single request to store
56     * uploaded files.  Any requirements above this will be stored on disk.
57     * The default is 100 kilobytes.
58     */
59    public static final String MAX_MEMORY_PARAM_NAME = "org.apache.myfaces.trinidad.UPLOAD_MAX_MEMORY";
60  
61    /**
62     * Initialization parameter for the default
63     * <code>UploadedFileProcessor</code> that configures the maximum
64     * amount of disk space that can be used in a single request to store
65     * uploaded files.  The default is 2000 kilobytes.  Any requests that
66     * exceed this size will result in an EOFException being thrown
67     * on that request.
68     */
69    public static final String MAX_DISK_SPACE_PARAM_NAME = "org.apache.myfaces.trinidad.UPLOAD_MAX_DISK_SPACE";
70  
71    /**
72     * Initialization parameter for the default
73     * <code>UploadedFileProcessor</code> that configures the 
74     * to the directory where temporary files should be stored while
75     * uploading.  This defaults to the the application server's temporary
76     * directory, as provided by the "javax.servlet.context.tempdir"
77     * property.  If that is not set, the System "java.io.tempdir" property
78     * will be used as a backup.
79     */
80    public static final String TEMP_DIR_PARAM_NAME = "org.apache.myfaces.trinidad.UPLOAD_TEMP_DIR";
81  
82    /**
83     * Initialization parameter for the default
84     * <code>UploadedFileProcessor</code> that configures the maximum
85     * file size that can be uploaded. The default is 2000 kilobytes.  Any requests that
86     * exceed this size will result in an EOFException being thrown
87     * on that request.
88     */
89    public static final String MAX_FILE_SIZE_PARAM_NAME = "org.apache.myfaces.trinidad.UPLOAD_MAX_FILE_SIZE";
90    
91    /**
92     * Initialize the UploadedFileProcessor with access to the current
93     * web application context. 
94     * 
95     * @param context the current ServletContext or PortletContext
96     */
97    public void init(Object context);
98  
99    /**
100    * Process a single uploaded file, moving it from temporary
101    *   storage to per-request storage.  An implementation of this
102    *   method must process an incoming <code>UploadedFile</code> object
103    *   and return a new <code>UploadedFile</code> instance that will
104    *   remain valid for the duration of this request.  The incoming
105    *   <code>UploadedFile</code>
106    *   object is a temporary file object that has a number of 
107    *   restrictions:
108    *  <ul>
109    *    <li>{@link UploadedFile#getInputStream} may only be called once</li>
110    *    <li>{@link UploadedFile#getLength} returns -1, since the length is not yet available</li>
111    *    <li>{@link UploadedFile#getFilename} has not yet been internationalized;  users should not
112    *      rely on its value, but simply use it unmodified in the
113    *      outgoing <code>UploadedFile</code></li>
114    *  </ul>
115    *  <p>
116    *  The <code>UploadedFile</code> object returned from this method
117    *  must remain valid for the duration of this request.  The framework
118    *  guarantees that {@link UploadedFile#dispose}</code> will be called before
119    *  the request completes.
120    *  </p>
121    *  <p>
122    *  If any implementation of this method throws an IOException, it is considered that there is a 
123    *  error in processing the uploaded file, and the message contained in the IOException is shown 
124    *  to the user as a value conversion warning.
125    *  If the processing failure is less severe, and if the failure need to be meaningfully reported 
126    *  to the end users, the length of the returned UploadedFile should be set to -1, and its 
127    *  getOpaqueData() should provide the error details. The object returned by getOpaqueData() 
128    *  should implement a toString() that returns a detailed error message. During the JSF life cycle 
129    *  later, the input file component would show this message as value conversion warning to the 
130    *  user.
131    *  @see UploadedFile#getLength()
132    *  @see UploadedFile#getOpaqueData()
133    *  </p>
134    * @param request the current servlet or portlet request
135    * @param file a temporary file object
136    * @return a new instance of UploadedFile.  It is legal to return null,
137    *   in which case the file will not be available later in the request.
138    */
139   public UploadedFile processFile(
140     Object request, UploadedFile file) throws IOException;
141 }