Deploying resources in a restricted environment

Added support to deploy resources inside JARs from the Servlet 3.0 compliant - location, META-INF/resources. If Click is running on a Servlet 3.0 - server, it won't deploy its resources, but rely on the container to - serve the resources directly + location, META-INF/resources. Click's own pre-packaged resources + are now also located in the JAR under META-INF/resources [570].

Modified: incubator/click/trunk/click/documentation/docs/upgrade-path.html URL: http://svn.apache.org/viewvc/incubator/click/trunk/click/documentation/docs/upgrade-path.html?rev=798708&r1=798707&r2=798708&view=diff ============================================================================== --- incubator/click/trunk/click/documentation/docs/upgrade-path.html (original) +++ incubator/click/trunk/click/documentation/docs/upgrade-path.html Tue Jul 28 20:55:47 2009 @@ -99,8 +99,8 @@ Page.getHeadElements().

- Click automatically deploy resources from the classpath that are located - under the directory META-INF/web. + Click automatically deploy resources from JARs and folders on the + classpath that are located under the directory META-INF/web.

The Servlet 3.0 specification introduced a similar concept where resources can be packaged in a JAR and served directly without having to be Modified: incubator/click/trunk/click/documentation/xdocs/src/docbook/click/chapter-configuration.xml URL: http://svn.apache.org/viewvc/incubator/click/trunk/click/documentation/xdocs/src/docbook/click/chapter-configuration.xml?rev=798708&r1=798707&r2=798708&view=diff ============================================================================== --- incubator/click/trunk/click/documentation/xdocs/src/docbook/click/chapter-configuration.xml (original) +++ incubator/click/trunk/click/documentation/xdocs/src/docbook/click/chapter-configuration.xml Tue Jul 28 20:55:47 2009 @@ -1010,29 +1010,153 @@ for that control. - It is generally easier to work with unpacked WARs and most servlet - containers do just that. However some contains such as WebLogic (at least - version 10) does not. To enable WebLogic to unpack the WAR go to the - Admin Console > server node > Web Applications - tab and check the Archived Real Path Enabled parameter. - + + Deploying resources in a restricted environment - If Click cannot deploy resources because of restricted file system - permissions, warning messages will be logged. - + It is generally easier to work with unpacked WARs and most servlet + containers do just that. However some contains such as WebLogic (at least + version 10) does not. To enable WebLogic to unpack the WAR go to the + Admin Console > server node > Web Applications + tab and check the Archived Real Path Enabled parameter. + + + If Click cannot deploy resources because the WAR/EAR is not unpacked + or because of restricted file system permissions, warning messages will be + logged. + + + Note: if your application is + running on a Servlet 3.0 compliant server, there is + no need to deploy resources in restricted environments. Servlet 3.0 + provide a feature where if the server cannot find a resource in the root + directory of the webapp, it will look for the resource under + 'META-INF/resources', and if found, serve it up. + Since Click packages its resources under + 'META-INF/resources' as well, there is no need to + deploy the resources. + - If your application server does not unpack the WAR/EAR or has restricted - permissions, you will need to package up these auto deployed files in your web - applications WAR file. To do this you should run you application on a development - machine without these restrictions and then package up the deployed files into - the WAR/EAR before deployment. - + Click also provides a number of options to make resources available + in restricted environments which is covered below: + + + + + Add a mapping in web.xml to inform + ClickServlet to serve static resources. This feature is made available + through the ResourceService + interface and its default implementation, + ClickResourceService. + Below is an example: + + + ClickServlet + org.apache.click.ClickServlet + 0 + + + + ClickServlet + *.htm + + + + + ClickServlet + /click/* +]]> + + Now ClickServlet will serve all static /click/* + resources directly from Click's JAR files. + + + One restriction of ClickResourceService is it only serves + resources from the /click/* folder. So if you use + third-party Click libraries that serve their resources from a different + folder e.g. /clickclick/*, this option won't work + out-of-the-box. + + + Also note that with this option Click's resources are served + directly from the JAR files, you won't be able to customize the resources, + if for example you want change the default styling through CSS. + + + + Use the DeployTask to deploy Click's static resources at build + time to your web application. With this option Click's static resources + can be copied to the root directory of your webapp, where you can + customize the resources as you see fit. The DeployTask is an Ant Task + you can incorporate into your build script. + + Currently the DeployTask is part of the click-dev-tools-xxx.jar + which can be found in your Click distribution under the lib + folder. + + To use this Ant Task, ensure the click-dev-tools-xxx.jar + is available on your build classpath and add the following target to your + build.xml: + + + + + +]]> + + We use the <deploy> Ant Task and specify + the attributes dir and todir. + dir specifies the source + directory to scan for JARs and folders containing static resources, + while todir specifies the target + directory where the resources should be copied to. + + + dir should point to your web application's + WEB-INF folder, since that is where Click's JARs + will be located. todir should point to your web + application's root directory, since that is where Click's resources + will be served from. + + + The DeployTask also generates an HTML report in the same folder + where the build script is executed from. The report will indicate + which resources was deployed and also which resources in your webapp + root directory is outdated. Resources can become outdated if you + upgrade to a new version of Click and certain Click resources were + updated. + + + + Click resources are packaged in JARs under the directory + META-INF/resources. You can use your favorite IDE + to navigate into the JARs and copy all the resources from + META-INF/resources to your webapp root directory. + Just remember to copy the resources in the same structure as they + appear under META-INF/resources. + + + + You can also access Click's resources by deploying your + application on a development machine where there are no file system + restrictions and the WAR/EAR is unpacked. Then you can copy the + deployed resources to your webapp root directory. + + + + + Deploying Custom Resources Click supports two ways of deploying pre-configured resources (templates, stylesheets, JavaScript etc.) from a Jar to a web application. + (This assumes that the environment Click is running in supports having + write access to the file system and that the WAR is unpacked.) @@ -1046,12 +1170,6 @@ By packaging the resources (stylesheets, JavaScript, Images etc.) into a special folder called 'META-INF/resources'. - Please note that if Click is executing inside a Servlet 3.0 compliant - server, it won't deploy its resources. Instead it will rely on the - Servlet 3.0 feature where if the server cannot find a resource - in the root directory of the webapp, it will look for the resource - under 'META-INF/resources', and if it is found, - serve it up. @@ -1060,9 +1178,9 @@ Controls, lets look at option #2. - When Click starts up, it scans each Jar in the classpath for - specially marked entries starting with 'META-INF/resources/'. (Please note - that even though Click will scan the entire classpath it is strongly + When Click starts up, it scans each Jar and folder on the classpath + for specially marked entries starting with 'META-INF/resources/'. (Please + note that even though Click will scan the entire classpath it is strongly recommended to host your Jar files under your WAR lib folder e.g. WEB-INF/lib. Sharing Jars on the classpath can lead to class loading issues.) @@ -1097,9 +1215,9 @@ 'webapp/mycorp/edit_customer.css'. - Option #2 is especially useful when you need to deploy a large number - of resources from a Jar. Note, only Jars placed under the - 'WEB-INF/lib' folder will be deployed. + Option #2 is the recommended approach for deploying your own + resources since it makes the managing and maintenance of resources much + easier. Modified: incubator/click/trunk/click/extras/src/org/apache/click/extras/gae/GoogleAppEngineListener.java URL: http://svn.apache.org/viewvc/incubator/click/trunk/click/extras/src/org/apache/click/extras/gae/GoogleAppEngineListener.java?rev=798708&r1=798707&r2=798708&view=diff ============================================================================== --- incubator/click/trunk/click/extras/src/org/apache/click/extras/gae/GoogleAppEngineListener.java (original) +++ incubator/click/trunk/click/extras/src/org/apache/click/extras/gae/GoogleAppEngineListener.java Tue Jul 28 20:55:47 2009 @@ -133,16 +133,9 @@ * the webapp. Since GAE doesn't allow writing to disk, Click cannot * automatically deploy its resources. *

- * Instead you will have to manually add Click's resources in your GAE - * application's "/war" folder. To do this create a click - * folder under your /war directory -> "/war/click". - *

- * Next you need to copy the resources from the click-core.X.X.X.jar and - * click-extras.X.X.X.jar. Use your favorite IDE or ZIP utility to open the - * jars and navigate to "META-INF/resources/" where you will find the - * "/click" folder with all the resources packaged for that jar. Simply - * copy the content of the "/click" folder to your GAE folder: - * "/war/click". + * Please see the user-guide section, + * Deploying resources in a restricted environment, + * for various solutions. */ public class GoogleAppEngineListener implements ServletContextListener {