...
artifactId/ | project directory |
---|---|
|-- .cvsignore | contains files that are local to build: target, profiles.xml, etc |
|-- pom.xml | POM file |
|-- profiles.xml | local, user and project dependent profile definitions; this should not be version controlled |
|-- LICENSE.txt | license of the project |
|-- README.txt | welcome to the reader |
|-- src/ | original src material; this should be version controlled |
|-- main/ | the original material for the artifact |
|-- java | root of main Java source; will be compiled into target/classe |
|-- resources/ | main Java resources; will be copied into target/classes |
|-- webapp/ | web application with standard web application structure |
|-- WEB-INF/ |
|
| '-- web.xml |
|
'-- index.jsp |
|
|-- assembly/ |
|
'-- dep.xml | assembly descriptor for maven-assembly-plugin |
|-- filters/ | resource filter properties files for main Java resources |
|-- config/ | configuration files for the artifact |
|-- bash/ | sources in other technologies for the artifact |
|-- python/ | |
|-- sql/ | |
|-- site/ | project documentation in different formats; mvn site will produce a project website in target/site based on this material and structure (Doxia) |
|-- fml/ | documentation in FML format (XML based FAQ format) |
'-- faq.fml | |
|-- resources/ |
|
|-- css/ |
|
|-- img/ |
|
|-- js/ | site resources; will be copied into target/site as-is |
|-- site.xml | site descriptor: description of site structure; this will generate menus |
|-- xdoc/ |
|
'-- xdoc.xml | documentation in Xdoc format (XML based HTML generation; maven 1 legacy) |
|-- test/ | original material to test the artifact |
|-- java/ | root of Java source for testing the artifact; usually JUnit test classes; will be compiled into target/test-classes |
|-- resources/ | resources for testing the artifact; will be copied into target/test-classes |
|-- filters/ | resource filter properties files for resources for testing the artifact |
|-- python/ | sources in other technologies for testing the artifact |
|-- target/ | generated material; this should not be under version control |
|-- artifactId-version.jar | generated artifact |
|-- classes/ | result of compilation of src/main/java and copy of src/main/resources |
|-- exported-pom.xml | consolidated POM |
|-- javadoc/ | javadoc of src/main/java |
|-- site/ | project site generated by mvn site |
|-- surefire-reports/ | test reports |
|-- test-classes/ | result of compilation of src/test/java and copy of src/test/resources |
|-- announcement/ | |
'-- announcement.vm | org.codehaus.mojo:changelog-maven-plugin generates announcement mail here |
|-- denotes subdirectory | '-- denotes file in the directory |
...
Maven 1.x | Maven 2.x | Description |
---|---|---|
<project> | <project xmlns="http://maven.apache.org/POM/4.0.0" | Keep more extended version of project, so you can visit the schema and validate document |
<pomVersion>3.0.0</pomVersion> | <modelVersion>4.0.0</modelVersion> | Differentiates between different versions of POM objects |
<groupId> | <groupId> | Stays the same |
<artifactId> | <artifactId> | Stays the same |
<currentVersion> | <version> | Same meaning |
<shortDescription> | <description> | Same meaning |
<package> | Not used, JavaDoc is done differently in Maven 2 | The Java package name of the project. This value is used when generating JavaDoc. |
<siteAddress> | Not used, hostname is part of the corresponding <url> element | The hostname of the web server that hosts the project's web site. This is used when the web site is deployed. |
<siteDirectory> | Not used, directory part of the corresponding <url> element | The directory on the web server where the public web site for this project resides |
<repository> | Should be nested inside <repositories> element | Specifies various Maven and SCM repositories |
<developerConnection> | Should be moved to <scm> element | Defines connection to SCM (Source Control Management) for developers. |
<reports> | <reports> <reporting> (and <report>*) Delete, it is deprecated in Maven 2. | This element includes the specification of reports to be included in a Maven-generated site. |
<properties> | If used inside <dependency> delete the element and use <scope>, <version>,<type> as described in http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html | Dependency properties |
<url> | If used inside <dependency>, delete it. | Different URLs nested inside other elements |
<sourceDirectory> | <sourceDirectory> | Used inside <build>, no need to specify, if the default src directory is used. |
<issueManagementUrl> | <issueManagement> | url of Jira server |
|
|
|
3. File after substitutions:
...
If we run mvn install target with this POM file, it will still not build completely as we need to locate dependencies that are not found in the parent POM central repositories (modules and plugins): http://repo1.maven.org/maven2
Maven 2 profile files
...
Code Block |
---|
<profile>
<id>profile1</id>
[...]
<activation>
<property>
<name>debug</name>
</property>
</activation>
</profile>
This will activate the profile when the system property "debug" is specified with any value.
3.3
|
<profile>
<id>profile1</id>
...
<activation>
<property>
<name>environment</name>
<value>test</value>
</property>
</activation>
</profile>
Code Block |
---|
This last example will activate the profile when the system property "environment" is specified with the value "test".
h3. (e) profiles.xml file for org-glast-groupmanager
Based on the general discussion above of profiles, I have chosen initially the following profiles.xml file.
Note: settings.xml file in my Maven2 repository directory (~igor/.m2) is just:
{code:title=settings.xml}
<?xml version="1.0" encoding="UTF-8"?>
<settings>
</settings>
|
The profiles file will initially point to project specific repositories that are needed to complete the dependency resolution. In the transition period, when some of the files are in Maven 1 repositories (both GLAST and developer ) and only some of the files are in GLAST Maven 2 respository:
http://glast-ground.slac.stanford.edu/maven2/ or
/nfs/slac/g/glast/ground/maven2
we need to establish the set of repositories to follow the following path in the order of precedence:
1.http://repo1.maven.org/maven2/
2. any outside repositories not in maven2 repository above (like apache.org, sun.com, freehep.org)
3.http://glast-ground.slac.stanford.edu/maven2/
4.http://glast-ground-slac.stanford.edu/maven1/
5. and only than developer specific repositories:
6. ~developer/.m2/repository
7. ~developer/.maven/repository
...
They can be viewed through the web interface
http://glast-ground.slac.stanford.edu/maven2/
GLAST parent POM
...
Code Block | ||
---|---|---|
| ||
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>glast</groupId> <artifactId>maven-parent</artifactId> <version>1.0-SNAPSHOT</version> <organization> <name>Glast</name> <url>http://glast-ground.slac.stanford.edu</url> </organization> <repositories> <repository> <id>glast-maven</id> <name>GLAST Maven 2 Repository</name> <url> http://glast-ground.slac.stanford.edu/maven2/ </url> <releases> <enabled>false</enabled> </releases> </repository> <repository> <id>glast-maven-snapshots</id> <name>GLAST Snapshot Repository</name> <url> http://glast-ground.slac.stanford.edu/maven2/SNAPSHOTS </url> <releases> <enabled>false</enabled> </releases> </repository> </repositories> </project> |
...
Code Block | ||
---|---|---|
| ||
<!-- use the following in if you're not using a snapshot version. xxxx-->
<repository>
<id>glast-maven2</id>
<name>GLAST Maven 2 central repository</name>
<url>scp://glast-java.slac.stanford.edu:/nfs/slac/g/glast/ground/maven2/</url>
</repository>
<!-- use the following if you ARE using a snapshot version. -->
<snapshotRepository>
<id>glast-maven2-snapshots</id>
<name>GLAST Maven2 centreal SNAPSHOTS repository</name>
<url>scp://glast-java.slac.stanford.edu:/nfs/slac/g/glast/ground/maven2/SNAPSHOTS</url>
<!-- this is set to false, to prevent multiple versions of SNAPSHOT files -->
<uniqueVersion>false</uniqueVersion>
</snapshotRepository>
|
...
Code Block | ||
---|---|---|
| ||
<pluginRepositories>
<pluginRepository>
<id>glast-maven2-plugins</id>
<name>GLAST Maven2 central PLUGINS repository</name>
<url>scp://glast-java.slac.stanford.edu:/nfs/slac/g/glast/ground/maven2/PLUGINS</url>
<uniqueVersion>false</uniqueVersion>
</pluginRepository>
</pluginRepositories>
|
...
Code Block | ||
---|---|---|
| ||
<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> <!-- every project POM must include GLAST parent POM --> <parent> <groupId>glast</groupId> <artifactId>maven-parent</artifactId> <version>1.0</version> </parent> <modelVersion>4.0.0</modelVersion> <groupId>glast</groupId> <artifactId>sample-maven-webapp</artifactId> <packaging>war</packaging> <version>1.0-SNAPSHOT</version> <name>Sample Maven Webapp</name> <url>http://glast-ground.slac.stanford.edu</url> <dependencies> <!-- enter project specific POM --> </dependencies> <build> <finalName>sampleMavenWebapp</finalName> </build> </project> |
Note | |
---|---|
|
Deploying your project in GLAST Maven 2 repository:
If you can deploy to cvs server and deploy to Maven 1, you are already set for deploying to Maven 2.
If not, make sure that you can ssh and scp to glast-java.slac.stanford.edu
Using ssh at SLAC is nicely described in: http://glast-ground.slac.stanford.edu/workbook/ (Under Getting Conntected, Secure Shell).
To learn about ssh and different authentication strategies http://www.linux.com/articles/34958?tid=78&tid=82
Basic requirement is that you need to be able to do scp without password authentication.
Using archetypes to create specific type of projects.
Often, you would like to use a default Maven 2 sceleton project for particular type of project, that are not already part of NetBeans or your IDE. In that case you need to locate your favorable 'archetype' on the web, and use it to build a sceleton project. For example, if there were many projects that are going to use Struts2 framework, one would download Struts2 starter project archetype, called struts2-archetype-starter.
To generate the starter project, select the working directory, and issue the following command:
Code Block | ||
---|---|---|
| ||
mvn archetype:create
-DgroupId=org.glast.struts2
-DartifactId=app
-DarchetypeGroupId=org.apache.struts
-DarchetypeArtifactId=struts2-archetype-starter
-DarchetypeVersion=2.0.9-SNAPSHOT
-DremoteRepositories=http://people.apache.org/maven-snapshot-repository
|
| |
In order for you to see what happens during the inheritance process, you will need to use the handy You will notice that the POM that you see when using the mvn help:effective-pom is bigger than you expected. Remember that |
Deploying your project in GLAST Maven 2 repository:
If you can deploy to cvs server and deploy to Maven 1, you are already set for deploying to Maven 2.
If not, make sure that you can ssh and scp to glast-java.slac.stanford.edu
Using ssh at SLAC is nicely described in:
http://glast-ground.slac.stanford.edu/workbook/ (Under Getting Conntected, Secure Shell).
To learn about ssh and different authentication strategies http://www.linux.com/articles/34958?tid=78&tid=82
Basic requirement is that you need to be able to do scp without password authentication.
Using archetypes to create specific type of projects.
Often, you would like to use a default Maven 2 sceleton project for particular type of project, that are not already part of NetBeans or your IDE. In that case you need to locate your favorable 'archetype' on the web, and use it to build a sceleton project. For example, if there were many projects that are going to use Struts2 framework, one would download Struts2 starter project archetype, called struts2-archetype-starter.
To generate the starter project, select the working directory, and issue the following command:
Code Block | ||
---|---|---|
| ||
mvn archetype:create
-DgroupId=org.glast.struts2
-DartifactId=app
-DarchetypeGroupId=org.apache.struts
-DarchetypeArtifactId=struts2-archetype-starter
-DarchetypeVersion=2.0.9-SNAPSHOT
-DremoteRepositories=http://people.apache.org/maven-snapshot-repository
|
This command will create a Struts2 application prototype, in the 'app' directdory. From there you can use the files in directory 'app' as a starting point for your new Struts2 application project.
Configuring the Dependencies
Most of the time there is no configuration for repositories in the pom.xml configuration file
because there is a built-in default repository (pointing to http://repo1.maven.org/maven2).
Most of the time, open source projects will publish artifacts to the central repository, but they
can also host their own repositories and not made them available.
Hibernate, which is now under the JBoss umbrella of projects, is such an example.
To integrate Hibernate into the web application, two different types of dependencies are
required: for the Hibernate code itself, and for the JPA and transactional APIs that are implemented.
The JBoss repository contains both of these types, so configuring the pom.xml configuration
file is easy. A new repositories tag is added under the top-level project tag, which in
turn contains a repository tag with an id tag (providing a unique identifier) and a url tag
(that supplies the URL of the repository).
<project>
...
<repositories>
<repository>
<id>jboss</id>
<url>http://repository.jboss.com/maven2</url>
</repository>
</repositories>
<project>
As well as the common repositories outside our organization, we have created repositories inside GLAST. This is a great strategy because developers know that if an artifact is installed in the GLAST repository, it can be used. Along with external artifacts, this
repository hosts internal projects and libraries to provide a central access point here at SLAC.
Installing new artifacts in the GLAST Maven 2 repository
When dealing with a build tool that automates dependency management (especially downloading the
libraries for you) such as Maven2, the artifact or library that you require may not be available.
The following are two scenarios when JAR files are not automatically retrieved and installed:
? The distributing organization does not publish the JAR files to the standard remote repositories (such
as ibiblio.com).
? A legal restriction such as a user acknowledgment or license agreement needs to be accepted before
using the files.
In either of these cases, additional steps are required before the JAR file can be configured in the
pom.xml configure file and utilized in your application:
1. Locate the download location for the libraries that are needed
2. Accept the license agreement (if applicable), and download the file.
3. If the files are downloaded as archives (other than JAR files), expand the archive into a working
directory.
4. Install the required libraries into your local Maven2 repository (usually in ~/.m2)
Once downloaded, Maven2 provides a command to install the library into the correct local repository
location and to create the necessary metadata files within the repository. The command has the following
form:
Code Block |
---|
mvn install:install-file -DgroupId=<groupId>
-DartifactId=<artifactId>
-Dversion=<version>
-Dpackaging=jar
-Dfile=</path/to/downloaded/file>
|
For an example, let's take the Hibernate annotations file (remember this is an example and this step
doesn't need to be performed). Following is the dependency configuration that will be added into the web
application's pom.xml configuration file:
Code Block |
---|
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-annotations</artifactId>
<version>3.2.1.ga</version>
</dependency>
|
This provides all the information needed to issue the install command from earlier. By substituting the
groupId, artifactId, and version information, and issuing the command from the directory that the
hibernate-annotations.jar (the name of the file that was downloaded) is located, the Maven2 command
to install the library becomes the following:
Code Block |
---|
mvn install:install-file -DgroupId=org.hibernate
-DartifactId=hibernate-annotations
-Dversion=3.2.1.ga -Dpackaging=jar -Dfile=hibernate-annotations.jar
|
The preceding pom.xml configuration is now able to access the dependency from your local development
environment.
The next step is to configure Maven2 so that the application can access the Hibernate
dependencies. We saw above that this is achieved by adding the dependency file
information to the dependencies node of the pom.xml configure file. When configured in this
manner, Maven2 goes out and retrieves the JAR files from either a local repository or the
newly configured remote repository.
Code Block |
---|
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate</artifactId>
<version>3.2.1.ga</version>
</dependency>
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-annotations</artifactId>
<version>3.2.1.ga</version>
</dependency>
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-entitymanager</artifactId>
<version>3.2.1.ga</version>
</dependency>
|
Note Each Hibernate dependency also has its own dependencies, known as transitive dependencies.
When the project you are using is built for Maven2, the transitive dependencies are configured and downloaded
automatically with the dependency that you have configured. But occasionally, you will encounter
a project that has not been built for Maven2. In this case, you need to add each of the transitive dependencies
individually to the pom.xml configuration file manually.
Guide to using Maven 1.x repositories with Maven 2.x
When you are migrating from Maven 1.x to Maven 2.x you will first be trying to convert your build and to make this easier we have provided a way for you to use your existing Maven 1.x repository so that you don't have to convert your repository before trying to migrate your projects. To use a Maven 1.x repository with your Maven 2.x project you need to specify this in your POM as follows:<project>
...
<repositories>
<repository>
<snapshots>
<enabled>true</enabled>
</snapshots>
<id>my-m1-repository</id>
<name>Maven 1.x Repository</name>
<url>http://repostory.mycompany.com/maven1</url>
<layout>legacy</layout>
</repository>
</repositories>
...
</project>
Enabling the snapshots is important as Maven 2.x makes a distinction between repositories that contain snapshots and those that don't. In Maven 1.x there is no distinction, so setting snapshots to true will give you the Maven 1.x style repository behavior while using Maven 2.x This command will create a Struts2 application prototype, in the 'app' directdory. From there you can use the files in directory 'app' as a starting point for your new Struts2 application project.
Web application deployments on tomcat servers
...