...

...

...

First, let's review some Maven basics. Maven uses the notion of a build life-cycle to which plugins can attach. Plugins are similar to Ant tasks. When a Maven build is invoked, we specify a point in the life-cycle up to which the build should proceed. The compile phase

...

Getting started

Before we get too far ahead, it is important to know some basics concepts of Maven. The most important thing to understand is that unlike Ant, Maven has no concept of procedural tasks that get run. Instead, Maven has a concept of a build lifecycle in which plugins (somewhat similar to Ant asks) can attach to. When you execute a maven build, you specify a point in the lifecycle that you want the project built up to. The phase compile comes before test, and test comes before package, and package comes before install.

Installing

Once we have Maven setup, we can invoke the Struts build, and specify which phase the build should use.

Installing

The install phase builds The install phase simply means that maven should build up the project ("package"), and then install it to installs any JARs it needs into your local repository (found in e.g. ~/.m2/repository). There is Once installed, the JARs can be used by any other maven Maven project you build.  The install phase is the default phase if none is specified.

To run a basic install, simply invoke:change to the root of the source distribution, and enter

> mvn install

That's it! Maven will download all any dependencies it the build needs, ; run all unit tests, ; package up the jars, and JARs; then install the jars new JARs locally. You can also find the jars For your convenience, copies of the JARs can be found in the target directories of each module. For example, actionafter the build, the main JAR can found at core/target/actionstruts2-core-2.0-SNAPSHOT.jar would be where the main jar is built.

If all goes well, you should see something like:

[INFO] Reactor Summary:
[INFO]
[INFO] Struts 2 .......................................... SUCCESS [6.016s]
[INFO] XWork: Core ....................................... SUCCESS [1:08.086s]

[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] ------------------------------------------------------------------------
[INFO] Struts Action2 FrameworkCore 2..0 Project ................... SUCCESS [0.688s]................ SUCCESS [2:42.604s]
[INFO] Struts Action Framework 2.0 API Plugins .................................... SUCCESS [20.125s944s]
[INFO] Struts Action2 Spring FrameworkPlugin 2.0 ........................... SUCCESS [2113.866s523s]
[INFO] WebappsStruts 2 Convention Plugin ........................ SUCCESS [16.473s]
[INFO] Struts 2 JUnit Plugin ............................. SUCCESS [013.002s325s]
[INFO] BlankWebapps Webapp ........................................... SUCCESS [01.982s027s]
[INFO] PortetBlank Webapp ......................................... SUCCESS [29.038s572s]
[INFO] ShoppingJBoss CartBlank Webapp .................................. SUCCESS [07.934s814s]
[INFO] ShowcaseMail Reader Webapp ....................................... SUCCESS [37.351s028s]
[INFO] Starter WebappStruts 2 Portlet Plugin ........................... SUCCESS [20.995s]
[INFO] Struts 2 DWR Plugin ............................... SUCCESS [14.013s432s]
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 33 seconds
[INFO] Finished at: Wed May 03 18:23:38 PDT 2006
[INFO] Final Memory: 11M/43M
[INFO] ------------------------------------------------------------------------

Other phases

There are other phases that can be useful when working with Maven. The package phase will just jar (or war) up the modules. The test phase will only run the unit tests. The compile phase will only build the source code (but not the test sources). And the clean phase will remove all artifacts, typically the entire target directory.

Build profiles

The next step to building Struts with Maven is to understand build profiles. These are simply slightly different configurations for the build. The following profiles are available:

In the previous example, we didn't specify a profile so the default profile was used. However, most developers will want to use additional profiles as they work on both XWork and other modules, such as the JasperReports integration.

Specify a profile is as simple as:

> mvn -Pprofile ...

Third party profile

That is, if you wanted to build all the third-party add-ons not included with the default build, you'd simply use the thirdparty profile:

> mvn -Pthirdparty package

Notice that the final output is now:

