com.sun.webui.jsf.util
Class UploadFilter

java.lang.Object
  extended by com.sun.webui.jsf.util.UploadFilter
All Implemented Interfaces:
javax.servlet.Filter

public class UploadFilter
extends java.lang.Object
implements javax.servlet.Filter

Use the UploadFilter if your application contains an Upload component (<ui:upload> tag).

Configure the filter by declaring the filter element in the web application's deployment descriptor.

 
  <filter>
    <filter-name>UploadFilter</filter-name>
    <filter-class>com.sun.web.ui.util.UploadFilter</filter-class>
  </filter>
 

Map the filter to the FacesServlet, for example

  <filter-mapping>
   <filter-name>UploadFilter</filter-name>
   <servlet-name>FacesServlet</servlet-name>
 </filter-mapping>
 

The UploadFilter uses the Apache commons fileupload package. You can configure the parameters of the UploadFilterDiskFileUpload class (a subclass of DiskFileUpload) by specifying init parameters to the Filter. The following parameters are available:

If an unexpected exception occurs due to a malformed request, for example, UploadFilter.UPLOAD_ERROR_KEY is added as a request attribute with the exception as the value, and is available to the rest of the request chain. If there were no unexpected exceptions but no form data was obtained, Upload.UPLOAD_NO_DATA_KEY is added as a request attribute, with Upload.UPLOAD_NO_DATA_KEY as the value. If Upload.UPLOAD_ERROR_KEY is set Upload.UPLOAD_NO_DATA_KEY is also set but adds no additional information and can be ignored, it is always set when there is an unexpected parsing exception.

UploadFilter places all FileItem's returned by DiskFileUpload.parseRequest() that are not field forms in the request map mapped to their getFieldName value. This includes Upload component fields as well as any standard input fields of type "file".

In order to integrate with the a console application, the UploadFilter recognizes the following ServletContext attribute com.sun.webui.v4.uploadfilter.maxfilesize. If the value of this attribute is an instance of a Long its value takes precedence over the UploadFilter's default values and the value of a filter's maxSize init-param value. If the value is -1 then there is no restriction of upload file size.


Field Summary
static java.lang.String MAX_SIZE
          The name of the filter init parameter used to specify the maximum allowable file upload size.
static java.lang.String SIZE_THRESHOLD
          The name of the filter init parameter used to specify the byte size above which temporary storage of files is on disk.
static java.lang.String TMP_DIR
          The name of the filter init parameter used to specify the directory to be used for temporary storage of uploaded files.
 
Constructor Summary
UploadFilter()
           
 
Method Summary
 void destroy()
          Invoked when the Filter is destroyed
 void doFilter(javax.servlet.ServletRequest request, javax.servlet.ServletResponse response, javax.servlet.FilterChain chain)
          If the incoming request has multipart content, create a UploadFilterDiskFileUpload to parse the request, else pass the request unchanged to the next filter in the chain.
 void init(javax.servlet.FilterConfig filterConfig)
          Initializes the Upload filter by reading any init parameters.
 java.lang.String toString()
          Return a String representation of the UploadFilter
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

MAX_SIZE

public static final java.lang.String MAX_SIZE
The name of the filter init parameter used to specify the maximum allowable file upload size.

See Also:
Constant Field Values

SIZE_THRESHOLD

public static final java.lang.String SIZE_THRESHOLD
The name of the filter init parameter used to specify the byte size above which temporary storage of files is on disk.

See Also:
Constant Field Values

TMP_DIR

public static final java.lang.String TMP_DIR
The name of the filter init parameter used to specify the directory to be used for temporary storage of uploaded files.

See Also:
Constant Field Values
Constructor Detail

UploadFilter

public UploadFilter()
Method Detail

doFilter

public void doFilter(javax.servlet.ServletRequest request,
                     javax.servlet.ServletResponse response,
                     javax.servlet.FilterChain chain)
              throws java.io.IOException,
                     javax.servlet.ServletException
If the incoming request has multipart content, create a UploadFilterDiskFileUpload to parse the request, else pass the request unchanged to the next filter in the chain.

UploadFilterDiskFileUpload reimplements some of the commons-fileupload support classes in order to ensure that the form-data is extracted in the case of unexpected failures due to problems with input/output of the file content. It also ensures that the maxSize specification is enforced on the file size and not the request size. It does this by passing -1 to the underlying FileUploadBase instance and in the upload filter reimplemented classes enforces the size constraint. If the size constraint is exceeded processing continues but resources are not consumed, in order to ensure that any form-data is processed so that it can be passed to the rest of the request chain.it does, the filter processes the request for form components.

Exceptions that occur can be obtained from the specialized UpateFilterFileItem instances stored in the request. These instances can be obtained in the decode method in order to continue in the JSF lifecycle as appropriate.

The form data that might exist in the multipart request is collected into a Hashtable and passed onto the rest of the chain in a wrapped request, as the request parameters.

Note that if an unexpected exception occurs while parsing the multipart data, all request form data is lost and not passed onto the rest of the chain. This means that the JSF view state is also lost and the FacesServlet will see this request as a first request for this page. The unexpected exception will be seen by the Upload renderer and a FacesMessage queued and logged, but for this error to be seen by the application, a component must be rendered after the Upload component to react to the queued message.

Specified by:
doFilter in interface javax.servlet.Filter
Parameters:
response - The servlet response
request - The servlet request we are processing
chain - The filter chain we are processing
Throws:
java.io.IOException - if an input/output error occurs
javax.servlet.ServletException - if a servlet error occurs

init

public void init(javax.servlet.FilterConfig filterConfig)
Initializes the Upload filter by reading any init parameters. If an init parameter is invalid, or an exception occurs due to an invalid init parameter the default value for that parameter will be used and messages and exceptions will be logged as java.util.logging.Level.WARNING.

Specified by:
init in interface javax.servlet.Filter
Parameters:
filterConfig - the filter configuration

toString

public java.lang.String toString()
Return a String representation of the UploadFilter

Overrides:
toString in class java.lang.Object
Returns:
A String representation of the UploadFilter

destroy

public void destroy()
Invoked when the Filter is destroyed

Specified by:
destroy in interface javax.servlet.Filter


Copyright © 2008 Sun Microsystems, Inc. All Rights Reserved.