Author: reinhard
Date: Mon Feb 21 08:21:30 2005
New Revision: 154686
URL: http://svn.apache.org/viewcvs?view=rev&rev=154686
Log:
use hypens instead of capitals
Added:
cocoon/whiteboard/doc-repos/2.2/src/documentation/content/xdocs/custom-cocoon-based-project-using-ant/
- copied from r154684,
cocoon/whiteboard/doc-repos/2.2/src/documentation/content/xdocs/CustomCocoonBasedProjectUsingAnt/
cocoon/whiteboard/doc-repos/2.2/src/documentation/content/xdocs/custom-cocoon-based-project-using-ant/content-reinhard_en.html
cocoon/whiteboard/doc-repos/2.2/src/documentation/content/xdocs/custom-cocoon-based-project-using-ant/content_en.html
- copied unchanged from r154685,
cocoon/whiteboard/doc-repos/2.2/src/documentation/content/xdocs/CustomCocoonBasedProjectUsingAnt/content_en.html
cocoon/whiteboard/doc-repos/2.2/src/documentation/content/xdocs/custom-cocoon-based-project-using-ant/files/example-repository.zip
(with props)
cocoon/whiteboard/doc-repos/2.2/src/documentation/content/xdocs/getting-started/comments_en.xml
Removed:
cocoon/whiteboard/doc-repos/2.2/src/documentation/content/xdocs/CustomCocoonBasedProjectUsingAnt/content_en.html
cocoon/whiteboard/doc-repos/2.2/src/documentation/content/xdocs/CustomCocoonBasedProjectUsingAnt/files/build-cocoon-targets.xml
cocoon/whiteboard/doc-repos/2.2/src/documentation/content/xdocs/CustomCocoonBasedProjectUsingAnt/files/dirlayout.png
cocoon/whiteboard/doc-repos/2.2/src/documentation/content/xdocs/CustomCocoonBasedProjectUsingAnt/files/dirlayout.psd
cocoon/whiteboard/doc-repos/2.2/src/documentation/content/xdocs/CustomCocoonBasedProjectUsingAnt/meta.xml
Added:
cocoon/whiteboard/doc-repos/2.2/src/documentation/content/xdocs/custom-cocoon-based-project-using-ant/content-reinhard_en.html
URL:
http://svn.apache.org/viewcvs/cocoon/whiteboard/doc-repos/2.2/src/documentation/content/xdocs/custom-cocoon-based-project-using-ant/content-reinhard_en.html?view=auto&rev=154686
==============================================================================
---
cocoon/whiteboard/doc-repos/2.2/src/documentation/content/xdocs/custom-cocoon-based-project-using-ant/content-reinhard_en.html
(added)
+++
cocoon/whiteboard/doc-repos/2.2/src/documentation/content/xdocs/custom-cocoon-based-project-using-ant/content-reinhard_en.html
Mon Feb 21 08:21:30 2005
@@ -0,0 +1,1196 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html><head>
+ <title>Building your own Cocoon project using Ant</title>
+</head>
+<body>
+<h1>Building your own Cocoon project using Ant</h1>
+
+
+
+
+
+
+
+
+
+
+
+
+<p>Now that you've studied Cocoon and you are convinced it is worth
+spending your time on, you want to try your hand at your own project.
+There are several ways to start your own project. This is just one of
+them. Please note, that this document requires Cocoon 2.2 because of
+use of the newly introduced import-feature in configuration files.<br>
+</p>
+
+
+
+
+
+
+
+
+
+
+
+
+<p>If you develop your own Cocoon based project, you usually want to be
+as independant of Cocoon. This means that you should be able to "drop
+in" any version of Cocoon 2.2 into your project and it should become
+buildable and delployable.<br>
+ </p>
+
+
+
+
+
+
+
+
+
+
+
+
+<p>For this purpose there is a clean separation between your project,
+the build system and the Cocoon version(s) that is (are) used necessary.<br>
+</p>
+
+
+
+
+
+
+
+
+
+
+
+
+<h2>Goals</h2>
+
+
+
+
+
+
+
+
+
+
+
+
+<ul>
+
+
+
+
+
+
+
+
+
+
+
+
+ <li>build a project that is based on Cocoon 2.2<br>
+</li><li>clean separation between project specific files and Cocoon
distribution</li>
+
+ <li>support different server environments with their own configuration
needs</li>
+ <li>only use Ant</li>
+ <li>make build scripts easily extensbile by overriden and interception using
Ant<br>
+</li>
+ <li>use clear naming concepts so that the build system can be
+integrated into already existing build systems without having to expect
+troubles because of naming conflicts<br>
+ </li>
+</ul>
+
+
+
+
+
+
+
+
+
+
+
+
+<h2>Prerequisites</h2>
+
+
+
+
+
+
+
+
+
+
+
+
+<ul>
+
+
+
+
+
+
+
+
+
+
+
+
+ <li>have Ant 1.6.2 or above installed properly (see <a
href="http://ant.apache.org";>Ant documentation</a> for more information)<br>
+ </li>
+ <li>setup a repository that includes Cocoon and your favorite servlet
container</li>
+</ul>
+
+
+
+
+
+
+
+
+
+
+
+
+<h1>Setting up your repository</h1>
+
+
+
+
+
+
+
+
+
+
+
+
+
+Including all Cocoon files or the container itself into your project
+might not be the best idea. It makes upgrading to newer Cocoon versions
+or just trying out whether everything still works with another version
+of Cocoon very difficult. In order to avoid this, set up a repository
+that contains all your Cocoon versions that you want to use in all your
+Cocoon based projects.<br>
+
+
+
+
+
+
+
+
+
+
+
+
+<br>
+
+
+
+
+
+
+
+
+
+
+
+
+<table style="width: 100%; text-align: left;" border="1" cellpadding="2"
cellspacing="2">
+
+
+
+
+
+
+
+
+
+
+
+
+ <tbody>
+ <tr>
+ <td style="vertical-align: top;">/rep/</td>
+ <td style="vertical-align: top;">
+ <p>the base directory of your repository (it has to be referenced in
your properties files)</p>
+ </td>
+ </tr>
+ <tr>
+ <td style="vertical-align: top;">/rep/cocoon/</td>
+ <td style="vertical-align: top;">contains all Cocoon versions that you
want to use in all your projects<br>
+ </td>
+ </tr>
+ <tr>
+ <td style="vertical-align: top;">/rep/cocoon/123456/</td>
+ <td style="vertical-align: top;">the version 123456 of Cocoon
+(needn't be a number but can be any string you like and has some
+meaning to you), this directory contains<span style="font-style: italic;">
local.build.properties</span> and <span style="font-style:
italic;">local.blocks.properties</span> so that you are able in the future to
find out very quickly which configuration you have used to build Cocoon<br>
+ </td>
+ </tr>
+ <tr>
+ <td style="vertical-align: top;">/rep/cocoon/123456/webapp/</td>
+ <td style="vertical-align: top;">the output of /build/webapp after
building Cocoon<br>
+You can build Cocoon the way you like by excluding all blocks that are not
necessary for your project.<br>
+ </td>
+ </tr>
+ </tbody>
+</table>
+
+
+
+
+
+
+
+
+
+
+
+
+<p>Additionally to Cocoon you can put the containers, that you use, into your
repository (Tomcat 5.0.30 is used as example):</p>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<table style="width: 100%; text-align: left;" border="1" cellpadding="2"
cellspacing="2">
+
+
+
+
+
+
+
+
+
+
+
+
+ <tbody>
+ <tr>
+ <td style="vertical-align: top;">/rep/container/<br>
+ </td>
+ <td style="vertical-align: top;">contains all containers<br>
+ </td>
+ </tr>
+ <tr>
+ <td style="vertical-align: top;">/rep/container/tomcat-5.0.30<br>
+ </td>
+ <td style="vertical-align: top;">base directory of Tomcat 5.0.30<br>
+ </td>
+ </tr>
+ <tr>
+ <td style="vertical-align:
top;">/rep/container/tomcat-5.0.30/container-build.xml<br>
+ </td>
+ <td style="vertical-align: top;"><br>
+ </td>
+ </tr>
+<tr>
+ <td style="vertical-align:
top;">/rep/container/tomcat-5.0.30/build-conf/**<br>
+ </td>
+ <td style="vertical-align: top;">contains all the directories and files
of your container that should be overriden (e.g. server.xml in Tomcat).<br>
+ </td>
+ </tr>
+ <tr>
+ <td style="vertical-align:
top;">/rep/container/tomcat-5.0.30/server.properties<br>
+ </td>
+ <td style="vertical-align: top;">contains container specific
properties:<br>
+ <pre> server.start.win=bin/startup.bat<br>
server.stop.win=bin/shutdown.bat</pre>
+ </td>
+ </tr>
+ <tr>
+ <td style="vertical-align: top;">/rep/container/tomcat-5.0.30/dist/</td>
+ <td style="vertical-align: top;">contains the unpacked version of the
container<br>
+ </td>
+ </tr>
+ </tbody>
+</table>
+
+
+
+
+
+
+
+
+
+
+
+
+<p>The container-build.xml script could look like this:</p>
+
+
+
+
+
+
+
+
+
+
+
+
+<pre><?xml version="1.0" encoding="UTF-8"
standalone="yes"?><br><project name="Cocoon build system"
default="create-tomcat-5.0.30"><br> <target
name="cocoon:create-tomcat-5.0.30"><br>
<echo>Using Tomcat 5.0.30 as servlet
container.</echo><br> <copy
todir="${cocoon.build.container.dir}" filtering="off"><br>
<fileset
dir="${cocoon.rep.container.dir}/dist"/><br>
</copy><br>
<!-- create platform specific file path --><br>
<dirname
property="tomcat.filter.server.webapp.path"
file="${basedir}/${cocoon.build.webapp.dir}}"/><br>
<filter token="tomcat.filter.server.webapp.path"
value="${tomcat.filter.server.webapp.path}"/>
<br> <copy
todir="${cocoon.build.container.dir}" filtering="on"
overwrite="true"><br>
<fileset
dir="${cocoon.rep.container.dir}/build-conf"/><br>
</copy><br>
</target><br></project></pre>
+
+
+
+
+
+
+
+
+
+
+
+
+<p>Note the name of the create target: It has to start with
+"cocoon:create-tomcat-" and has to end with the name of the directory
+where the container is put into. In this case tomcat-5.0.30. This name
+has to be unique as it is used in th build property files to identify
+the container that should be used.<br>
+</p>
+
+
+
+
+
+
+
+<p>Also note the filter <span style="font-family:
monospace;"></span>tomcat.filter.server.webapp.path
+which is applied to all files that are copied from
+/rep/container/tomcat-5.0.30/build-conf/**. Looking at
+/rep/container/tomcat-5.0.30/build-conf/conf/server.xml reveals
+following (Tomcat specific) configuration:<br>
+</p>
+
+
+
+
+
+
+
+<pre><Server port="8005" shutdown="SHUTDOWN" debug="0"><br>
<Service name="Catalina"><br> <Connector port="8080"
/><br> <Engine name="Catalina"
defaultHost="localhost"><br> <Logger
className="org.apache.catalina.logger.FileLogger"
/><br> <Host name="localhost"
appBase="@tomcat.filter.server.webapp.path@" /><br>
</Engine><br> </Service><br></Server></pre>
+
+
+
+
+
+
+
+<p>
+</p>
+
+
+
+
+
+
+
+
+
+
+
+
+<p>This minimal Tomcat configuration makes use of this filter to point to the
webapp directory.</p>
+
+
+
+
+
+
+
+<p>Find an example repository <a
href="files/example-repository.zip">here</a>.</p>
+
+
+
+
+
+
+
+
+
+
+
+
+
+<h1>Setting up your Cocoon based project</h1>
+
+
+
+
+
+
+
+
+
+
+
+
+
+<h2>Step 1: build.xml</h2>
+
+
+
+
+
+
+
+
+
+
+
+
+<p>Create a new directory for your Cocoon based project and create an XML file
that you name "build.xml" with following content:<br>
+</p>
+
+
+
+
+
+
+
+
+
+
+
+
+
+<pre><project name="my-project"
default="complete-ant"><br> <import
file="build/current-build-core.xml" optional="true"/><br>
<target name="complete-ant" description="call this, to download core build
descriptor"><br> <mkdir
dir="build"/><br> <get
<br>
src="http://svn.apache.org/viewcvs.cgi/*checkout*/cocoon/trunk/tools/external-project-build/generic-build.xml";
<br>
dest="build/current-build-core.xml" <br>
usetimestamp="true"<br>
ignoreerrors="true"<br>
/> <br>
</target><br></project></pre>
+
+
+
+
+
+
+
+
+
+
+
+
+<p>By using the get-task this script always uses the latest version of the
+build script. If you want to make sure that you use a particular
+version (e.g. you want to avoid unforseen surprises with new versions),
+you can import a specific version like
+http://svn.apache.org/viewcvs/cocoon/trunk/tools/external-project-build/generic-build.xml?view=auto&amp;rev=151382
+that uses revision 151382 of the build script.<br>
+</p>
+
+
+
+
+
+
+
+
+
+
+
+
+<h2>Step 2: Seeding your project</h2>
+
+
+
+
+
+
+
+
+
+
+
+
+<p>Now call<br>
+</p>
+
+
+
+
+
+
+
+
+
+
+
+
+<pre>ant</pre>
+
+
+
+
+
+
+
+
+
+
+
+
+<p>and</p>
+
+
+
+
+
+
+
+
+
+
+
+
+<pre>ant seed</pre>
+
+
+
+
+
+
+
+
+
+
+
+
+<p>The first call downloads the generic Ant script, the second calls
+the seed target of this generic script. After this you get following structure
+in your project directory:<br>
+</p>
+
+
+
+
+
+
+
+
+
+
+
+
+<pre>./java<br>./webapp<br>./conf<br>./lib<br>build.xml<br>project.properties<br>localhost.build.properties</pre>
+
+
+
+
+
+
+
+
+
+
+
+
+<h2>Step 3: Set following properties</h2>
+
+
+
+
+
+
+
+
+
+
+
+<p>After seeding your project you have to set following properties, before you
can build your project:<br>
+</p>
+
+
+
+
+
+
+
+
+
+
+
+
+<ul>
+
+
+
+
+
+
+
+
+
+
+
+
+ <li>cocoon.version [project.properties]<br>
+ </li>
+ <li>cocoon.container.version [project.properties]<br>
+ </li>
+ <li>cocoon.rep [localhost.build.properties]<br>
+ </li>
+</ul>
+
+
+
+
+
+
+
+
+
+
+
+
+<h2>Step 4: Building your project the first time<br>
+</h2>
+
+
+
+
+
+
+
+
+
+
+
+
+<p>This allows you to build the web application and the container:<br>
+</p>
+
+
+
+
+
+
+
+
+
+
+
+
+<pre>ant webapp<br>ant container</pre>
+
+
+
+
+
+
+
+
+
+
+
+
+<p>Now it's time to start the container <br>
+</p>
+
+
+
+
+
+
+
+
+
+
+
+
+<pre>ant run</pre>
+
+
+
+
+
+
+
+
+
+
+
+
+<p>Open your browser and access your servlet container via http. For
+most containers the container is available on port 8080 or 8888:<br>
+</p>
+
+
+
+
+
+
+
+
+
+
+
+
+<pre>http://localhost:8080</pre>
+
+
+
+
+
+
+
+
+
+
+
+
+<h2>List of available Ant targets<br>
+</h2>
+
+
+
+
+
+
+
+
+
+
+
+
+<p>The generic build script provides a couple of Ant targets that you
can use (output of ant -projecthelp)<br>
+</p>
+
+
+
+
+
+
+
+
+
+
+
+
+<pre> clean clean webapps
and container<br> clean-all clean *everything* in
the build dir<br> compile Compile Java
classes<br> complete-ant call this, to download core build
descriptor<br> container screate a container (uses
the property
'container.version')<br> run
run the container (currently it only works on windows boxes)<br> seed
seed a new Cocoon based
project<br> stop run
the container (currently it only works on windows
boxes)<br> war
create a web archive
(WAR)<br> webapp create the web
application</pre>
+
+
+
+
+
+
+
+
+
+
+
+
+<h2>Default directory structure</h2>
+
+
+
+
+
+
+
+
+
+
+<table style="width: 100%; text-align: left;" border="1" cellpadding="2"
cellspacing="2">
+
+
+
+
+
+
+
+
+
+
+ <tbody>
+ <tr>
+ <td style="vertical-align: top;">./java<br>
+ </td>
+ <td style="vertical-align: top;">The java directory contains all your
custom Java classes.</td>
+ </tr>
+ <tr>
+ <td style="vertical-align: top;">./webapp<br>
+ </td>
+ <td style="vertical-align: top;">The webapp directory contains your
Cocoon project files like sitemaps and all files that are references and used
by the sitemap.</td>
+ </tr>
+ <tr>
+ <td style="vertical-align: top;">./lib<br>
+ </td>
+ <td style="vertical-align: top;">Here is the place to put in all Java
libraries that do not come with Cocoon.</td>
+ </tr>
+ <tr>
+ <td style="vertical-align: top;">./conf<br>
+ </td>
+ <td style="vertical-align: top;">
+
+
+
+The conf directory contains configuration snippets. Those snippets can use Ant
filter tokens.</td>
+ </tr>
+ </tbody>
+</table>
+
+
+
+
+
+
+
+
+
+
+<h1>Project-specific configuration</h1>
+
+
+
+
+
+
+
+
+
+
+
+
+
+<h2>Ant target interception mechanism</h2>
+
+
+
+
+
+
+
+
+
+
+
+
+<p>If this is not enough for you, you can re-implement these targets by
+using some sort of interception mechanism. All of the targets above
+have a core, before and after target that can be overriden, e.g.:<br>
+</p>
+
+
+
+
+
+
+
+
+
+
+
+
+
+<pre>cocoon:core-compile<br>cocoon:before-compile<br>cocoon:after-compile</pre>
+
+
+
+
+
+
+
+
+
+
+
+
+<p>This way you can adjust or replace the behaviour of the generic build
script.<br>
+</p>
+
+
+
+
+
+
+
+
+
+
+
+
+<h2>Configuration targets</h2>
+
+
+
+
+
+
+
+
+
+
+
+
+<p>
+</p>
+
+
+
+
+
+
+
+
+
+
+
+
+
+<p>Additionally you can override following targets.<br>
+</p>
+
+
+
+
+
+
+
+
+
+
+
+
+<pre><target name="cocoon:setFilters"/><br><target
name="cocoon:complete-ant"/></pre>
+
+
+
+
+
+
+
+
+
+
+
+<h3>cocoon:setFilters</h3>
+
+
+
+
+
+
+
+
+
+
+<p>
+cocoon:setFilters allows you to declare project-specific filters that
+you want to use e.g. in your component configurations (./conf
+directory). For example:<br>
+</p>
+
+<pre><target name="cocoon:setFilters"><br> <filter
token="filter.mailserver" value="${mailserver}"/><br></target></pre>
+
+<p>Make sure that the property "mailserver" is set in
+project.properties or *.build.properties. The filter
+"filter.mailserver" is now useable in your configuration files.<br>
+</p>
+
+
+
+
+
+
+
+
+
+
+
+<h3>
+cocoon:complete-ant</h3>
+
+
+
+
+
+
+
+
+
+
+
+cocoon:complete-ant is the target that you *have* to override in your
+project-specific build.xml, if you want to make sure that you always
+use the latest version of your build script. If you don't want this,
+you can copy the generic Ant script into your project and refer to it
+using the import task.<br>
+
+
+
+
+
+
+
+
+
+
+
+
+<h2>Project properties (project.properties)</h2>
+
+
+
+
+
+
+
+
+
+
+
+
+
+<p>The project.properties contains project-wide valid properties like the used
version of Cocoon, e.g.:<br>
+</p>
+
+
+
+
+
+
+
+
+
+
+
+
+<pre>cocoon.version=149238</pre>
+
+
+
+
+
+
+
+
+
+
+
+
+<h2>Server-specific properties (*.build.properties)<br>
+
+</h2>
+
+
+
+
+
+
+
+
+
+
+
+
+
+<p>Some configurations are dependant on the environment where your web
+application is running, e.g. database connections or how you can reach
+your mail server. You can provide configuration files for each
+environment. At a minimum you have to set following properties (of course, the
values are examples):<br>
+</p>
+
+
+
+
+
+
+
+
+
+
+
+
+<pre>cocoon.rep=F:/rep<br>cocoon.container.version=tomcat-5.0.30</pre>
+
+
+
+
+
+
+
+
+
+
+
+
+<p> The default properties file for environment specific properties is
+localhost.build.properties. If you want to use another properties file,
+you have to set the pass the name of this environment when you
+invoke ant. E.g. you have a productionServer.build.properties you have
+to call<br>
+</p>
+
+
+
+
+
+
+
+
+
+
+
+
+<pre>ant -Dcocoon.server=productionServer webapp</pre>
+
+
+
+
+
+
+
+
+
+
+
+
+
+<p>if you want to build the web application.<br>
+
+</p>
+
+
+
+
+<h1>List of all available properties</h1>
+
+
+
+
+<pre><!-- local directories --><br><property
name="cocoon.local.webapp.dir" value="webapp"/><br><property
name="cocoon.local.src.dir" value="java"/><br><property
name="cocoon.local.lib.dir" value="lib"/><br><property
name="cocoon.local.conf.dir" value="conf"/><br><br><!-- target directory
structure --><br><property name="cocoon.build.dir"
value="build"/><br><property name="cocoon.build.webapp.war.dir"
value="${cocoon.build.dir}/${cocoon.server}_webapp"/><br><property
name="cocoon.build.webapp.dir"
value="${cocoon.build.dir}/${cocoon.server}_webapp/ROOT"/><br><property
name="cocoon.build.container.dir"
value="${cocoon.build.dir}/${cocoon.server}_container"/><br><br><!--
default values for compiler settings --><br><property
name="cocoon.compiler" value="modern"/><br><property
name="cocoon.compiler.debug" value="on"/><br><property
name="cocoon.compiler.optimize" value="on"/><br><property
name="cocoon.compiler.deprecation" value="off"/><br><property
name="cocoon.compiler.nowarn" value="on"/><br><property
name="cocoon.compiler.source.vm" value="1.3"/><br><property
name="cocoon.compiler.target.vm" value="1.3"/><br><br><!-- container
properties --><br><property
file="${cocoon.rep.container.dir}/server.properties"/></pre>
+
+
+
+
+<h1>ToDo</h1>
+
+
+
+<ul>
+
+
+
+ <li>implement the seed target</li>
+ <li>how to integrate your own container - what's to do?</li>
+ <li>win/nix switch</li>
+</ul>
+
+
+
+</body></html>
\ No newline at end of file
Added:
cocoon/whiteboard/doc-repos/2.2/src/documentation/content/xdocs/custom-cocoon-based-project-using-ant/files/example-repository.zip
URL:
http://svn.apache.org/viewcvs/cocoon/whiteboard/doc-repos/2.2/src/documentation/content/xdocs/custom-cocoon-based-project-using-ant/files/example-repository.zip?view=auto&rev=154686
==============================================================================
Binary file - no diff available.
Propchange:
cocoon/whiteboard/doc-repos/2.2/src/documentation/content/xdocs/custom-cocoon-based-project-using-ant/files/example-repository.zip
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added:
cocoon/whiteboard/doc-repos/2.2/src/documentation/content/xdocs/getting-started/comments_en.xml
URL:
http://svn.apache.org/viewcvs/cocoon/whiteboard/doc-repos/2.2/src/documentation/content/xdocs/getting-started/comments_en.xml?view=auto&rev=154686
==============================================================================
---
cocoon/whiteboard/doc-repos/2.2/src/documentation/content/xdocs/getting-started/comments_en.xml
(added)
+++
cocoon/whiteboard/doc-repos/2.2/src/documentation/content/xdocs/getting-started/comments_en.xml
Mon Feb 21 08:21:30 2005
@@ -0,0 +1,9 @@
+<?xml version="1.0"?>
+<comments>
+ <comment name="Reinhard Poetz" by="http://www.poetz.cc"; subject="the first
comment">
+ <p>Here follows the comment text.<strong>more</strong></p>
+ </comment>
+ <comment name="Reinhard Poetz" by="http://www.poetz.cc"; subject="second
comment">
+ <p>Here follows the comment text.<strong>more</strong></p>
+ </comment>
+</comments>