[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] ------------------------------------------------------------------------
[INFO] Struts Action Framework 2.0 Project Struts 2 Tiles Plugin ............................. SUCCESS [4.451s]
[INFO] Struts 2 Portlet Tiles Plugin ..................... SUCCESS [3.741s]
[INFO] Portlet Webapp .................................... SUCCESS [28.480s]
[INFO] Struts 2 Struts 1 Plugin .......................... SUCCESS [8.353s]
[INFO] Struts 2 Dojo Plugin .............................. SUCCESS [30.181s]
[INFO] Struts 2 JSF Plugin ............................... SUCCESS [6.000s]
[INFO] Struts 2 Configuration Browser Plugin ............. SUCCESS [7.531s]
[INFO] Struts 2 Sitemesh Plugin .......................... SUCCESS [6.159s]
[INFO] Struts 2 JSON Plugin .............................. SUCCESS [16.944s]
[INFO] Showcase Webapp ................................... SUCCESS [20.303s]
[INFO] Struts 2 REST Plugin .............................. SUCCESS [010.646s015s]
[INFO] Struts Action2 FrameworkRest 2.0Showcase APIExample ....................... SUCCESS [26.389s928s]
[INFO] Struts Action2 FrameworkCodebehind 2.0Plugin ........................... SUCCESS [2210.155s394s]
[INFO] Webapps Struts 2 Java Templates Plugin .................... SUCCESS [9.633s]
[INFO] Struts 2 Jasper Reports Plugin .......................... SUCCESS [05.002s920s]
[INFO] Blank WebappStruts 2 JFreeChart Plugin ........................ SUCCESS [18.296s]
[INFO] Struts 2 Pell Multipart Plugin .................... SUCCESS [03.906s891s]
[INFO] Struts 2 PortetPlexus WebappPlugin ......................................... SUCCESS [14.661s715s]
[INFO] ShoppingStruts 2 CartSitegraph WebappPlugin .................................. SUCCESS [08.779s009s]
[INFO] ThirdStruts Party2 TestNG ModulesPlugin ................................... SUCCESS [06.003s012s]
[INFO] JasperReports ... Struts 2 OVal Plugin ...................................... SUCCESS [09.918s629s]
[INFO] Showcase WebappStruts 2 OSGi Plugin ....................................... SUCCESS [2.336s]
[INFO] Starter Webapp ........................................ SUCCESS [0.571s]
[INFO] JFree Chart ........................................... SUCCESS [1.972s]
[INFO] Pell File Upload ...................................... SUCCESS [0.385s]
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 35 seconds
[INFO] Finished at: Wed May 03 18:26:19 PDT 2006
[INFO] Final Memory: 14M/52M
[INFO] ------------------------------------------------------------------------

As you can see, the additional modules that aren't part of the default build were not included.

XWork profile

Besides the third party profile, another useful profile is the xwork profile. This one assumes that the latest XWork CVS code is checked out and is located at ../xwork, relative to the Struts project. You can check out XWork using these commands:

cvs -d :pserver:guest@cvs.dev.java.net:/cvs login
cvs -d :pserver:guest@cvs.dev.java.net:/cvs co xwork

Now you can do:

> mvn -Pxwork package

And you'll see that XWork is included:

[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] ------------------------------------------------------------------------.......... SUCCESS [8.118s]
[INFO] Struts Action2 FrameworkEmbedded 2.0JSP ProjectPlugin ...................... SUCCESS [030.774s524s]
[INFO] Struts Action2 GXP Framework 2.0 API Plugin ............................... SUCCESS [14.969s878s]
[INFO] XWork Struts 2 CDI Plugin ............................... SUCCESS [7.620s]
[INFO] Struts 2 Tiles 3 Plugin ........................... SUCCESS [85.757s132s]
[INFO] Struts ActionOSGi FrameworkBundles 2....0 ........................... SUCCESS [240.947s254s]
[INFO] Webapps [INFO] Struts 2 OSGi Admin Bundle ........................ SUCCESS [5.204s]
[INFO] Struts 2 OSGi Demo Bundle ......................... SUCCESS [04.002s582s]
[INFO] Blank Webapp Struts 2 Maven Archetypes ......................... SUCCESS [0.198s]
[INFO] Struts 2 Archetypes - Angular JS .................... SUCCESS [110.068s509s]
[INFO] Portet Webapp Struts 2 Archetypes - Blank ............................ SUCCESS [1.440s]
[INFO] Struts 2 Archetypes - Blank Convention ............. SUCCESS [1.391s324s]
[INFO] ShoppingStruts Cart2 Webapp ....................Archetypes - Database Portlet .............. SUCCESS [0.745s990s]
[INFO] Showcase Webapp Struts 2 Archetypes - Plugin ...................... SUCCESS [0.923s]
[INFO] Struts 2 Archetypes - Portlet ..................... SUCCESS [30.064s888s]
[INFO] Struts 2 Archetypes - Starter Webapp ........................... SUCCESS [1.992s]
[INFO] Struts 2 Assembly ............ SUCCESS [0.625s]
[INFO] ------------------------------------------------------------------------..................... SUCCESS [1:37.556s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFULSUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 44 seconds12:23.728s
[INFO] Finished at: Wed MayOct 0330 1817:3126:4927 PDTCET 20062013
[INFO] Final Memory: 14M57M/46M945M
[INFO] ------------------------------------------------------------------------

Notice that the build runs XWork before building the main Struts project. That is because instead of using the XWork snapshot release that is already pre-compiled, Maven is now understanding that it should build XWork and use the resulting artifact (jar) from that build to supply to Struts.

Multiple profiles

You can use multiple profiles at once. For example, this is possible and highly recommend for anyone spending a lot of time developing on Struts and XWork:

> mvn -Pthirdparty,xwork package

This is especially important if you wish to use Maven to build your IDE project files, which is highly recommended.

Building IDE project files

Maven has a great feature that will allow you to build up your IDEA or Eclipse project files based on the project build structure. This is a great way to make sure all developers keep in sync and operate and maximum efficiency. The IDEA project files, in fact, are pre-configured in such a way that when built many of the common tasks ("execute all tests", "launch the showcase sample app", etc) are already defined in the Run/Debug menu.

IDEA

Before you build the IDEA project files, it might be helpful to understand that Maven can actually run a phase or a plugin. Up until now we've told Maven to run build phases (package, test, clean, install, etc). You can also specify a standalone plugin that isn't bound to any particular phase. In this case, we're invoking the "idea:idea" plugin (don't worry about the redundant text other than knowing it is required).

