click-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sa...@apache.org
Subject svn commit: r798708 - in /incubator/click/trunk/click: documentation/docs/ documentation/xdocs/src/docbook/click/ extras/src/org/apache/click/extras/gae/
Date Tue, 28 Jul 2009 20:55:47 GMT
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>&nbsp;</p>
 
@@ -94,8 +96,8 @@
       <b>1.&nbsp; 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.&nbsp; 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.&nbsp; Why doesn't Click use Commons Logging / Log4J for logging?</b>
+      <b>22.&nbsp; 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.&nbsp; Why doesn't Click use FreeMarker instead of Velocity as the
default template engine?</b>
+      <b>23.&nbsp; 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.&nbsp; Why develop a new Web Application Framework?</b>
+      <b>24.&nbsp; 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 &gt; server node &gt; 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 &gt; server node &gt; 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>&lt;deploy&gt;</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 {
 



Mime
View raw message