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 }