Page History

First, let's review some Maven basics. Maven uses the notion of a build lifecycle 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 lifecycle life-cycle up to which the build should proceed. The compile phase compile comes before test, and test comes before package, and package comes before install. Once we have Maven setup, we can invoke the Struts build, and specify which phase the build should use.

...

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

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

> mvn install

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

[INFO] ------------------------------------------------------------------------Reactor Summary:
[INFO]
[INFO] Struts Reactor Summary:
[INFO] ------------------------------------------------------------------------2 .......................................... SUCCESS [6.016s]
[INFO] XWork: Core ....................................... SUCCESS [1:08.086s]
[INFO] Struts Action Framework 2.0 ProjectCore ................... SUCCESS [0.688s]
[INFO] Struts Action Framework 2.0 API ....................... SUCCESS  SUCCESS [2:42.125s604s]
[INFO] Struts Action Framework 2.0 Plugins .................................... SUCCESS [210.866s944s]
[INFO] Webapps ........Struts 2 Spring Plugin ....................................... SUCCESS [013.002s523s]
[INFO] Struts Blank2 Convention WebappPlugin ......................... SUCCESS [16.473s]
[INFO] Struts 2 JUnit Plugin ............................. SUCCESS [013.982s325s]
[INFO] PortetWebapps Webapp ........................................... SUCCESS [21.038s027s]
[INFO] ShoppingBlank Cart Webapp ...................................... SUCCESS [09.934s572s]
[INFO] ShowcaseJBoss Blank Webapp ....................................... SUCCESS [37.351s814s]
[INFO] StarterMail Reader Webapp ................................ SUCCESS [7.028s]
[INFO] Struts 2 Portlet Plugin ........................... SUCCESS [120.013s995s]
[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) the modules. The test phase will run only 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 the framework with Maven is to understand build profiles. Profiles provide different configurations for a build. There are several profiles, including default, xwork, and _thirdparty".

Tbe default profile will work for most developers, but someMost 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

If you want to build all the third-party add-ons not included with the default build, use the _thirdparty*_profile.

> mvn -Pthirdparty package

[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] ------------------------------------------------------------------------
[INFO] Struts Action Framework 2.0 Project Struts 2 DWR Plugin ............................... SUCCESS [4.432s]
[INFO] 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 [016.646s944s]
[INFO] StrutsShowcase Action Framework 2.0 API Webapp ................................... SUCCESS [220.389s303s]
[INFO] Struts Action2 REST FrameworkPlugin 2...0 ........................... SUCCESS [2210.155s015s]
[INFO] Webapps Struts 2 Rest Showcase Example .......................... SUCCESS [6.928s]
[INFO] Struts 2 Codebehind Plugin ........................ SUCCESS [010.002s394s]
[INFO] Blank Webapp Struts 2 Java Templates Plugin .................... SUCCESS [9.633s]
[INFO] Struts 2 Jasper Reports Plugin ..................... SUCCESS [05.906s920s]
[INFO] Portet WebappStruts 2 JFreeChart Plugin ........................... SUCCESS [18.296s]
[INFO] Struts 2 Pell Multipart Plugin .................... SUCCESS [13.661s891s]
[INFO] Struts Shopping2 CartPlexus WebappPlugin .................................. SUCCESS [04.779s715s]
[INFO] Struts Third2 PartySitegraph ModulesPlugin ................................... SUCCESS [08.003s009s]
[INFO] Struts JasperReports .........2 TestNG Plugin ................................ SUCCESS [06.918s012s]
[INFO] Struts Showcase2 OVal WebappPlugin ....................................... SUCCESS [29.336s629s]
[INFO] Starter WebappStruts 2 OSGi Plugin ........................................ SUCCESS [08.571s118s]
[INFO] JFree Chart Struts 2 Embedded JSP Plugin ...................... SUCCESS [30.524s]
[INFO] Struts 2 GXP Plugin ............................... SUCCESS [14.972s878s]
[INFO] PellStruts 2 FileCDI UploadPlugin ...................................... SUCCESS [07.385s620s]
[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] ------------------------------------------------------------------------

In the second run, serveral new categories are built, including "Third Party Modules" and JasperReports. If you decide to make use of any of the third-party modules, be sure to review the license, since these modules may not be under the Apache License.

XWork profile

