You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@click.apache.org by sa...@apache.org on 2009/07/28 22:55:47 UTC
svn commit: r798708 - in /incubator/click/trunk/click: documentation/docs/
documentation/xdocs/src/docbook/click/
extras/src/org/apache/click/extras/gae/
Author: sabob
Date: Tue Jul 28 20:55:47 2009
New Revision: 798708
URL: http://svn.apache.org/viewvc?rev=798708&view=rev
Log:
added docs: deploying resources in restricted environments
Modified:
incubator/click/trunk/click/documentation/docs/faq.html
incubator/click/trunk/click/documentation/docs/roadmap-changes.html
incubator/click/trunk/click/documentation/docs/upgrade-path.html
incubator/click/trunk/click/documentation/xdocs/src/docbook/click/chapter-configuration.xml
incubator/click/trunk/click/extras/src/org/apache/click/extras/gae/GoogleAppEngineListener.java
Modified: incubator/click/trunk/click/documentation/docs/faq.html
URL: http://svn.apache.org/viewvc/incubator/click/trunk/click/documentation/docs/faq.html?rev=798708&r1=798707&r2=798708&view=diff
==============================================================================
--- incubator/click/trunk/click/documentation/docs/faq.html (original)
+++ incubator/click/trunk/click/documentation/docs/faq.html Tue Jul 28 20:55:47 2009
@@ -78,13 +78,15 @@
<li><a href="#performance">What is the performance of Click?</a>
</li>
<li><a href="#unit-testing">How do I unit test Click pages?</a>
- </li>
+ </li>
+ <li><a href="#restricted-env">How do I deploy Click resources in restricted environments?</a>
+ </li>
<li><a href="#logging">Why doesn't Click use Commons Logging / Log4J for logging?</a>
</li>
<li><a href="#why-velocity">Why doesn't Click use FreeMarker as the default rendering engine?</a>
- </li>
+ </li>
<li><a href="#why-click">Why develop a new Web Application Framework?</a>
- </li>
+ </li>
</ol>
<p> </p>
@@ -94,8 +96,8 @@
<b>1. How to get help?</b>
</dt>
<dd>
- OK you have read the documentation and reviewed the
- <a href="examples.html">Examples</a> applications, but there is still something
+ OK you have read the documentation and reviewed the
+ <a href="examples.html">Examples</a> applications, but there is still something
you still don't understand. What do you do?
<p/>
You go to the click-user or click-development mail
@@ -757,8 +759,30 @@
</dd>
+ <dt><a name="restricted-env"></a>
+ <b>21. How do I deploy Click resources in restricted environments?</b>
+ </dt>
+ <dd>
+ Often times one need to run Click applications in restricted environments.
+ Examples include:
+ <p/>
+ <ul>
+ <li>WAR/EAR is not unpacked - common with WebLogic and Websphere servers</li>
+ <li>File system permissions are restricted</li>
+ <li>Hosting applications on <a href="http://code.google.com/appengine/docs/java/overview.html">Google App Engine</a></li>
+ </ul>
+ Click works perfectly fine in these environments. The only issue one might
+ encounter is Click's auto-deploy feature where static resources are copied
+ to the webapp root directory at application startup. In restricted environments
+ it might not be possible for Click to deploy its resources.
+ <p/>
+ Please see the user-guide section, <a href="user-guide/html/ch04s03.html#deploying-restricted-env">Deploying resources in a restricted environment</a>,
+ for various solutions.
+ </dd>
+
+
<dt><a name="logging"></a>
- <b>21. Why doesn't Click use Commons Logging / Log4J for logging?</b>
+ <b>22. Why doesn't Click use Commons Logging / Log4J for logging?</b>
</dt>
<dd>
Click by default does not use Commons Logging / Log4J to avoid the class
@@ -771,7 +795,7 @@
<dt><a name="why-velocity"></a>
- <b>22. Why doesn't Click use FreeMarker instead of Velocity as the default template engine?</b>
+ <b>23. Why doesn't Click use FreeMarker instead of Velocity as the default template engine?</b>
</dt>
<dd>
FreeMarker is a powerful templating engine which was evaluated along side
@@ -785,7 +809,7 @@
<dt><a name="why-click"></a>
- <b>23. Why develop a new Web Application Framework?</b>
+ <b>24. Why develop a new Web Application Framework?</b>
</dt>
<dd>
Because the existing frameworks did not meet my needs. Struts doesn't really do much,
Modified: incubator/click/trunk/click/documentation/docs/roadmap-changes.html
URL: http://svn.apache.org/viewvc/incubator/click/trunk/click/documentation/docs/roadmap-changes.html?rev=798708&r1=798707&r2=798708&view=diff
==============================================================================
--- incubator/click/trunk/click/documentation/docs/roadmap-changes.html (original)
+++ incubator/click/trunk/click/documentation/docs/roadmap-changes.html Tue Jul 28 20:55:47 2009
@@ -147,6 +147,13 @@
<a href="user-guide/html/ch02s12.html">here</a> and
the section on Control HEAD elements <a href="user-guide/html/ch03s05.html">here</a>.
</li>
+ <li>
+ Added a new section, <a href="user-guide/html/ch04s03.html#deploying-restricted-env">Deploying resources in a restricted environment</a>,
+ describing how to deploy static resources in environments where
+ WAR/EAR are not unpacked or where file system permissions are
+ restricted, such as
+ <a class="external" target="_blank" href="http://code.google.com/appengine/docs/java/overview.html">Google App Engine</a>.
+ </li>
</ul>
<div style="margin-left: -2em; margin-top: 1.5em; margin-bottom: 1em;">
@@ -202,9 +209,8 @@
</li>
<li class="change">
Added support to deploy resources inside JARs from the Servlet 3.0 compliant
- location, <tt>META-INF/resources</tt>. 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, <tt>META-INF/resources</tt>. Click's own pre-packaged resources
+ are now also located in the JAR under <tt>META-INF/resources</tt>
[<a target="_blank" href="https://issues.apache.org/jira/browse/CLK-570">570</a>].
</li>
<li class="change">
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 @@
<a href="click-api/org/apache/click/Page.html#getHeadElements()">Page.getHeadElements()</a>.
</li>
<li class="change">
- Click automatically deploy resources from the classpath that are located
- under the directory <tt>META-INF/web</tt>.
+ Click automatically deploy resources from JARs and folders on the
+ classpath that are located under the directory <tt>META-INF/web</tt>.
<p/>
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.
</para>
- <para>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
- <emphasis>Admin Console > server node > Web Applications</emphasis>
- tab and check the <emphasis>Archived Real Path Enabled</emphasis> parameter.
- </para>
+ <sect2 id="deploying-restricted-env" remap="h3">
+ <title>Deploying resources in a restricted environment</title>
- <para>If Click cannot deploy resources because of restricted file system
- permissions, warning messages will be logged.
- </para>
+ <para>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
+ <emphasis>Admin Console > server node > Web Applications</emphasis>
+ tab and check the <emphasis>Archived Real Path Enabled</emphasis> parameter.
+ </para>
+
+ <para>If Click cannot deploy resources because the WAR/EAR is not unpacked
+ or because of restricted file system permissions, warning messages will be
+ logged.
+ </para>
+
+ <para><emphasis role="bold">Note: </emphasis>if your application is
+ running on a <emphasis>Servlet 3.0</emphasis> 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
+ <emphasis>'META-INF/resources'</emphasis>, and if found, serve it up.
+ Since Click packages its resources under
+ <emphasis>'META-INF/resources'</emphasis> as well, there is no need to
+ deploy the resources.
+ </para>
- <para>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.
- </para>
+ <para>Click also provides a number of options to make resources available
+ in restricted environments which is covered below:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Add a mapping in <emphasis>web.xml</emphasis> to inform
+ ClickServlet to serve static resources. This feature is made available
+ through the <ulink url="../../click-api/org/apache/click/service/ResourceService.html">ResourceService</ulink>
+ interface and its default implementation,
+ <ulink url="../../click-api/org/apache/click/service/ClickResourceService.html">ClickResourceService</ulink>.
+ Below is an example:
+ </para>
+ <programlisting language="xml"><![CDATA[<servlet>
+ <servlet-name>ClickServlet</servlet-name>
+ <servlet-class>org.apache.click.ClickServlet</servlet-class>
+ <load-on-startup>0</load-on-startup>
+</servlet>
+
+<servlet-mapping>
+ <servlet-name>ClickServlet</servlet-name>
+ <url-pattern>*.htm</url-pattern>
+</servlet-mapping>
+
+ <!-- Inform ClickServlet to serve static resources contained under the /click/*
+ directory directly from Click's JAR files. -->
+<servlet-mapping>
+ <servlet-name>ClickServlet</servlet-name>
+ <url-pattern>/click/*</url-pattern>
+</servlet-mapping>]]></programlisting>
+
+ <para>Now ClickServlet will serve all static <varname>/click/*</varname>
+ resources directly from Click's JAR files.
+ </para>
+
+ <para>One restriction of ClickResourceService is it only serves
+ resources from the <emphasis>/click/*</emphasis> folder. So if you use
+ third-party Click libraries that serve their resources from a different
+ folder e.g. <emphasis>/clickclick/*</emphasis>, this option won't work
+ out-of-the-box.
+ </para>
+
+ <para>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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>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.
+ </para>
+ <para>Currently the DeployTask is part of the <filename>click-dev-tools-xxx.jar</filename>
+ which can be found in your Click distribution under the <emphasis>lib</emphasis>
+ folder.
+ </para>
+ <para>To use this Ant Task, ensure the <filename>click-dev-tools-xxx.jar</filename>
+ is available on your build classpath and add the following target to your
+ <filename>build.xml</filename>:
+ </para>
+ <programlisting language="xml"><![CDATA[<target name="deploy" description="Deploy static resources">
+ <taskdef name="deploy"
+ classname="org.apache.click.tools.deploy.DeployTask"
+ classpath="<click-distribution>/lib/click-dev-tasks-1.1.jar"/>
+
+ <deploy dir="<webapp-root>/WEB-INF"
+ todir="<webapp-root>"/>
+</target>]]> </programlisting>
+
+ <para>We use the <emphasis><deploy></emphasis> Ant Task and specify
+ the attributes <varname>dir</varname> and <varname>todir</varname>.
+ <varname>dir</varname> specifies the <emphasis>source</emphasis>
+ directory to scan for JARs and folders containing static resources,
+ while <varname>todir</varname> specifies the <emphasis>target</emphasis>
+ directory where the resources should be copied to.
+ </para>
+
+ <para><varname>dir</varname> should point to your web application's
+ <emphasis>WEB-INF</emphasis> folder, since that is where Click's JARs
+ will be located. <varname>todir</varname> should point to your web
+ application's root directory, since that is where Click's resources
+ will be served from.
+ </para>
+
+ <para>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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>Click resources are packaged in JARs under the directory
+ <emphasis>META-INF/resources</emphasis>. You can use your favorite IDE
+ to navigate into the JARs and copy all the resources from
+ <emphasis>META-INF/resources</emphasis> to your webapp root directory.
+ Just remember to copy the resources in the same structure as they
+ appear under <emphasis>META-INF/resources</emphasis>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>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.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ </sect2>
<sect2 id="deploying-custom-resources" remap="h3">
<title>Deploying Custom Resources</title>
<para> 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.)
</para>
<orderedlist>
@@ -1046,12 +1170,6 @@
<listitem>
<para>By packaging the resources (stylesheets, JavaScript, Images etc.)
into a special folder called <emphasis>'META-INF/resources'</emphasis>.
- 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 <emphasis>'META-INF/resources'</emphasis>, and if it is found,
- serve it up.
</para>
</listitem>
</orderedlist>
@@ -1060,9 +1178,9 @@
<link linkend="application-controls">Controls</link>, lets look at option #2.
</para>
- <para>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
+ <para>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.)
</para>
@@ -1097,9 +1215,9 @@
<emphasis>'webapp/mycorp/edit_customer.css'</emphasis>.
</para>
- <para>Option #2 is especially useful when you need to deploy a large number
- of resources from a Jar. Note, only Jars placed under the
- <emphasis>'WEB-INF/lib'</emphasis> folder will be deployed.
+ <para>Option #2 is the recommended approach for deploying your own
+ resources since it makes the managing and maintenance of resources much
+ easier.
</para>
</sect2>
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.
* <p/>
- * Instead you will have to manually add Click's resources in your GAE
- * application's "<tt>/war</tt>" folder. To do this create a <tt>click</tt>
- * folder under your <tt>/war</tt> directory -> "<tt>/war/click</tt>".
- * <p/>
- * 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 "<tt>META-INF/resources/</tt>" where you will find the
- * "<tt>/click</tt>" folder with all the resources packaged for that jar. Simply
- * copy the content of the "<tt>/click</tt>" folder to your GAE folder:
- * "<tt>/war/click</tt>".
+ * Please see the user-guide section,
+ * <a href="../../../../../../user-guide/html/ch04s03.html#deploying-restricted-env">Deploying resources in a restricted environment</a>,
+ * for various solutions.
*/
public class GoogleAppEngineListener implements ServletContextListener {