You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@maven.apache.org by br...@apache.org on 2005/03/15 07:57:04 UTC
svn commit: r157527 - in maven/maven-1/core/trunk/xdocs/using:
multiproject.xml war.xml
Author: brett
Date: Mon Mar 14 22:57:02 2005
New Revision: 157527
URL: http://svn.apache.org/viewcvs?view=rev&rev=157527
Log:
multiproject and WAR documentation
Modified:
maven/maven-1/core/trunk/xdocs/using/multiproject.xml
maven/maven-1/core/trunk/xdocs/using/war.xml
Modified: maven/maven-1/core/trunk/xdocs/using/multiproject.xml
URL: http://svn.apache.org/viewcvs/maven/maven-1/core/trunk/xdocs/using/multiproject.xml?view=diff&r1=157526&r2=157527
==============================================================================
--- maven/maven-1/core/trunk/xdocs/using/multiproject.xml (original)
+++ maven/maven-1/core/trunk/xdocs/using/multiproject.xml Mon Mar 14 22:57:02 2005
@@ -21,97 +21,132 @@
<document>
<properties>
<title>Multiple Modules</title>
- <author email="bwalding@apache.org">Ben Walding</author>
<author email="brett@apache.org">Brett Porter</author>
</properties>
<body>
-<!-- TODO:
- <subsection name="Multi Project Builds and the Reactor">
+ <section name="Multiple Modules">
+ <p>
+ Maven supports the notion of a product with multiple modules. While each <code>project.xml</code> is a discreet
+ unit of work, they can be gathered together using the reactor to build simultaneously. The reactor was
+ originally created to encourage the creation, or refactoring, of projects into smaller,
+ discrete, more coherent units.
+ </p>
+ <p>
+ The reactor determines the correct build order from the dependencies stated
+ by each project in their respective project descriptors, and will then execute a stated set of goals. It can
+ be used for both building projects and other goals, such as site generation.
+ </p>
+ <p>
+ While the reactor requires you to write some Jelly script to interface with it, there is also a friendly
+ wrapper plugin called <code>multiproject</code> that can allow you to control the setup with simple properties.
+ </p>
+ <subsection name="Using the Multiproject Plugin">
+ <p>
+ Using the plugin is quite simple. The default set up assumes that you are in the top level directory of your
+ build, and that and subdirectories that contain a <code>project.xml</code> file are subprojects to build.
+ </p>
+ <p>
+ To change this behaviour, set the <code>maven.multiproject.includes</code> and
+ <code>maven.multiproject.excludes</code> properties appropriately, for example:
+ </p>
+ <source>
+# Foo is broken, don't build it
+maven.multiproject.excludes=foo/project.xml</source>
+ <p>
+ All of the artifact based goals have a multiproject equivalent:
+ </p>
+ <table>
+ <tr>
+ <td><code>multiproject:install</code></td>
+ <td>Build and install all projects into the local repository</td>
+ </tr>
+ <tr>
+ <td><code>multiproject:install-snapshot</code></td>
+ <td>Build and install a timestamped build of all projects into the local repository</td>
+ </tr>
+ <tr>
+ <td><code>multiproject:deploy</code></td>
+ <td>Build and install all projects, deploying to the remote repository</td>
+ </tr>
+ <tr>
+ <td><code>multiproject:deploy-snapshot</code></td>
+ <td>Build and install a timestamped build of all projects, deploying to the remote repository</td>
+ </tr>
+ </table>
+ <p>
+ For the plugin to determine how to build each project, you must define a property for each project that
+ requires it:
+ </p>
+ <source>maven.multiproject.type=war</source>
+ <p>
+ The default type is <code>jar</code>.
+ </p>
+ <p>
+ Note that the original purpose of the Multiproject plugin was to assist in aggregating the web site of
+ subprojects, and so this comprises a large amount of the plugin's functionality. Simply by running:
+ </p>
+ <source>maven multiproject:site</source>
+ <p>
+ This goal will build the sites of all subprojects, including the top level that it was run from and will
+ build an appropriate navigation to access each of the subprojects, and an overview listing the subprojects.
+ </p>
<p>
- With Maven the Reactor is the tool that is used to control multi
- project builds. The Reactor uses the Werkz package to
- determine the correct build order from the dependencies stated
- by each project in their respective POMs. The Reactor was created to
- encourage the creation, or refactoring, of projects into smaller,
- discrete, more coherent units. The Reactor is ideal for Component
- Oriented Programming (COP) where the overall system is comprised
- of many discrete entities that need to be aggregated to form a whole
- for deployment.
+ The behaviour of this goal and all others can be easily customised. For more information, see the
+ <a href="../reference/plugins/multiproject/">Multiproject plugin reference</a>.
</p>
-
<p>
- The Reactor can execute an arbitrary list of goals for any set of
- specified projects. So while the Reactor was created for building, it can be
- used for things like site generation, or any sort of artifact generation.
+ Finally, you may wish to run some other goal(s) over the set of projects. To do this, run the following goal:
</p>
-
+ <source>maven multiproject:goal -Dgoal=goal1,goal2</source>
+ </subsection>
+ <subsection name="Using the Reactor">
<p>
- Currently the <a href="http://db.apache.org/">db.apache.org</a> site is
- generated by collecting project information from all its subprojects
- and injecting the harvested information into a set of
- <a href="http://jakarta.apache.org/velocity/">Velocity</a> templates
- which are processed by the <a href="http://jakarta.apache.org/commons/jelly/">Jelly</a>
- Velocity Tag Library. You can browse the mechanism used
- <a href="http://cvs.apache.org/viewcvs.cgi/db-site/">here</a>.
+ While the Multiproject plugin covers most common use cases in a convenient manner, in some instances it is
+ necessary to access the reactor directly to execute multiple projects.
</p>
-
<p>
- In Plexus, an Avalon-based container, the component manifest which tracks all
- Plexus components is generated by walking over all of the components, harvesting
- the information and aggregating it into a single manifest. Again we use Velocity
- templates and the Jelly Velocity Tag Library. You can browse the mechanism used
- <a href="http://cvs.werken.com/viewcvs.cgi/plexus-components/?cvsroot=plexus">here</a>.
+ The normal use of the reactor tag is as follows:
</p>
-
+ <source><![CDATA[<maven:reactor
+ includes="**/project.xml"
+ excludes=""
+ banner="Building"
+ goals="goal1, goal2"
+ ignoreFailures="false"
+/>]]></source>
<p>
- Here is an example of how you might use the Reactor Tag to process a
- set of components where the site is generated
-
+ This will loop through every <code>project.xml</code> file found in the current tree, in the order defined
+ by the dependencies they have on each other. The goals listed will be executed on each project in sequence.
</p>
- <source><![CDATA[
- <goal
- name="project-site"
- description="Generate the site for the entire project">
-
- <!- - Generate the site for each of the components. - ->
-
- <maven:reactor
- basedir="${basedir}/components"
- postProcessing="true"
- includes="*/project.xml"
- excludes="bad-component/*"
- goals="site"
- banner="Generating Site"
- ignoreFailures="true"/>
-
- <!- -
- |
- | At this point because 'postProcessing' was turned on we have all
- | the processed POMs available to us in the ${reactorProjects} variable.
- |
- - ->
-
- <j:forEach var="reactorProject" items="${reactorProjects}">
-
- ... Do whatever you want with the harvested information ...
-
- </j:forEach>
- </goal>
- ]]></source>
-
<p>
- If you have to generate documentation for N projects with an overall
- front-end do look at the <a href="http://db.apache.org/">db.apache.org</a>
- site as the navigation, mailing lists, committer lists and source repository
- lists are all harvested from sub-projects to produce the overall site. This
- means that the redundant, error prone process of moving sub-project specific
- information to the overall site is removed. Sub-projects at db.apache.org
- take care of their own information and it finds its way to the top-level
- site automatically.
+ The reactor tag is described in the <a href="../reference/maven-jelly-tags/">Maven Jelly Tag Library</a>
+ reference.
+ </p>
+ </subsection>
+ <subsection name="Processing Projects after the Reactor">
+ <p>
+ In some instances, you will want to work with the projects that the reactor did in your own script afterwards.
+ To do this, you can utilise the <code>${reactorProjects}</code> variable set in the Jelly context after each
+ reactor execution. This is a list, and so can be iterated. Each variable in the list will be a project object,
+ and can be used in the same way as <code>${pom}</code> would normally be used.
+ </p>
+ <p>
+ If you'd like to gather a list of subprojects without executing any goals on them, this can be done by using
+ the <code>collectOnly</code> attribute of the <code>maven:reactor</code> tag.
+ </p>
+ <p>
+ In some cases, you may wish to process a whole set of projects, and handle the failed projects differently.
+ This requires that you set the <code>ignoreFailures</code> attribute to <code>true</code> in the
+ <code>maven:reactor</code> tag. After all the projects have finished processing, the context variable
+ <code>${failedProjects}</code> will be available to iterate through and projects that failed to build
+ completely.
+ </p>
+ <p>
+ If <code>ignoreFailures</code> is not set, it defaults to <code>false</code> and the entire build will end
+ when one project fails to build.
</p>
-
</subsection>
--->
+ </section>
</body>
</document>
Modified: maven/maven-1/core/trunk/xdocs/using/war.xml
URL: http://svn.apache.org/viewcvs/maven/maven-1/core/trunk/xdocs/using/war.xml?view=diff&r1=157526&r2=157527
==============================================================================
--- maven/maven-1/core/trunk/xdocs/using/war.xml (original)
+++ maven/maven-1/core/trunk/xdocs/using/war.xml Mon Mar 14 22:57:02 2005
@@ -1,7 +1,7 @@
<?xml version="1.0"?>
<!--
/*
- * Copyright 2001-2004 The Apache Software Foundation.
+ * Copyright 2001-2005 The Apache Software Foundation.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -26,211 +26,163 @@
<body>
<section name="Web Applications">
- <!-- TODO -->
- <p>...</p>
-<!-- from wiki
-
-<ul><p> The purpose of this guide is to get you started in the creation of a simple web application using Maven. It focuses on the creation of a WAR using the appropriate parts of Maven. </ul><p><a name="head-6f58d263f33944384921df8405fd4a36e06175e2"></a><H1>24. Concepts</H1>
-<ul><p><a name="head-078078bdbf491a87c62d8fa023319ae673f86a1a"></a><H2>24.1. One artifact per project</H2>
-<ul><p> Maven is "limited" (by design) to creating one artifact per project. However using a plugin, additional artifacts can be created, however this technique should not be used to bypass the one artifact per project rule. <p> However, that being said, Maven can create a jar artifact as well as an associated war artifact using the same code-base. <p> If you have the desire to generate multiple artifacts as you have common code across the set, this is typically resolved by extracting that common code out into a separate artifact and using it via Maven's dependency mechanism. <p> Also, see <a href="./WhyYouCantCreateMultipleArtifactsInOneProject.html">WhyYouCantCreateMultipleArtifactsInOneProject</a>. </ul></ul><p><a name="head-db412b35391491a23074f474e3dd7ab6ca4b7fa3"></a><H1>25. Sample Code</H1>
-<ul><p> This article does not contain all the source required to build a web application. The complete source is contained in <a href="./CreatingWebApplications.html?action=AttachFile&do=get&target=maven-war-example-1.0-dev-src.zip">maven-war-example-1.0-dev-src.zip</a> . <p> Also, Maven provides different examples (<a href="http://cvs.apache.org/viewcvs.cgi/maven-plugins/examples/">http://cvs.apache.org/viewcvs.cgi/maven-plugins/examples/</a>) and the webapp example is available at <a href="http://cvs.apache.org/viewcvs.cgi/maven-plugins/examples/simple-webapp/">http://cvs.apache.org/viewcvs.cgi/maven-plugins/examples/simple-webapp/</a>. <p> (Currently I'm unsure where this can be put in CVS - perhaps /examples/war? - - <a href="./BenWalding.html">BenWalding</a>) <em>Ben, it's already there, no? - -<a href="./VincentMassol.html">VincentMassol</a></em> <em>It's a different sample, I think this one is more complete (i.e. it actually creates a servlet etc), so I'll probably overwrite the one there with this. - - <a href="./BenWalding.html">BenWalding</a> </em> </ul><p><a name="head-e863c718db915f2f4b58c523e97d4f07d5237232"></a><H1>26. Starting out</H1>
-<ul><p><a name="head-541adf4b5a0fdc6e90a32dedb85886ce2fd8dfdb"></a><H2>26.1. Project descriptor</H2>
-<ul><p> The project descriptor is basically just boilerplate for this project. The points to note are <li class="gap">log4j-1.2.8.jar is included in resultant WAR (war.bundle = true) </li><li>servletapi-2.3.jar is not included in the WAR (the container provides this) </li><li>If you are using Beta 9 (or earlier) of Maven, you will need to change <tt class="wiki">war.bundle</tt> to <tt class="wiki">war.bundle.jar</tt> <pre class="code">
-<?xml version="1.0"?>
-<project>
- <pomVersion>3</pomVersion>
-
- <id>maven-war-example</id>
- <name>Maven WAR Example</name>
- <currentVersion>1.0-dev</currentVersion>
- <package>org.apache.maven.examples.war</package>
-
- <dependencies>
- <dependency>
- <id>log4j</id>
- <version>1.2.8</version>
- <properties><war.bundle>true</war.bundle></properties>
- </dependency>
-
- <dependency>
- <id>servletapi</id>
- <version>2.3</version>
- <!- - Compile time only - ->
- </dependency>
-
- </dependencies>
-
- <build>
- <sourceDirectory>${basedir}/src/main/java</sourceDirectory>
- <unitTestSourceDirectory>${basedir}/src/test/java</unitTestSourceDirectory>
-
- <!- - Unit test cases - ->
- <unitTest>
- <resources><resource>
- <directory>${basedir}/src/test/java</directory>
- <includes><include>**/*</include></includes>
- <excludes><exclude>**/*.java</exclude></excludes>
- </resource></resources>
- <includes>
- <include>**/*Test.java</include>
- </includes>
- </unitTest>
-
- </build>
-</project>
-</pre><p><a name="head-b0c0a3787c5b36b4fe5b178d91a655c6a5cbdf6b"></a><H2>26.2. Other files</H2>
-</li><ul><p><a name="head-883ff21824d1a24fbb42f58b1e145b46d304d8b2"></a><H3>26.2.1. web.xml</H3>
-<ul><p> Anything that is placed into src/webapp will be transferred to the resulting WAR file. src/webapp/WEB-INF/web.xml is thus transferred into the appropriate location in the WAR file. <p> The contents of web.xml (see the attached source archive) are just a simple web application descriptor with a single servlet. </ul><p><a name="head-f21ee6185ca48360297d7b5dfef16e47340fa3c1"></a><H3>26.2.2. src/test/*</H3>
-<ul><p> The <a class="nonexistent" href="./HelloWorldBean.html">HelloWorldBean</a> that is used to write the text to a stream requires testing, and the test is contained in src/test/org/apache/maven/examples/war/<a class="nonexistent" href="./HelloBeanTest.html">HelloBeanTest</a>.java </ul><p><a name="head-fbb8929ba684d9ac110123319b5ad12984f8103b"></a><H3>26.2.3. maven.xml</H3>
-<ul><p> maven.xml contains custom scripting for your project. In this case, we simply specify that <tt class="wiki">war</tt> is the <a class="nonexistent" href="./DefaultGoal.html">DefaultGoal</a> </ul><p><a name="head-0cc4925ffd876dc10110f64fc429bb483fc38f18"></a><H3>26.2.4. src/webapp/index.html</H3>
-<ul><p> This is the standard welcome page for the web application. </ul></ul></ul></ul><p><a name="head-15b4e7750c087c5605d05d237ee25ce7445c1b3e"></a><H1>27. Building the application</H1>
-<ul><p> Now comes the hard part. To build the web application, run maven as such <p> <pre class="code">
-maven
-</pre><p> This should yield output like <pre class="code">
- __ __
-| \/ |__ _Apache__ ___
-| |\/| / _` \ V / -_) ' \ ~ intelligent projects ~
-|_| |_\__,_|\_/\___|_||_| v. 1.0-beta-10-SNAPSHOT
-
-war:init:
-java:prepare-filesystem:
- [mkdir] Created dir: D:\Data\workspace\maven-war-example\target\classes
-
-java:compile:
- [echo] Compiling to D:\Data\workspace\maven-war-example/target/classes
- [javac] Compiling 2 source files to D:\Data\workspace\maven-war-example\target\classes
-
-java:prepare-filesystem:
-
-java:compile:
- [echo] Compiling to D:\Data\workspace\maven-war-example/target/classes
-
-java:jar-resources:
-
-test:prepare-filesystem:
- [mkdir] Created dir: D:\Data\workspace\maven-war-example\target\test-classes
- [mkdir] Created dir: D:\Data\workspace\maven-war-example\target\test-reports
-
-test:test-resources:
- [copy] Copied 2 empty directories to D:\Data\workspace\maven-war-example\target\test-classes
-
-test:compile:
- [javac] Compiling 1 source file to D:\Data\workspace\maven-war-example\target\test-classes
-
-test:test:
- [echo] Testing classes found at D:\Data\workspace\maven-war-example/target/classes
- [junit] dir attribute ignored if running in the same VM
- [junit] Running org.apache.maven.examples.war.HelloWorldBeanTest
- [junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.03 sec
-
-
-war:webapp:
- [echo] Assembling webapp maven-war-example
- [mkdir] Created dir: D:\Data\workspace\maven-war-example\target\maven-war-example
- [mkdir] Created dir: D:\Data\workspace\maven-war-example\target\maven-war-example\WEB-INF
- [mkdir] Created dir: D:\Data\workspace\maven-war-example\target\maven-war-example\WEB-INF\lib
- [mkdir] Created dir: D:\Data\workspace\maven-war-example\target\maven-war-example\WEB-INF\tld
- [mkdir] Created dir: D:\Data\workspace\maven-war-example\target\maven-war-example\WEB-INF\classes
- [copy] Copying 2 files to D:\Data\workspace\maven-war-example\target\maven-war-example
- [copy] Copying 1 file to D:\Data\workspace\maven-war-example\target\maven-war-example\WEB-INF\lib
- [copy] Copying 2 files to D:\Data\workspace\maven-war-example\target\maven-war-example\WEB-INF\classes
-
-war:war:
- [echo] Building WAR maven-war-example
- [jar] Building jar: D:\Data\workspace\maven-war-example\target\maven-war-example.war
-BUILD SUCCESSFUL
-Total time: 8 seconds
-</pre><p> The result is a <tt class="wiki">maven-war-example.war</tt> in the <tt class="wiki">target</tt> directory. </ul><p><a name="head-8c2c6bf45c0ef89c348490fcf7cfa0f69e5ec3f0"></a><H1>28. Development Cycle</H1>
-<ul><p> During the development cycle you typically want / need fast turn around of changes into the running container. <p> This can be achieved by using the maven console (<tt class="wiki">maven console</tt>) and using the <tt class="wiki">war:webapp</tt> goal that creates a constructed / exploded web application in <tt class="wiki">${maven.build.dir}/${pom.artifactid} </tt> i.e. <tt class="wiki">target/maven-war-example</tt>. <ul><p> <pre class="code">
- maven-war-example 1.0 > [war:webapp] war:webapp
-
- war:init:
- java:prepare-filesystem:
-
- java:compile:
- [echo] Compiling to D:\Data\Workspace\maven-war-example/target/classes
-
- java:prepare-filesystem:
-
- java:compile:
- [echo] Compiling to D:\Data\Workspace\maven-war-example/target/classes
-
- java:jar-resources:
-
- test:prepare-filesystem:
-
- test:test-resources:
-
- test:compile:
-
- test:test:
-
-
- war:webapp:
- [echo] Assembling webapp maven-war-example
- [copy] Copying 8 files to D:\Data\Workspace\maven-war-example\target\maven-war-example\WEB-INF\classes
- maven-war-example 1.0 > [war:webapp]
-</pre></ul><p> The servlet container should be configured to auto-reload this web-application resulting in a fast turn-around time for development. <p> If you're using JBoss, see <a href="./WebAppDevCycleWithJbossPlugin.html">WebAppDevCycleWithJbossPlugin</a> for further details. </ul><p><a name="head-2b0c6db33bd58f8f93de3b6ff49263e574447731"></a><H1>29. Precompiling JSPs in Tomcat</H1>
-<p>If you'd like to precompile your JSPs in Tomcat 4.1, use the following code in a maven.xml file. In the near future, a more generic way will be added to the appserver plugin. <p>Set the precompile.jsp property to true and calls to war:webapp will also run Jasper. If you want to add the generated fragment to web.xml so that the generated files are turned into servlets (as recommended), include <tt class="wiki"><!- - [INSERT FRAGMENT HERE] - -></tt> in your web.xml file between the servlets and the servlet mappings. <p><pre class="code">
- <preGoal name="war:webapp">
- <j:set var="precompileJsp" value="${precompile.jsp}"/>
- <j:if test="${precompileJsp == 'true'}">
- <attainGoal name="precompile-jsp"/>
- </j:if>
- </preGoal>
-
- <postGoal name="war:webapp">
- <j:set var="precompileJsp" value="${precompile.jsp}"/>
- <j:if test="${precompileJsp == 'true'}">
- <j:set var="target" value="${pom.getPluginContext('maven-war-plugin').getVariable('maven.war.webapp.dir')}"/>
- <util:available file="${maven.build.dir}/web-fragment.xml">
- <util:loadText var="fragment" file="${maven.build.dir}/web-fragment.xml"/>
- <ant:replace file="${target}/WEB-INF/web.xml" token="&lt;!- - [INSERT FRAGMENT HERE] - -&gt;" value="${fragment}"/>
- </util:available>
- </j:if>
- </postGoal>
-
- <goal name="precompile-jsp" description="Precompile all JSPs into java classes, and then into classes" prereqs="war:load,java:compile">
- <j:set var="warSource" value="${pom.getPluginContext('maven-war-plugin').getVariable('maven.war.src')}"/>
- <ant:mkdir dir="${maven.build.dir}/jspc"/>
- <ant:mkdir dir="${maven.build.dir}/jspc-processed"/>
- <ant:mkdir dir="${maven.build.dir}/jspc-classes"/>
-
- <j:set var="jspOutDir" value="${maven.build.dir}/jspc"/>
- <j:set var="jspClassesOutDir" value="${maven.build.dest}"/>
- <ant:path id="jspc.classpath">
- <ant:pathelement location="${tomcat.home}/common/lib/jasper-runtime.jar"/>
- <ant:pathelement location="${tomcat.home}/common/lib/jasper-compiler.jar"/>
- <ant:pathelement location="${tomcat.home}/common/lib/servlet.jar"/>
- <ant:path refid="maven.dependency.classpath"/>
- <ant:pathelement path="${maven.build.dest}"/>
- </ant:path>
- <ant:taskdef name="jasper2" classname="org.apache.jasper.JspC" classpathref="jspc.classpath"/>
- <ant:jasper2
- webXmlFragment="${maven.build.dir}/web-fragment.xml"
- package="${pom.package}.jsp.${pom.artifactId}"
- outputDir="${jspOutDir}"
- srcdir="${warSource}"
- uriroot="${warSource}"
- uribase="/${pom.artifactId}"
- verbose="2"/>
- <ant:javac
- srcdir="${jspOutDir}"
- destdir="${jspClassesOutDir}"
- debug="${maven.compile.debug}"
- deprecation="${maven.compile.deprecation}"
- optimize="${maven.compile.optimize}"
- classpathref="jspc.classpath"/>
- </goal>
-</pre><p><a name="head-e737a090242c9d0342d3b7cea16bdfa684be6790"></a><H1>30. Deploying</H1>
-<ul><p> Deploying the WAR to the servlet container can be done manually or automatically. Simply write a new goal in maven.xml to deploy as you see fit. <p> For example, <p> <pre class="code">
-<goal name="war:install-local">
- <ant:copy file="target/maven-war-example.war" toDir="/var/tomcat4/webapps"/>
-</goal>
-</pre><p> If you're using JBoss, see <a href="./WebAppDevCycleWithJbossPlugin.html">WebAppDevCycleWithJbossPlugin</a> for further details. </ul><p><a name="head-8fb937b602b4f2ef21c7fab00ac15de3b3ba49ea"></a><H1>31. Discussion</H1>
-<ul><p> I wrote this based on how I use Maven for building web applications. Now it's your turn to improve and build upon this document. </ul><p>- - <a href="./BenWalding.html">BenWalding</a> <p><hr>
- <hr>
--->
+ <p>
+ Building a web application is not too much different to working with other types such as JARs in Maven. You
+ still create a project descriptor, add your source code and resources, and build an archive to finish.
+ </p>
+ <p>
+ However, a few extra steps must be taken to create the appropriate web application structure.
+ </p>
+ <subsection name="Adding Webapp Contents">
+ <p>
+ The first step is to add the web application contents. Unlike a JAR, resources are not included in the root of
+ the WAR - they will be located in <code>/WEB-INF/classes</code>, as the purpose of the resources is to make
+ them available in the classloader inside the application.
+ </p>
+ <p>
+ To include the contents of your web application (JSPs, images, etc., as well as some of the contents of
+ WEB-INF), create a directory called <code>src/main/webapp</code>. These will all reside in the base of the web
+ application when it is packaged up.
+ </p>
+ <p>
+ To configure the web application to use these resources, set the property:
+ </p>
+ <source>maven.war.src=${basedir}/src/main/webapp</source>
+ <p>
+ You can include whatever you like in this structure, including a <code>WEB-INF</code> directory and anything
+ underneath it. However, you should not have a <code>/WEB-INF/classes</code> or <code>/WEB-INF/lib</code>
+ directory as Maven will populate this from your project.
+ </p>
+ <p>
+ As mentioned, resources and classes will be compiled and copied into the <code>/WEB-INF/classes</code>
+ directory. The <code>lib</code> directory is populated from the project's dependency list, as shown in the
+ next section.
+ </p>
+ </subsection>
+ <subsection name="Adding Dependencies to the lib Directory">
+ <p>
+ Since Maven requires that you declare all of the dependencies of your project, it is quite easy to also set
+ up the <code>lib</code> directory in your web application.
+ </p>
+ <p>
+ Note however, libraries are not bundled into the web application by default - you must list those that you
+ want included. This is quite simple to do, by adding a property to those dependencies that are required in
+ the WAR:
+ </p>
+ <source><![CDATA[<dependency>
+ <groupId>mycompany</groupId>
+ <artifactId>mycompany-utils</artifactId>
+ <version>1.0.0</version>
+ <properties>
+ <war.bundle>true</war.bundle>
+ </properties>
+</dependency>]]></source>
+ </subsection>
+ <subsection name="Building and Deploying">
+ <p>
+ There are two particular goals that are used to build a web application: <code>war:webapp</code> and
+ <code>war:war</code>.
+ </p>
+ <p>
+ The first builds an unpacked directory structure in the <code>target</code> directory
+ that is the same as it would be exploded into an application server. This can be most effective for deploying
+ directly into an application server with reloading enabled in the development environment so that
+ reconstructing the WAR in this directory after making changes will be loaded.
+ </p>
+ <p>
+ The section will build a <code>.war</code> archive which is later deployed into the servlet container as is.
+ </p>
+ <p>
+ To automatically deploy into a servlet container will rely on scripting up the appropriate goals or locating
+ an existing plugin for the container. There is currently one available for JBoss - see the
+ <a href="../reference/plugins/jboss/">JBoss Plugin</a>. Tomcat also has several deployment Ant tasks which can
+ easily be used from Maven.
+ </p>
+ </subsection>
+ <subsection name="Further Information">
+ <p>
+ If you would like an example, please refer to
+ <a href="http://cvs.apache.org/viewcvs.cgi/maven-plugins/examples/simple-webapp/">The <code>simple-webapp</code>
+ example project.</a>
+ </p>
+ <p>
+ For more information on goals and configuration, see the <a href="../reference/plugins/war/">WAR plugin
+ reference</a>.
+ </p>
+ </subsection>
+ </section>
+ <section name="Precompiling JSPs for Tomcat">
+ <p>
+ How to precompile JSPs is a common question when developing Web Applications, as doing so can bring a
+ performance boost to the first time deployment of your application in a production environment.
+ </p>
+ <p>
+ The following code snippet can be used in <code>maven.xml</code> if you are using a Tomcat 4.1 based
+ servlet container. It should also serve as a starting point for implementing a similar task for other containers.
+ </p>
+ <source><![CDATA[
+<preGoal name="war:webapp">
+ <j:set var="precompileJsp" value="${precompile.jsp}"/>
+ <j:if test="${precompileJsp == 'true'}">
+ <attainGoal name="precompile-jsp"/>
+ </j:if>
+</preGoal>
+
+<postGoal name="war:webapp">
+ <j:set var="precompileJsp" value="${precompile.jsp}"/>
+ <j:if test="${precompileJsp == 'true'}">
+ <maven:set var="target" property="maven.war.webapp.dir" plugin="maven-war-plugin" />
+ <util:available file="${maven.build.dir}/web-fragment.xml">
+ <util:loadText var="fragment" file="${maven.build.dir}/web-fragment.xml"/>
+ <ant:replace file="${target}/WEB-INF/web.xml" token="<!-- [INSERT FRAGMENT HERE] -->" value="${fragment}"/>
+ </util:available>
+ </j:if>
+</postGoal>
+
+<goal name="precompile-jsp" description="Precompile all JSPs into java classes, and then into classes" prereqs="war:load,java:compile">
+ <maven:set var="warSource" property="maven.war.src" plugin="maven-war-plugin" />
+ <ant:mkdir dir="${maven.build.dir}/jspc"/>
+ <ant:mkdir dir="${maven.build.dir}/jspc-processed"/>
+ <ant:mkdir dir="${maven.build.dir}/jspc-classes"/>
+
+ <j:set var="jspOutDir" value="${maven.build.dir}/jspc"/>
+ <j:set var="jspClassesOutDir" value="${maven.build.dest}"/>
+ <ant:path id="jspc.classpath">
+ <ant:pathelement location="${tomcat.home}/common/lib/jasper-runtime.jar"/>
+ <ant:pathelement location="${tomcat.home}/common/lib/jasper-compiler.jar"/>
+ <ant:pathelement location="${tomcat.home}/common/lib/servlet.jar"/>
+ <ant:path refid="maven.dependency.classpath"/>
+ <ant:pathelement path="${maven.build.dest}"/>
+ </ant:path>
+ <ant:taskdef name="jasper2" classname="org.apache.jasper.JspC" classpathref="jspc.classpath"/>
+ <ant:jasper2
+ webXmlFragment="${maven.build.dir}/web-fragment.xml"
+ package="${pom.package}.jsp.${pom.artifactId}"
+ outputDir="${jspOutDir}"
+ srcdir="${warSource}"
+ uriroot="${warSource}"
+ uribase="/${pom.artifactId}"
+ verbose="2"/>
+ <ant:javac
+ srcdir="${jspOutDir}"
+ destdir="${jspClassesOutDir}"
+ debug="${maven.compile.debug}"
+ deprecation="${maven.compile.deprecation}"
+ optimize="${maven.compile.optimize}"
+ classpathref="jspc.classpath"/>
+</goal>
+]]></source>
+ <p>
+ To execute this code, set the <code>precompile.jsp</code> property to <code>true</code>. When building the web
+ application, the JSPs will be compiled and added to the generated WAR file.
+ </p>
+ <p>
+ These servlets will not be utilised by Tomcat by default. To do so, you must include them in the
+ <code>web.xml</code> file. The script above does this, as long as you include the following comment in your
+ <code>web.xml</code> file in between the last <code>servlet</code> and first <code>servlet-mapping</code>
+ declaration:
+ </p>
+ <source><![CDATA[<!-- [INSERT FRAGMENT HERE] -->]]></source>
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org