To get the most out of your IDEA environment, it is strongly recommended you use get the latest IDEA plugin for Maven. This is as simple as executing the following command from any directory:

------------------------------------

Other phases

There are other phases that can be useful when working with Maven. The package phase will just JAR (or WAR) the modules. The test phase will only execute unit-tests. The compile phase will only build the source-code (but not the test sources). And the clean phase will remove all artifacts, typically the entire target directory.

Building IDE project files

Maven has a great feature that will allow you to build up your IDEA or Eclipse project files based on the project build structure. Using the Maven project files helps keep developers in-sync and efficient. The IDEA project files are pre-configured to define in the Run/Debug menu many common tasks, such as "execute all tests", "launch the showcase sample app", and so fort.

IDEA by JetBrains

The Maven IDEA plugin creates IDEA project and modules files, based on the Maven build configuraton (pom.xml).

First, be sure you have the latest IDEA plugin for Maven.

mvn -DconnectionUrl=scm:svn:http://svn.apache.org/repos/asf/maven/plugins/trunk/maven-idea-plugin \
    -Dgoals=install \
    scm:bootstrap

Doing this will download and install the latest IDEA plugin for maven. This step will no longer be required as soon as the Maven team releases the next version of the plugin, which includes several major improvements used specifically by the Struts build.

Next, simple run the following command (the profiles are optional, but we encourage you to use them):

> mvn -Pthirdparty,xwork idea:idea

/trunk/maven-idea-plugin \
    -Dgoals=install \
    scm:bootstrap

Most often, we use Maven to build projects, but it can also run plugins directly. To build an IDEA project file for Struts 2, including all the modules, run

> mvn idea:idea -Papps,extras,thirdparty,xwork

Maven will generate struts-parent.ipr, struts-parent.iws, and an iml file for each module listed Open up struts-parent.ipr in IDEA, and you should be good to go.

If you ever need to rebuild your projects, running the idea:idea command again will update your files without overriding any information that doesn't conflict. If you do want to overwrite the project files, specify the overwrite parameter as true.

> mvn idea:idea -Doverwrite=true -Papps,extras,thirdparty,plugins,xwork

If you only need to rebuild some of the modules, adjust the list of "profiles".

This will generate project.ipr, project.iws, and an iml file for each module in the build. Open up project.ipr and you should be all set. If you ever need to rebuild your projects, running the command again will update your files without overriding any information that doesn't conflict. However, sometimes you may wish to overwrite the project files. To do so, you can do the following:

> mvn -Doverwrite=true -Pthirdparty,xwork idea:idea

Eclipse

Eclipse is untested (most Struts users are IDEA users - sorry!), but you should be able to do:

> mvn -Pthirdparty,xwork eclipse:eclipse

The Eclipse project files will not get any of the additional benefits, such as pre-built Run/Debug targets, that the IDEA project files use.

IMPORTANT: Running the sample webapps from Eclipse or non-IDEA IDEs

