...
Info |
---|
...
is required to build SAF2. |
First, let's review some Maven basics. Maven uses the notion
...
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 to which plugins can attach. (somewhat Plugins are similar to Ant asks) can attach to. When you execute a maven build, you tasks.) When a Maven build is invoked, we specify a point in the lifecycle that you want the project built up to which the build should proceed. The 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.
Installing
The install phase simply means that maven should build builds 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.
To run a basic install, simply invoke:change to the root of the source distribution, and enter
Code Block | ||
---|---|---|
| ||
> mvn install |
That's it! Maven will download all dependencies it the build needs, run all unit tests, package up the jarsJARs, and 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 action2/target/action-2.0-SNAPSHOT.
jar would be where the main jar
is built.
Warning | ||
---|---|---|
| ||
Sometimes, licensing restrictions prevent Maven for downloading all the JARs that a build might need. For example, Some dependencies, such as JavaMail and Activation, can 't only be downloaded automatically due to license restrictions. Fortunately, Maven gives you a nice error message showing you from Sun. When this happens, Maven will display a helpful message that explains how to install these to your local repository. Simply download the required jar from Sun's website and then use the command supplied by the error message to install it. You can then try the build again. |
If all goes well, you should see something like:
JARs manually. After downloading the required JAR, follow the instructions to install it to the your local repository. Once installed, the JAR is availale to all your Maven builds, not just Struts. |
Code Block | ||
---|---|---|
| ||
Code Block | ||
[INFO] ------------------------------------------------------------------------ [INFO] Reactor Summary: [INFO] ------------------------------------------------------------------------ [INFO] Struts Action Framework 2.0 Project ................... SUCCESS [0.688s] [INFO] Struts Action Framework 2.0 API ....................... SUCCESS [2.125s] [INFO] Struts Action Framework 2.0 ........................... SUCCESS [21.866s] [INFO] Webapps ............................................... SUCCESS [0.002s] [INFO] Blank Webapp .......................................... SUCCESS [0.982s] [INFO] Portet Webapp ......................................... SUCCESS [2.038s] [INFO] Shopping Cart Webapp .................................. SUCCESS [0.934s] [INFO] Showcase Webapp ....................................... SUCCESS [3.351s] [INFO] Starter Webapp ........................................ SUCCESS [1.013s] [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 JAR (or warWAR) up the modules. The test phase will run 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 the framework with Maven is to understand build profiles. These are simply slightly Profiles provide different configurations for the a build. The following profiles are available:There are several profiles, including default, xwork, and _thirdparty".
Profile | Description |
---|---|
default | Builds action-api, action, and all sample webapps |
xwork | Includes the xwork build |
thirdparty | Includes additional modules that cannot be part of the default build due to Apache rules |
In the previous example, we didn't specify a profile so the default profile was used. However, most 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:
Code Block | ||
---|---|---|
| ||
> mvn -Pprofile ... |
Third
...
Party Profile
If you want 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:.
Code Block | ||
---|---|---|
| ||
> mvn -Pthirdparty package |
Notice that the final output is now:
Code Block | ||
---|---|---|
| ||
[INFO] ------------------------------------------------------------------------ [INFO] Reactor Summary: [INFO] ------------------------------------------------------------------------ [INFO] Struts Action Framework 2.0 Project ................... SUCCESS [0.646s] [INFO] Struts Action Framework 2.0 API ....................... SUCCESS [2.389s] [INFO] Struts Action Framework 2.0 ........................... SUCCESS [22.155s] [INFO] Webapps ............................................... SUCCESS [0.002s] [INFO] Blank Webapp .......................................... SUCCESS [0.906s] [INFO] Portet Webapp ......................................... SUCCESS [1.661s] [INFO] Shopping Cart Webapp .................................. SUCCESS [0.779s] [INFO] Third Party Modules ................................... SUCCESS [0.003s] [INFO] JasperReports ......................................... SUCCESS [0.918s] [INFO] Showcase Webapp ....................................... 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
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 folderBesides 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 two CVS commands:.
Code Block | ||
---|---|---|
| ||
cvs -d :pserver:guest@cvs.dev.java.net:/cvs login cvs -d :pserver:guest@cvs.dev.java.net:/cvs co xwork |
Note | ||||
---|---|---|---|---|
| ||||
The guest user has a blank password at java.net. If you have your own java.net account, you can use that. |
Now you can do:
Code Block |
---|
> mvn -Pxwork package
|
And you'll see that XWork is included:
your own credentials instead. (In fact, you will be checking in XWork code too, be sure that you do!) |
Tip | ||
---|---|---|
| ||
If you need to install CVS under Windows, download and extract the CVS binary, and place it on your PATH. |
Tip | ||
---|---|---|
| ||
The Maven build may need to utilize Subversion. If you don't have the command line version installed, you can download it from the Subversion site, and add the |
Code Block | ||
---|---|---|
| ||
> mvn -Pxwork package
|
Code Block |
---|
[INFO] - |
Code Block |
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[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] ------------------------------------------------------------------------
[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] ------------------------------------------------------------------------
|
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 StrutsNow, Maven will build XWork from source and use that as the XWork snapshot for the Action2 build.
Multiple profiles
You Maven can use build against multiple profiles. If you are developing against both the XWork and Action2 frameworks at once. For example, this is possible and highly recommend for anyone spending a lot of time developing on Struts and XWork:, you can install both profiles with one call to Maven.
Code Block | ||
---|---|---|
| ||
Code Block | ||
> mvn -Pthirdparty,xwork package |
This Using both profiles is especially important if you wish to use when using 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 efficiencyUsing the Maven project files helps keep developers in-sync and efficient. The IDEA project files , in fact, are are pre-configured in such a way that when built many of the common tasks (to define in the Run/Debug menu many common tasks, such as "execute all tests", "launch the showcase sample app", etc) are already defined in the Run/Debug menuand so fort.
IDEA
...
by JetBrains
First, be sure you have
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:
Code Block | ||
---|---|---|
| ||
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.
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, Next, simple run the following command ( the profiles are optional, but we encourage you it can be a good idea to use them ):anyway.
Code Block | ||
---|---|---|
| ||
> mvn -Pthirdparty,xwork idea:idea |
Tip |
---|
If you find the xwork module causing you problems, such as displaying as "XWork" when it should be named "xwork", this is likely a bug in IDEA. To fix it, clear out your IDEA system cache and try again |
This 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.
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 If you do want to overwrite the project files. To do so, you can do the following:, specify the overwrite parameter as true.
Code Block | ||
---|---|---|
| ||
> 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:
-Pthirdparty,xwork idea:idea
|
Tip | ||
---|---|---|
| ||
If you find the xwork module causing you problems, such as displaying as "XWork" when it should be named "xwork", the problem is likely to be within IDEA. Try clearing out your IDEA system cache and then run it again |
Eclipse
For Eclipse, try
Code Block | ||
---|---|---|
| ||
Code Block | ||
> mvn -Pthirdparty,xwork eclipse:eclipse |
...
Info | ||
---|---|---|
| ||
Many SAF2 developers use IDEA, and the Eclipse project files |
...
are not as well-tested or featureful as the IDEA versions. But as far as we know, they work! |
IMPORTANT: Running the
...
Sample Applications from Eclipse or non-IDEA IDEs
Currently the sample webapps applications can be deployed using QuickStart. With the switch to Maven, the expected location for the jars 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 JARs specified there. So far the showcase webapp Showcase application is configured to do this (see it's its quickstart.xml
file). This means that even
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:
Code Block | ||
---|---|---|
| ||
Main class: org.apache.struts.action2.Main VM params: none Program params: quickstart Working directory: webapps/showcase Classpath: must include at least the strutsAction2 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 Internet or simply wish to make your build faster, just pass in the -o argument and maven Maven won't check for new modules to download:.
Code Block | ||
---|---|---|
| ||
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:the framework anyway. If there's a problem, you can pass in the skip tests parameter.
Code Block | ||
---|---|---|
| ||
Code Block | ||
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 Of course, if you find tests are failing, please submit a patch to fix them!
Mirrors
The main mirror of central (also known as default mirror for Maven builds ("ibiblio") is extremely can be 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 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 (or create the file if it doesn't exist), you can likely speed up the build process:).
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<settings> <mirrors> <mirror> <id>dotsrc</id> <url>http://mirrors.dotsrc.org/maven2</url> <mirrorOf>central</mirrorOf> </mirror> </mirrors> </settings> |
Notetip |
---|
Sometimes the alternative mirrors have problems and/too or aren't updated at the same frequency as the main mirror. If you have trouble building, try commenting out the aternative mirror and see if that helps. |
First time building
In some cases it has been seen that Maven will complain a module doesn't exist, even though it is part of the current build. This is especially likely Often, the missing module complete turins 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.