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  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 }