You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@cocoon.apache.org by da...@cocoon.zones.apache.org on 2006/01/11 22:11:01 UTC
[DAISY] Created: BD: Tutorial: Using the block deployer to create a
Cocoon web application
A new document has been created.
http://cocoon.zones.apache.org/daisy/documentation/797.html
Document ID: 797
Branch: main
Language: default
Name: BD: Tutorial: Using the block deployer to create a Cocoon web application
Document Type: Cocoon Document
Created: 1/11/06 9:10:42 PM
Creator (owner): Reinhard Pötz
State: publish
Parts
=====
Content
-------
Mime type: text/xml
Size: 9217 bytes
Content:
<html>
<body>
<p>This tutorial requires that you have sucessfully finished the [link_name]
tutorial.</p>
<h1>Maven integration</h1>
<p>The block deployer can be used from within a Maven 2 plugin. In order to
integrate it into the Maven 2 build lifecycle, you have to put the plugin
configuration into your project's pom.xml:</p>
<pre><project>
...
<plugins>
<groupId>org.apache.cocoon</groupId>
<artifactId>deployer-maven-plugin</artifactId>
</plugins>
...
</project>
</pre>
<p>You can configure the plugin with following parameters:</p>
<table width="1089">
<tbody>
<tr>
<th>
<p>property</p>
</th>
<th>
<p>default value</p>
</th>
<th>
<p>description</p>
</th>
</tr>
<tr>
<td>
<p>deployScript</p>
</td>
<td>
<p>./block-deploy.xml</p>
</td>
<td>
<p>Point to the file containing the block deployment descriptor. This is only
needed for the explicit deployment mode. The implicit mode doesn't recognize it.
</p>
</td>
</tr>
</tbody>
</table>
<h1>Create a web application project using Maven 2</h1>
<pre>mvn archetype:create \
-DarchetypeGroupId=org.apache.cocoon \
-DarchetypeArtifactId=webapp \
-DarchetypeVersion=1.0 \
-DgroupId=com.mycompany \
-DartifactId=myWebApp
</pre>
<p>If you look into pom.xml you will find the Cocoon block deployer as plugin:
</p>
<pre><project>
...
<plugins>
<groupId>org.apache.cocoon</groupId>
<artifactId>deployer-maven-plugin</artifactId>
<configuration>
...
</configuration>
</plugins>
...
</project></pre>
<p>It accepts following configuration parameters:</p>
<table width="1089">
<tbody>
<tr>
<th>
<p>property</p>
</th>
<th>
<p>default value</p>
</th>
<th>
<p>description</p>
</th>
</tr>
<tr>
<td>
<p>deployScript</p>
</td>
<td>
<p>./block-deploy.xml</p>
</td>
<td>
<p>Point to the file containing the block deployment descriptor. This is only
needed for the explicit deployment mode. The implicit mode doesn't recognize it.
</p>
</td>
</tr>
</tbody>
</table>
<h1>Deploy your first block (explicitly)</h1>
<p>You can describe in detail which blocks should become part of the web
application. Make sure that you have sucessfully finished the [link_name]
tutorial and don't forget the last step of installing your block.</p>
<p>Open <em>block-deploy.xml</em> with your favorite XML editor. There is also
an XML schema file that describes the structure. The Maven archetype already
provides following descriptor:</p>
<pre><deploy xmlns="">
...
</deploy></pre>
<p class="fixme">Explain the content</p>
<h2>Install a simple block (minimal configuration)</h2>
<p>Now we start to add the block from the former tutorial:</p>
<pre><deploy xmlns="">
...
<block>
</block>
</deploy></pre>
<p>id, urn</p>
<h2>Mounting a block to the webapp's URI space</h2>
<p>If you block contains a sitemap, you can mount it in your web applications
URI space.</p>
<h2>Create the web application</h2>
<pre>mvn cocoon:deploy</pre>
<p>This target deploys all blocks into ./target/[project-name]/WEB-INF/blocks
and updates ./target/[project-name]/WEB-INF/wiring.xml. You can override the
target directory the deployer's target directory in deploy.xml</p>
<pre><deploy xmlns="">
<cocoon version="2.2" <strong>url="/opt/my-webapp"</strong>/>
...
</deploy></pre>
<h2>Start your servlet engine</h2>
<p>The easiest way to start your web application is using the Jetty 6 Maven
plugin. The website of the plugin
<a href="http://jetty.mortbay.org/jetty6/maven-plugin/index.html">describes
</a>how to install it. In order to use it, simply call</p>
<pre>mvn jetty6:run
</pre>
<p>Point your browser to</p>
<pre>http://localhost:8080/[your-project-name]/</pre>
<h1>Deploy a second block: connections and properties</h1>
<p>The first block that we have installed, was very simple. Now we want to
install a more advanced block that can be configured and requires other blocks
to run.</p>
<p class="fixme">explain the more advanced block here, maybe show block.xml</p>
<h2>Configure your block</h2>
<p>A block may have properties that can be used to configure it for your
environment. See the block descriptor (block.xml) to learn, which properties can
be set for a particular block. If you have following block.xml</p>
<pre><block xmlns="">
</block></pre>
<p>you can set the properties foo1 and foo2.</p>
<pre><deploy xmlns="">
</deploy></pre>
<h2>Explicit connections</h2>
<p>You specify, which block implementations you want to use to satisfy a blocks
requirements:</p>
<pre><deploy xmlns="">
...
<block id="blockA" urn="mycompany:blockA:1.0.0">
<strong> <connections>
<connection name="database" block="blockC"/>
</connections></strong>
</block>
<block id="<strong>blockC</strong>" urn="mycompany:blockC:1.0.0"/>
...
</deploy>
</pre>
<p>This is an explicit connection as your connection with the name "database"
points to the block with the id "blockC". Of course, "blockC" must be available
within your deployment script.</p>
<h2>Run it</h2>
<p>Repeat the steps "Create the web application" and "Start your servlet engine"
from above.</p>
<h1>Deploy a third block: auto-wiring and using other blocks connections to
satisfy block requirements</h1>
<h3>Auto-wiring of blocks</h3>
<p>If you don't describe explicitly which connections should be used for a block
requirement (see block.xml to learn about a block's requirements), the deployer
uses the default values of the requirement:</p>
<pre><block xmlns="">
...
<requirements>
<requires interface="" name="" <strong>default=""</strong>/>
</requirements>
...
</block>
</pre>
<p>This saves you the work of explicitly setting all connections.</p>
<h3>Using another blocks connection as block connection</h3>
<p>In the case that you want to use exactly the same connection for blockA that
blockB uses, you can point from your blockA descriptor to your blockB
descriptor:</p>
<pre><deploy xmlns="">
<block id="blockA" urn="mycompany:blockA:1.0.0">
<connections>
<connection name="database" block="blockC"/>
</connections>
</block>
<block id="blockB" urn="mycompany:blockB:1.0.0">
<connections>
<connection name="database" <strong>block="blockA.database"</strong>/>
</connections>
</block>
<block id="blockC" urn="mycompany:blockC:1.0.0"/>
</deploy>
</pre>
<p>The reference blockA.database at blockB points to <em>blockA </em>and it's
connection with the name <em>database</em>. This also works for auto-wired
blocks.</p>
<h2>Run it</h2>
<p>Repeat the steps "Create the web application" and "Start your servlet engine"
from above.</p>
<h1>Implicit deployment (of Cocoon block projects)</h1>
<p class="note">Implicit deployment has already been used in the [name_link]
tutorial. It is repeated here for the sake of completness.</p>
<p>If you develop a single block and you want to deploy it just for testing, you
can use the implicit block deployer. This deployer will mount your block to the
root of your web application "/" and will auto-wire all connections using the
default blocks defined in block.xml.</p>
<p>The only thing you have to do is calling</p>
<pre>mvn cocoon:simple-deploy jetty6:run</pre>
<p>Make sure, that you have installed the Jetty 6 plugin properly. See the
<a href="http://jetty.mortbay.org/jetty6/maven-plugin/index.html">website
</a>of the plugins to find details.</p>
<p>Point your browser to</p>
<pre>http://localhost:8080/[your-project-name]/</pre>
<p>That's it.</p>
<p>The implicit deployment doesn't create a block archive but points to the
sources in ./src/main/webapp and configures the Reloading classloader in Cocoon
to target/classes. This way, you can change all your files and see the changes
in your browser immediatly without having to restart your servlet engine.</p>
<h1>Rapid application development</h1>
<p>You think that the block deployer is nice to create a web application but you
want faster turn-around cycles during development. If the implicit deployment of
a block is good enough for you than use it. A reason not to use it is, if you
want to use more than one block in the rapid application development mode.</p>
<p>You can set the attribute "location" at your block elements. If this
attribute is set, the deployer doesn't deploy the block by unpacking it but
points to a local directory.</p>
<pre><block id="myblock" location="/home/rpoetz/myblock" urn="mycompany:myblock:1.0.0">
<mount path="/myblock"/>
</block>
</pre>
<p>This mounts the web application in /home/rpoetz/myblock/src/main/webapp to
"/myblock" and adds all compiled classes in /home/rpoetz/myblock/target/classes
to the reloading classloader. Additionally all jar files that
mycompany:myblock:1.0.0 depends on, will be handled correctly by adding them to
/WEB-INF/lib of your web application which is the same behaviour as with
normally unpacked blocks.</p>
</body>
</html>
Collections
===========
The document belongs to the following collections: documentation