Struts Action Framework 2 is an extension of the XWork framework. While SAF2 adds a lot of value for web developers, much of the core functionality derives from XWork. The xwork plugins add the capability to build against a current XWork checkout, rather than a precompiled JAR.

The plugin assumes that the latest XWork code is checked out and is located at ../xwork, relative to the Action2 folder. You can check out XWork using two CVS commands.

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

...

The guest user has a blank password at java.net. If you have your own java.net account, you can use your own credentials instead. (In fact, you will be checking in XWork code too, be sure that you do!)

> mvn -Pxwork package

[INFO] -----------Struts 2 Tiles 3 Plugin ........................... SUCCESS [5.132s]
[INFO] Struts OSGi Bundles ............................... SUCCESS [0.254s]
[INFO] Struts 2 OSGi Admin Bundle ........................ SUCCESS [5.204s]
[INFO] Struts 2 OSGi Demo Bundle ......................... SUCCESS [4.582s]
[INFO] Struts 2 Maven Archetypes ......................... SUCCESS [0.198s]
[INFO] Struts 2 Archetypes - Angular JS .................. SUCCESS [10.509s]
[INFO] Struts 2 Archetypes - Blank ....................... SUCCESS [1.440s]
[INFO] Struts 2 Archetypes - Blank Convention ............ SUCCESS [1.324s]
[INFO] Struts 2 Archetypes - Database Portlet ............ SUCCESS [0.990s]
[INFO] Struts 2 Archetypes - Plugin ...................... SUCCESS [0.923s]
[INFO] Struts 2 Archetypes - Portlet ..................... SUCCESS [0.888s]
[INFO] Struts 2 Archetypes - Starter ..................... SUCCESS [1.992s]
[INFO] Struts 2 Assembly ................................. SUCCESS [1:37.556s]
[INFO] ------------------------------------------------------------------------
[INFO] ReactorBUILD Summary:SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Struts Action Framework 2.0 Project ................... SUCCESS [0.774s]
[INFO] Struts Action Framework 2.0 API ....................... SUCCESS [1.969s]
[INFO] XWork ................................................. SUCCESS [8.757s]
[INFO] Struts Action Framework 2.0 ........................... SUCCESS [24.947s]
[INFO] Webapps ............................................... SUCCESS [0.002s]
[INFO] Blank Webapp .......................................... SUCCESS [1.068s]
[INFO] Portet Webapp ......................................... SUCCESS [1.391s]
[INFO] Shopping Cart Webapp .................................. SUCCESS [0.745s]
[INFO] Showcase Webapp ....................................... SUCCESS [3.064s]
[INFO] Starter Webapp ........................................ SUCCESS [0.625s]--
[INFO] Total time: 12:23.728s
[INFO] Finished at: Wed Oct 30 17:26:27 CET 2013
[INFO] Final Memory: 57M/945M
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 44 seconds
[INFO] Finished at: Wed May 03 18:31:49 PDT 2006
[INFO] Final Memory: 14M/46M
[INFO] ------------------------------------------------------------------------

Now, Maven will build XWork from source and use that as the XWork snapshot for the Action2 build.

Multiple profiles

Maven can build against multiple profiles. If you are developing against both the XWork and Action2 frameworks at once, you can install both profiles with one call to Maven.

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

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".

Eclipse

For Eclipse, try

> mvn -Pthirdparty,plugins,xwork package

Using both profiles is especially important when using Maven to build your IDE project files (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. 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

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

Aside from running phases, Maven can also run plugins, and you can even specify phases and plugins as a single command. To just build the IDEA project file, the profiles are optional, but it can be a good idea to use them anyway.

> mvn -Pthirdparty,xwork idea:idea

Maven will generate project.ipr, project.iws, and an iml file for each module in the build. Open up project.ipr in IDEA, and you shuold be good to go.

If you ever need to rebuild your projects, running the 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 -Doverwrite=true -Pthirdparty,xwork idea:idea

Eclipse

For Eclipse, try

> mvn -Pthirdparty,xwork eclipse:eclipse

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

Currently the sample applications 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 application is configured to do this (see its quickstart.xml file).

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.

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

These settings are already baked into the IDEA workspace file.

Maven 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, 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 the framework anyway. If there's a problem, you can pass in the skip tests parameter.

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

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.Of course, if you find tests are failing, please submit a patch to fix them!

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.

...

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. Often, the missing module complete turins 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