You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@myfaces.apache.org by sk...@apache.org on 2008/07/23 20:39:09 UTC
svn commit: r679157 - in /myfaces/tomahawk/trunk/core/src:
main/java/org/apache/myfaces/custom/fileupload/
main/java/org/apache/myfaces/webapp/filter/ site/xdoc/
Author: skitching
Date: Wed Jul 23 11:39:08 2008
New Revision: 679157
URL: http://svn.apache.org/viewvc?rev=679157&view=rev
Log:
TOMAHAWK-1303 - improve t:inputFileUpload documentation.
Modified:
myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/fileupload/AbstractHtmlInputFileUpload.java
myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/fileupload/HtmlFileUploadRenderer.java
myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/webapp/filter/ExtensionsFilter.java
myfaces/tomahawk/trunk/core/src/site/xdoc/extensionsFilter.xml
myfaces/tomahawk/trunk/core/src/site/xdoc/selectOneRow.xml
Modified: myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/fileupload/AbstractHtmlInputFileUpload.java
URL: http://svn.apache.org/viewvc/myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/fileupload/AbstractHtmlInputFileUpload.java?rev=679157&r1=679156&r2=679157&view=diff
==============================================================================
--- myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/fileupload/AbstractHtmlInputFileUpload.java (original)
+++ myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/fileupload/AbstractHtmlInputFileUpload.java Wed Jul 23 11:39:08 2008
@@ -28,12 +28,24 @@
import org.apache.myfaces.shared_tomahawk.util.MessageUtils;
/**
- * You must enable the MultiPart Filter to make this component work (see web.xml).
- *
+ * Creates a file-selection widget in the rendered page which allows a user to select
+ * a file for uploading to the server.
+ * <p>
+ * When the page is selected (using a command component such as commandButton), the
+ * currently selected file contents are included in the data posted to the server.
+ * The contents are cached somewhere, and an object of type UploadedFile will then
+ * be assigned to the property pointed to by the "value" expression of this component.
+ * </p>
+ * <p>
+ * You must enable the Tomahawk ExtensionsFilter to make this component work (see web.xml).
+ * </p>
+ * <p>
* Also, don't forget to set the form's attribute "enctype" to "multipart/form-data".
- * See "examples/web/fileupload.jsp" for an example!
- *
+ * See "examples/web/fileupload.jsp" for an example!
+ * </p>
+ * <p>
* Unless otherwise specified, all attributes accept static values or EL expressions.
+ * </p>
*
* @JSFComponent
* name = "t:inputFileUpload"
@@ -70,14 +82,36 @@
}
/**
+ * This setting was intended to allow control over how the contents of the
+ * file get temporarily stored during processing.
+ * <p>
+ * However it appears that this is only half-implemented, and not at all
+ * documented. It is therefore recommended that this not be used.
+ * </p>
+ *
* @JSFProperty
*/
public abstract String getStorage();
+
/**
+ * This property appears to have no purpose at all. It certainly has no
+ * documentation.
+ *
* @JSFProperty
*/
public abstract String getAccept();
+ /**
+ * An EL expression to which an UploadedFile object will be assigned on postback
+ * if the user specified a file to upload to the server.
+ *
+ * @JSFProperty
+ */
+ public Object getValue()
+ {
+ return super.getValue();
+ }
+
public boolean isRendered()
{
if (!UserRoleUtils.isVisibleOnUserRole(this)) return false;
Modified: myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/fileupload/HtmlFileUploadRenderer.java
URL: http://svn.apache.org/viewvc/myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/fileupload/HtmlFileUploadRenderer.java?rev=679157&r1=679156&r2=679157&view=diff
==============================================================================
--- myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/fileupload/HtmlFileUploadRenderer.java (original)
+++ myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/fileupload/HtmlFileUploadRenderer.java Wed Jul 23 11:39:08 2008
@@ -41,6 +41,10 @@
import java.util.Map;
/**
+ * Renderer for the HtmlInputFileUpload component.
+ * <p>
+ * See also class AbstractHtmlInputFileUpload.
+ *
* @JSFRenderer
* renderKitId = "HTML_BASIC"
* family = "javax.faces.Input"
@@ -101,7 +105,15 @@
}
}
-
+ /**
+ * Handle the postback of a form containing a fileUpload component.
+ * <p>
+ * The browser request will have been in "multi-part-mime" format, where
+ * the normal http post is in one part, and the file being uploaded is
+ * in another. Hopefully JSF has been configured so that this special
+ * request is wrapped in a custom ServletRequest that allows us to
+ * fetch that extra data....
+ */
public void decode(FacesContext facesContext, UIComponent uiComponent)
{
super.decode(facesContext, uiComponent); //check for NP
Modified: myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/webapp/filter/ExtensionsFilter.java
URL: http://svn.apache.org/viewvc/myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/webapp/filter/ExtensionsFilter.java?rev=679157&r1=679156&r2=679157&view=diff
==============================================================================
--- myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/webapp/filter/ExtensionsFilter.java (original)
+++ myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/webapp/filter/ExtensionsFilter.java Wed Jul 23 11:39:08 2008
@@ -18,7 +18,6 @@
*/
package org.apache.myfaces.webapp.filter;
-import org.apache.commons.fileupload.FileUpload;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.apache.myfaces.renderkit.html.util.AddResource;
@@ -113,7 +112,8 @@
* library to save the file into a configurable local directory before
* allowing the normal processing for the url that the post request
* refers to. A number of configuration properties on this filter control
- * maximum file upload sizes and various other useful settings.
+ * maximum file upload sizes and various other useful settings. See the
+ * documentation for the init method for more details.
*
* <h2>Avoiding Processing</h2>
*
@@ -130,7 +130,7 @@
private Log log = LogFactory.getLog(ExtensionsFilter.class);
- private int _uploadMaxFileSize = 100 * 1024 * 1024; // 10 MB
+ private int _uploadMaxFileSize = 100 * 1024 * 1024; // 100 MB
private int _uploadThresholdSize = 1 * 1024 * 1024; // 1 MB
@@ -141,9 +141,53 @@
public static final String DOFILTER_CALLED = "org.apache.myfaces.component.html.util.ExtensionFilter.doFilterCalled";
/**
- * Init method for this filter
+ * Init method for this filter.
+ * <p>
+ * The following filter init parameters can be configured in the web.xml file
+ * for this filter:
+ * <ul>
+ * <li>uploadMaxFileSize</li>
+ * <li>uploadThresholdSize</li>
+ * <li>uploadRepositoryPath</li>
+ * </ul>
+ * </p>
+ * <p>
+ * All size parameters may have the suffix "g" (gigabytes), "m" (megabytes) or "k" (kilobytes).
+ * </p>
+ *
+ * <h2>uploadMaxFileSize</h2>
+ *
+ * Sets the maximum allowable size for uploaded files.
+ * <p>
+ * If the user attempts to upload a file which is larger than this, then the data <i>is</i>
+ * transmitted from the browser to the server (this cannot be prevented with standard HTML
+ * functionality). However the file will not be saved in memory or on disk. An error message
+ * will be added to the standard JSF error messages, and the page re-rendered (as for a
+ * validation failure).
+ * </p>
+ * <p>
+ * The default value is 100 Megabytes.
+ * </p>
+ *
+ * <h2>uploadThresholdSize</h2>
+ *
+ * Sets the size threshold beyond which files are written directly to disk. Files which are
+ * smaller than this are simply held in memory. The default is 1 Megabyte.
+ *
+ * <h2>uploadRepositoryPath</h2>
+ *
+ * Sets the directory in which temporary files (ie caches for those uploaded files that
+ * are larger than uploadThresholdSize) are to be stored.
*/
public void init(FilterConfig filterConfig) {
+ // Note that the code here to extract FileUpload configuration params is not actually used.
+ // The handling of multipart requests was moved from this Filter into a custom FacesContext
+ // (TomahawkFacesContextWrapper) so that Portlets could be supported (Portlets cannot use
+ // servlet filters).
+ //
+ // For backwards compatibility, the TomahawkFacesContextWrapper class *parses* the
+ // web.xml to retrieve these same filter config params. That is IMO seriously ugly
+ // and hopefully will be fixed.
String param = filterConfig.getInitParameter("uploadMaxFileSize");
Modified: myfaces/tomahawk/trunk/core/src/site/xdoc/extensionsFilter.xml
URL: http://svn.apache.org/viewvc/myfaces/tomahawk/trunk/core/src/site/xdoc/extensionsFilter.xml?rev=679157&r1=679156&r2=679157&view=diff
==============================================================================
--- myfaces/tomahawk/trunk/core/src/site/xdoc/extensionsFilter.xml (original)
+++ myfaces/tomahawk/trunk/core/src/site/xdoc/extensionsFilter.xml Wed Jul 23 11:39:08 2008
@@ -54,7 +54,7 @@
<filter-name>MyFacesExtensionsFilter</filter-name>
<filter-class>org.apache.myfaces.webapp.filter.ExtensionsFilter</filter-class>
<init-param>
- <param-name>maxFileSize</param-name>
+ <param-name>uploadMaxFileSize</param-name>
<param-value>20m</param-value>
<description>Set the size limit for uploaded files.
Format: 10 - 10 bytes
@@ -87,6 +87,12 @@
</filter-mapping>
</source>
</section>
+<section name="What configuration settings are available?">
+ <p>
+ See the javadoc for class ExtensionsFilter for information on the full set of configuration
+ options for this filter.
+ </p>
+</section>
<section name="Under what circumstances am I *required* to use the extensions filter?">
<p>
If you just use standard JSF component, but don't use any MyFaces' extended component (beginning with t:),
Modified: myfaces/tomahawk/trunk/core/src/site/xdoc/selectOneRow.xml
URL: http://svn.apache.org/viewvc/myfaces/tomahawk/trunk/core/src/site/xdoc/selectOneRow.xml?rev=679157&r1=679156&r2=679157&view=diff
==============================================================================
--- myfaces/tomahawk/trunk/core/src/site/xdoc/selectOneRow.xml (original)
+++ myfaces/tomahawk/trunk/core/src/site/xdoc/selectOneRow.xml Wed Jul 23 11:39:08 2008
@@ -77,6 +77,7 @@
<br/>
<code>
+<!-- TODO: fixme
&html_align_attribute;
&html_disabled_attribute;
&html_focus_blur_attributes;
@@ -84,7 +85,8 @@
&html_onclick_attribute;
&html_onselect_attribute;
&html_readonly_attribute;
- &ui_input_attributes;
+ &ui_input_attributes;
+ -->
</code>
<br/>