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 import org.apache.myfaces.trinidad.model.UploadedFile;
23
24 /**
25 * Interface responsible for processing file uploads by multiple processors one
26 * after another in a chained fashion. An Apache Trinidad application could have
27 * multiple <code>ChainedUploadedFileProcessor</code> instances. A composite UploadedFileProcessor
28 * is accessible from the {@link org.apache.myfaces.trinidad.context.RequestContext},
29 * but will be invoked automatically by the framework as needed. Developers
30 * can implement this interface and chain many of them up together using space
31 * separated class names in <code>trinidad-config.xml</code> file under
32 * <code>uploaded-file-processor</code> element. The order in which the processors
33 * will be instantated and called will be the same as how it appears inside the element.
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 ChainedUploadedFileProcessor extends UploadedFileProcessor
51 {
52 /**
53 * Initialize the ChainedUploadedFileProcessor with access to the current
54 * web application context. The order of call is same as it
55 * appears in trinidad-config.xml
56 *
57 * @param context the current ServletContext or PortletContext
58 */
59 public void init(Object context);
60
61 /**
62 * Process a single uploaded file. An implementation of this
63 * method must process an incoming <code>UploadedFile</code> object
64 * and return a new <code>UploadedFile</code> instance that will
65 * remain valid for the duration of this request. The properties of the incoming
66 * <code>UploadedFile</code> object depends on the implementation detail of
67 * the previous ChainedUploadedFileProcessor in the chain. In general all the
68 * implementations must strive to return a <code>UploadedFile</code> that
69 * should at the least comply to following:
70 * <ul>
71 * <li>{@link UploadedFile#getInputStream} may only be called once</li>
72 * <li>{@link UploadedFile#getLength} returns length as it should be available</li>
73 * <li>{@link UploadedFile#getFilename} may have been internationalized; users should not
74 * rely on its value, but simply use it unmodified in the
75 * outgoing <code>UploadedFile</code></li>
76 * </ul>
77 * <p>
78 * First ChainedUploadedFileProcessor in the list gets an <code>UploadedFile</code> implementation
79 * from the framework with the above properties and the following few more:
80 * <ul>
81 * <li>{@link UploadedFile#getInputStream} may be called multiple times. Each call gives a new InputStream</li>
82 * <li>{@link UploadedFile#getLength} returns length</li>
83 * </ul>
84 * Due to the above properties, if there was no change made to the underlying stream
85 * significantly by the current ChainedUploadedFileProcessor, this <code>UploadedFile</code> object could
86 * be returned intact for subsequent processing by the framework. This avoids creation of
87 * new <code>UploadedFile</code> for simple ChainedUploadedFileProcessor implementations.
88 * </p>
89 * <p>
90 * The framework guarantees that {@link UploadedFile#dispose}</code> will be called before
91 * the request completes for each UploadedFile returned by every ChainedUploadedFileProcessor.
92 * The order in which dispose() will be called is the revers of the order
93 * they are declared in trinidad-config.xml. If same UploadedFile
94 * was returned by more than one processors, dispose() will be called only once
95 * on it. Any exception that happenes during dispose() call will be logged
96 * as warning and the processing continues with the rest of the UploadedFile(s).
97 * </p>
98 * <p>
99 * If one of chained file processor throws an IOException in this method, it is considered that
100 * there is a error in processing the uploaded file, the chain is broken hence, the file upload
101 * process stops, and the message contained in the IOException is shown to the user as a value
102 * conversion warning.
103 * If the processing failure is less severe, and if the failure need to be meaningfully reported
104 * to the end users, the length of the returned UploadedFile should be set to -1, and its
105 * getOpaqueData() should provide the error details. The object returned by getOpaqueData()
106 * should implement a toString() that returns a detailed error message. During the JSF life cycle
107 * later, the input file component would show this message as value conversion warning to the
108 * user.
109 * @see UploadedFile#getLength()
110 * @see UploadedFile#getOpaqueData()
111 * </p>
112 * @param request the current servlet or portlet request
113 * @param file a temporary file object
114 * @return a new instance of UploadedFile. It is legal to return null,
115 * in which case the file will not be available later in the request.
116 */
117 public UploadedFile processFile(
118 Object request, UploadedFile file) throws IOException;
119 }