Currently the sample webapps can be deployed using QuickStart. With the switch to Maven, the expected location for the jars is no longer valid. Fortunately, QuickStart has a feature where it can read in one or more IDEA iml (module) file and use the jars specified there. So far the showcase webapp is configured to do this (see it's quickstart.xml file). This means that even if you're using Eclipse, it is recommended that you generate the IDEA project files so that you can run the Showcase webapp via QuickStart.

The settings, automatically baked in to the IDEA workspace file, needed to run Showcase under QuickStart are:

Main class: org.apache.struts.action2.Main
VM params: none
Program params: quickstart
Working directory: webapps/showcase
Classpath: must include at least the struts module (Which contains the Main class)

Tips

A few helpful tips for using Maven are provided:

Offline mode

If you are disconnected from the internet or simply wish to make your build faster, just pass in the -o argument and maven won't check for new modules to download:

mvn -o -Pthirdparty,xwork package

Skipping test execution

Although this shouldn't ever happen, sometimes tests do fail and you need to build Struts anyway. Getting around this is possible by adding the -Dmaven.test.skip=true parameter:

mvn -Dmaven.test.skip=true -Pthirdparty,xwork package

Now the project will still build and tests just won't be executed. Please try to fix tests rather than skipping them!

Mirrors

The main mirror of central (also known as "ibiblio") is extremely slow and can be very unreliable. Fortunately, Maven supports mirrors. You can read more about them here, but the basic idea is that if you add the following to ~/.m2/settings.xml (or create the file if it doesn't exist), you can likely speed up the build process:

Eclipse

For Eclipse, try

> mvn -Pthirdparty,plugins,xwork eclipse:eclipse

IMPORTANT: Running the Sample Applications from Eclipse or non-IDEA IDEs

Currently the sample applications can be deployed using the Maven 2 Jetty plugin. For example, you can run the showcase example application from the command line:

cd apps/showcase
mvn jetty:run

You could also use one of the Maven IDE plugins to run the plugin or simply execute the mvn or mvn.bat file as an external application within your IDE.
A good tutorial on how to use the Maven 2 jetty plugin along with your IDE, including JPDA debugging support, can be found at the Apache Wicket documentation.

Maven Tips

A few helpful tips for using Maven are provided:

Skip exporting pages from Confluence

The whole Struts2 documentation resists on Confluence and during normal build process is exported with SiteExporter tool locally to html files. To perform that, you must have an account on Confluence. In most cases you don't need to export the whole Confluence, so you can skip this, just type command:

mvn clean install -DskipWiki

Skip creating assemblies

During normal development cycle you don't need to create assembly packages which consist of all the libraries, example apps and docs - you can skip them as well:

mvn clean install -DskipAssembly

Offline mode

If you are disconnected from the Internet or simply wish to make your build faster, pass in the -o argument and Maven won't check for new modules to download.

mvn -o

OutOfMemoryError

If you get an OutOfMemoryError while running the tests:

// Bash
export MAVEN_OPTS=-Xmx512m

// Windows
set MAVEN_OPTS=-Xmx512m

Skipping test execution

Although this shouldn't ever happen, sometimes tests do fail and you need to build the framework anyway. If there's a problem, you can pass in the skip tests parameter.

mvn -Dmaven.test.skip=true

Of course, if you find tests are failing, please submit a patch to fix them!

Debugging build failures

Struts 2 depends on the current snapshot artifact of XWork 2. Unfortunately, if XWork 2 is modified in a significant way, the Struts build doesn't check for and retrieve a new version of the XWork snapshot jar, resulting in compilation or unit test failures.

The solution is to clear out any stale XWork 2 jars in your local Maven repository, usually by removing the directory ~/.m2/repository/opensymphony. This will force the Struts Maven build to pull down a fresh copy of XWork and hopefully resolve your problem.

Mirrors

The default mirror for Maven builds ("ibiblio") can be slow and unreliable. Maven lets you specify alternative mirrors so that you don't have to depend on ibiblio for everything.

You can add new mirrors through the Settings file (~/.m2/settings.xml).

<settings>

  <mirrors>
    <mirror>
      <id>dotsrc</id>
      <url>http://mirrors.dotsrc.org/maven2</url>
      <mirrorOf>central</mirrorOf>
    </mirror>
  </mirrors>

</settings>

First time building

In some cases it has been seen that Maven will complain if a module doesn't exist, even though it is part of the current build. This is especially likely Often, the missing module turns up when executing mvn package. A simple fix for this is to run mvn install instead. If you have to do this, it will probably only be a one - time thing.

Next: Creating and Signing a Distribution