Author: lfryc(a)redhat.com Date: 2011-11-02 12:29:54 -0400 (Wed, 02 Nov 2011) New Revision: 22870 Added: modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/prog-Developer_Guide-Advanced_features-Configuring_ResourceServlet.xml_sample modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/prog-Developer_Guide-Advanced_features-Configuring_resource_loading_strategies.xml_sample modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/prog-Developer_Guide-Advanced_features-Configuring_resource_mapping_custom_mappping_properties.xml_sample modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/prog-Developer_Guide-Advanced_features-Configuring_resource_mapping_web_xml.xml_sample Modified: modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-Advanced_features.xml Log: RFPL-1702: Document Resource loading strategies - initial commit Modified: modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-Advanced_features.xml =================================================================== --- modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-Advanced_features.xml 2011-11-02 16:29:41 UTC (rev 22869) +++ modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/chap-Developer_Guide-Advanced_features.xml 2011-11-02 16:29:54 UTC (rev 22870) @@ -270,6 +270,179 @@ RichFaces provides a number of advanced functions, such as managing user roles and identifying elements. Refer to the <citetitle pubwork="chapter">Functions</citetitle> chapter in the <citetitle pubwork="book">RichFaces Component Reference</citetitle> for further details. </para> </section> + + <section id="sect-Developer_Guide-Advanced_features-Resource_loading"> + <title>Resource loading</title> + <para> + Resources which RichFaces uses in components, like style sheets, JavaScript code or images are handled by standard JSF resource handling. + </para> + <para> + However JSF resource handling feature falls short when using static resources which refers to each other (style sheets refering to images, JavaScript refering to style sheets). + These resources does not know about Faces servlet mapping and thus it cannot be referenced by JSF resource handling feature. + </para> + <para> + RichFaces provides <sgmltag>ResourceServlet</sgmltag> which handles framework static resources: + </para> + <itemizedlist> + <listitem> + <para> + third-party JavaScript libraries or style sheets + </para> + </listitem> + <listitem> + <para> + pre-generated dynamic resources (ECSS, dynamic images) + </para> + </listitem> + </itemizedlist> + + <section id="sect-Developer_Guide-Advanced_features-Configuring_ResourceServlet"> + <title>Configuring ResourceServlet</title> + <para> + <sgmltag>ResourceServlet</sgmltag> is automatically registered in Servlet 3.0 and higher environments. + </para> + <para> + In Servlet 2.5 environment, it is necessary to register <sgmltag>ResourceServlet</sgmltag> manually in <sgmltag>WEB-INF/web.xml</sgmltag> configuration file: + </para> + <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/prog-Developer_Guide-Advanced_features-Configuring_ResourceServlet.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + This servlet is strictly limited in what can be processed to the RichFaces resource libraries only. + </para> + </section> + + <section id="sect-Developer_Guide-Advanced_features-Resource_mapping"> + <title>Resource mapping</title> + <para> + RichFaces resources are determined by notion of resource libraries and load by standard JSF resource handling mechanism. + </para> + <para> + There are situations where it may be favourable to use alternative resource location: + </para> + <itemizedlist> + <listitem> + <para> + loading modified resource (either patched version, alternative version, compressed resource) + </para> + </listitem> + <listitem> + <para> + loading resource from external location (HTTP server, Content Delivery Network) + </para> + </listitem> + </itemizedlist> + <section id="sect-Developer_Guide-Advanced_features-Configuring_resource_mapping"> + <title>Configuring resource mapping</title> + <para> + Resource mapping feature is in default state disabled. You can enable it with contextual parameter <code>org.richfaces.resourceMapping.enabled</code>. + </para> + <para> + Resource mapping consist of properties file with records in format: + </para> + <programlisting>resourceLibrary:resourceName=resourceLocation</programlisting> + <para> + It is possible to define custom resource mapping configuration file using contextual parameter identifying class-path location where file resides: <code>org.richfaces.resourceMapping.mappingFile</code> + </para> + <para> + Location of resources is determined by resource location root and <code>resourceLocation</code> configured in file. + Since <code>resourceLocation</code> can point to external locations, you can point it to completely other server, these locations are determined + In other cases resource location root can be configured using contextual parameter <code>org.richfaces.resourceMapping.location</code> and it can contain EL expressions. + </para> + <para> + By default, resource mapping file and location root are determined by current resource loading strategy. + </para> + <para> + Following sample shows usage of <code>web.xml</code> and <code>META-INF/custom-mapping.properties</code> configurations: + </para> + <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/prog-Developer_Guide-Advanced_features-Configuring_resource_mapping_web_xml.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + First <code>context-param</code> is enabling resource mapping. Both other context-params are configuring the behavior. + </para> + <para> + Second <code>context-param</code> instructs RichFaces to look for <code>META-INF/custom-mapping.properties</code> file on class-path (either in your WAR: <code>WEB-INF/classes/META-INF/custom-mapping.properties</code> or any JAR on class-path in <code>META-INF/custom-mapping.properties</code>). + </para> + <para> + Last <code>context-param</code> configures the root resource location and uses expressions <code>#{facesContext.externalContext.requestContextPath}</code> to retrieve context path and <code>#{resourceLocation}</code> to retrieve location of specific resource (as provided from resource mapping configuration file). + </para> + <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/prog-Developer_Guide-Advanced_features-Configuring_resource_mapping_custom_mappping_properties.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + First property in the <code>META-INF/custom-mapping.properties</code> specifies resource mapping for resource with qualifier <code>javax.faces:jsf.js</code> which stands for Java Server Faces 2.0 JavaScript implementation. It instructs resource handler to look for <code>patched-jsf.js</code> source file. + Using the resource location root, it will specifically look for <code>#{facesContext.externalContext.requestContextPath}/resources/com.acme/patched-jsf.js</code> + </para> + <para> + Second property defines mapping for <code>jquery.js</code> resource. This line instructs resource handler to locate this resource on external URL, specifically from CDN. + </para> + <para> + Note that several resources can point to one location, which will in turn cause browser to load only one resource which should contain all resources. + </para> + </section> + </section> + + <section id="sect-Developer_Guide-Advanced_features-Resource_loading_strategies"> + <title>Resource loading strategies</title> + <para> + Resource loading strategies are special configuration of resource mapping suitable in lot of cases. + </para> + <para> + RichFaces framework bundles static versions of all components' resources which are processed to optimize performance in certain scenarios: + </para> + <itemizedlist> + <listitem> + <para> + <emphasis>static resources</emphasis> - suitable for environments, where dynamic generation is not enough performant or can't be processed at all + </para> + </listitem> + <listitem> + <para> + <emphasis>compression</emphasis> - suitable as network bandwidth and client performance optimization and client side code obfuscation + </para> + </listitem> + <listitem> + <para> + <emphasis>packing</emphasis> - suitable for providing dependencies for all components in one package, limiting number of requests to one per resource type + </para> + </listitem> + </itemizedlist> + <para> + Previous features aren't configured directly, it is necessary to choose project stages in which given feature will be applied. + </para> + <para> + It is necessary to choose stages, where compression is applied and where packed resource will be used. If both compression and packing are disable, simple static resources will be served. + </para> + <section id="sect-Developer_Guide-Advanced_features-Configuring_resource_loading_strategies"> + <title>Configuring resource loading strategies</title> + <para> + It is possible to provide following options for project stages: <code>None, Development, UnitTest, SystemTest, Production, All</code>. + </para> + <para> + For configuration, you can use any combination of project stages (separated by commas) or keywords None (for feature turned off in all stages) or All (for feature turned off in all stages). + </para> + <para> + Compression is configured in <code>web.xml</code> using <code>context-param</code> <code>org.richfaces.resourceMapping.compressedStages</code>. + Compression is set to <code>Production,SystemTest</code>, enabling this feature for production and system testing. + </para> + <para> + Packing is configured in <code>web.xml</code> using <code>context-param</code> <code>org.richfaces.resourceMapping.packedStages</code>. + Packing is set to <code>All</code>, enabling this feature in all stages. + </para> + <para> + It specifically means that with resource mapping enabled, packed resources are served and compression is turned off in development and unit tests and turned on in production and for system tests. + </para> + <para> + Following sample turns off packing, so only compression will be applied. + </para> + <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/prog-Developer_Guide-Advanced_features-Configuring_resource_loading_strategies.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + Notice that resource mapping needs to be enabled for serving static resources + </para> + <para> + For serving static resources, you will need to turn off both compression and packing. + </para> + <para> + Note that resource loading strategies are just special case of resource mapping, thus once you will provide custom resource mapping configuration or location, bundled default resources won't be referenced correctly. For using compressed/packed resources you will need to copy properties from one of files located in <code>richfaces-components-ui.jar:/META-INF/richfaces/staticResourceMapping/</code>. + </para> + </section> + </section> + </section> </chapter> Added: modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/prog-Developer_Guide-Advanced_features-Configuring_ResourceServlet.xml_sample =================================================================== --- modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/prog-Developer_Guide-Advanced_features-Configuring_ResourceServlet.xml_sample (rev 0) +++ modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/prog-Developer_Guide-Advanced_features-Configuring_ResourceServlet.xml_sample 2011-11-02 16:29:54 UTC (rev 22870) @@ -0,0 +1,10 @@ +<servlet> + <servlet-name>Resource Servlet</servlet-name> + <servlet-class>org.richfaces.webapp.ResourceServlet</servlet-class> + <load-on-startup>1</load-on-startup> +</servlet> + +<servlet-mapping> + <servlet-name>Resource Servlet</servlet-name> + <url-pattern>/org.richfaces.resources/*</url-pattern> +</servlet-mapping> \ No newline at end of file Added: modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/prog-Developer_Guide-Advanced_features-Configuring_resource_loading_strategies.xml_sample =================================================================== --- modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/prog-Developer_Guide-Advanced_features-Configuring_resource_loading_strategies.xml_sample (rev 0) +++ modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/prog-Developer_Guide-Advanced_features-Configuring_resource_loading_strategies.xml_sample 2011-11-02 16:29:54 UTC (rev 22870) @@ -0,0 +1,9 @@ +<context-param> + <param-name>org.richfaces.resourceMapping.enabled</param-name> + <param-value>true</param-value> +</context-param> + +<context-param> + <param-name>org.richfaces.resourceMapping.packedStages</param-name> + <param-value>None</param-value> +</context-param> \ No newline at end of file Added: modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/prog-Developer_Guide-Advanced_features-Configuring_resource_mapping_custom_mappping_properties.xml_sample =================================================================== --- modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/prog-Developer_Guide-Advanced_features-Configuring_resource_mapping_custom_mappping_properties.xml_sample (rev 0) +++ modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/prog-Developer_Guide-Advanced_features-Configuring_resource_mapping_custom_mappping_properties.xml_sample 2011-11-02 16:29:54 UTC (rev 22870) @@ -0,0 +1,2 @@ +javax.faces:jsf.js=patched-jsf.js +jquery.js=http://some.cdn/jquery/1.6.4/jquery.min.js \ No newline at end of file Added: modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/prog-Developer_Guide-Advanced_features-Configuring_resource_mapping_web_xml.xml_sample =================================================================== --- modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/prog-Developer_Guide-Advanced_features-Configuring_resource_mapping_web_xml.xml_sample (rev 0) +++ modules/docs/trunk/Developer_Guide/src/main/docbook/en-US/extras/prog-Developer_Guide-Advanced_features-Configuring_resource_mapping_web_xml.xml_sample 2011-11-02 16:29:54 UTC (rev 22870) @@ -0,0 +1,14 @@ +<context-param> + <param-name>org.richfaces.resourceMapping.enabled</param-name> + <param-value>true</param-value> +</context-param> + +<context-param> + <param-name>org.richfaces.resourceMapping.mappingFile</param-name> + <param-value>META-INF/custom-mapping.properties</param-value> +</context-param> + +<context-param> + <param-name>org.richfaces.resourceMapping.location</param-name> + <param-value>#{facesContext.externalContext.requestContextPath}/resources/com.acme/#{resourceLocation}</param-value> +</context-param> \ No newline at end of file