What is Maven?

Apache Maven is a software project management and comprehension tool. Based on the concept of a project object model (POM), Maven can manage a project's build, reporting, and documentation from a central piece of information. For more information about Maven see the following web site:

http://maven.apache.org/

Maven SCM provides plug-ins with a common API for SCM operations. Dimensions CM has a plug-in that integrates with Maven. For more information about Maven SCM see the following web site:

http://maven.apache.org/scm/

Terminology

Archetype

An archetype is an original model or type after which other similar objects are patterned. Maven can use different archetypes when creating a project.

Artifact

An artifact is an object that is produced or used by a project. Examples of artifacts produced by Maven for a project include JARs, source and binary distributions, and WARs. Each artifact is uniquely identified by a group ID and an artifact ID that is unique within a group.

Dependency

A typical Java project relies on libraries to build and/or run. Those are called "dependencies" inside Maven. Those dependencies are usually other projects' JAR artifacts but are referenced by the POM that describes them.

Goal

Goals are executed to perform an action on a project. For example, the jar:jar goal compiles the current project and produces a JAR file. Each goal exists in a plug-in except for those that you define yourself. The goal name usually reflects the plug-in, for example, java:compile comes from the Java plug-in.

Group ID

A group ID is a universally unique identifier for a project. This is often just the project name, for example, commons-collections. It is helpful to use a fully-qualified package name to distinguish it from other projects with a similar name, such as org.apache.maven.

Project

Maven operates with projects and everything that you build are projects. Projects follow a well defined Project Object Model (POM). Projects can depend on other projects called "dependencies". A project may consistent of several subprojects, however these subprojects are still treated equally as projects.

Plug-in

Maven is organized in plug-ins and every piece of functionality in Maven is provided by a plug-in. Plug-ins provide goals and use the metadata found in the POM to perform their task. Examples of plug-ins are jar, eclipse, and war.

Project Object Model (POM)

The Project Object Model is the metadata that Maven needs to work with your projects. It is called pom.xml and it is located in the root directory of each project.

Repository

A repository is a structured storage of project artifacts organized under the following structure:

$MAVEN_REPO/groupId/artifact type/project-version.extension

For instance, a Maven JAR artifact will be stored in a repository under:

/repository/maven/jars/maven-1.0-beta-8.jar

Maven uses the following repositories:

• Remote repositories are a list of repositories that Maven downloads from. For example, an internet repository, its mirrors, and a private company repository.

• The "central repository" is the repository to which generated artifacts are uploaded, for example, for use by developers.

• The "local repository" is the repository that you have on your local machine. Artifacts are downloaded just once, unless they are a snapshot, from the remote repository to your local repository.

Snapshots

Projects can and should have a special version including a snapshot to indicate that they are a "work in progress" and are not yet released. When a snapshot dependency is encountered it is always searched for in all remote repositories, and downloaded again if it is newer than the local copy. The version can either be the string SNAPSHOT, indicating "the very latest" development version, or something similar to 1.1-SNAPSHOT, indicating development that will be released as 1.1 (newer than 1.0, but not yet 1.1).

Checkin and checkout

If you are using streams in Dimensions CM the following terminology is different: you deliver changes (check in) and update your work area (check out).

Installing and Configuring the Maven SCM Dimensions CM Provider

The following sections describe how to install and configure the Dimensions CM Maven plug-in.

Downloading and Installing

1. Download Maven from the following web site:

http://maven.apache.org/download.html

2. Install Maven.

3. Download the Dimensions CM Maven SCM plug-in:

a    Logon to the Serena Support web site:

http://support.serena.com

b    Select the My Downloads tab.

c     From the Product list select Dimensions CM.

d    In the Product column find Serena Dimensions CM 12.2.

e    In the Available Operating Systems column select Windows or Linux.

f      In the Integrations section download the appropriate zip or tar file.

4. Specify one of the following environment variables:

• MAVEN_HOME

• M2_HOME

5. Extract the contents and run the Maven SCM plug-in installer.

Specifying User Credentials in pom.xml

The format for the user credentials in pom.xml is:

scm:dimensions://[<username>][:<password>]@<server>[:<port>]/<dbName>@<dbConnection>[/product][:project][/relativeLocation]

Examples:

scm:dimensions://fred:fred_test@dimserver:671/cm_typical@dim12/qlarius:mainline_vs_str/

scm:dimensions://fred:fred_test@dimserver:671/cm_typical@dim12/qlarius:mainline_vs_str/Qlarius_Underwriter/Qlarius_Underwriter/Dialogs/

Edit your pom.xml file accordingly.

Specifying User Credentials in an External File

The user credentials in pom.xml are optional and you can specify them in an external file, settings.xml. To specify user credentials do the following:

1. Remove any user credentials from pom.xml. For example:

scm:dimensions://@dimserver:671/cm_typical@dim12/qlarius:mainline_vs_str/

2. Open settings.xml in the Maven local repository, typically located in:

${user.home}/.m2/settings.xml

Note: If settings.xml does not exist in the above location copy it from:

$M2_HOME/conf/settings.xml.

3. Under the <servers> element add a new <server> element and specify:

• The server and port.

• The <username> and <password>.

For example:

<server><id>dimserver:671</id><username>fred</username><password>fred_test</password></server>

These steps will ensure that:

• There is no confidential information in pom.xml and it can be distributed for use by other members of your organization.

• The correct login credentials are used when Maven SCM commands are issued.

Goals

The high level goals currently supported by the Dimensions CM Maven plug-in are:

Maven SCM Plug-in Commands and Options

Commands

The table below lists the Maven SCM plug-in commands that are completely or partially supported by the Dimensions CM Maven plug-in.

Options

Some of the commands listed above support options that are not available in the Maven SCM plug-in. To pass an option through to the Dimensions plug-in, specify it on the command line as -Dkey=value. This passes the option through as a system property. The following table lists the currently supported options.

Scenarios

The scenarios below show you ways that you can use the Maven plug-in.

Scenario 1: Updating an Existing Stream

This simple scenario describes how to update an existing stream and assumes that:

•    A stream exists and contains files and folders.

•    Maven has been installed and the mvn executable is on the path.

•     The Maven SCM Dimensions CM Provider is installed.

Steps:

1. Create an empty folder on disk.

2. Copy the following into a new file called pom.xml in that folder:

<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/xsd/maven-4.0.0.xsd">

   <modelVersion>4.0.0</modelVersion>

   <groupId>com.acme</groupId>

   <artifactId>JavaStr01</artifactId>

   <version>1.0-SNAPSHOT</version>

   <packaging>jar</packaging>

   <name>JAVA_STR_01</name>

   <url>http://maven.apache.org</url>

   <properties>

      <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

   </properties>

   <scm>

      <connection>

         scm:dimensions://fred:fred_test@localhost:671/cm_typical@dim12/   qlarius:java_str_01

      </connection>

      <url>http://localhost:8080/dimensions</url>

   </scm>

   <build>

      <plugins>

         <plugin>

            <groupId>org.apache.maven.plugins</groupId>

            <artifactId>maven-scm-plugin</artifactId>

            <version>1.5</version>

            <dependencies>

               <dependency>

                  <groupId>org.apache.maven.scm</groupId>

                  <artifactId>maven-scm-provider-dimensions</artifactId>

                  <version>1.5</version>

               </dependency>

            </dependencies>

         </plugin>

      </plugins>

   </build>

</project>

3. Edit the <connection> element in pom.xml to specify your user credentials and server connection details.

4. On the command line execute (from the same folder where pom.xml resides):

mvn scm:update

Result:

The stream is fetched to the current folder.

NOTE  

• The top section of elements in pom.xml specify the properties of the stream being fetched. Their values are not important when performing simple SCM operations and are used when Maven goals are run to compile/build sources fetched from Dimensions.

• The element <build> in pom.xml is required to help Maven find and load the Dimensions CM provider.

Scenario 2: Checking Out Using a Copy of pom.xml

This scenario is similar to scenario 1 above. The difference is that the same pom.xml file has been checked into the stream at the root of the project and copied to an empty folder to simulate having been emailed to a user who wants to fetch the stream.

Steps:

From the folder where pom.xml is located execute the following command line:

mvn scm:checkout

Result:

The stream is fetched to the following subfolder:

target\checkout

NOTE  

• After this initial fetch you can discard the original pom.xml file and perform all future SCM operations directly from the subfolder where the stream was fetched (the pom.xml from the stream was fetched there).

• Alternatively you can also use any Dimensions CM client to fetch files and then run pom.xml for any subsequent operations.

Scenario 3: Checking In a Modified File

This scenario is similar to scenario 2 above. The difference is that you have modified files locally and want to check them in (deliver to Dimensions CM).

Steps:

1. To check in files to a location in the repository that is different from where you checked them out, add the following to the scm element of your pom.xml file:

<developerConnection>scm:dimensions://fred:fred_test@localhost:671/cm_typical@dim12/qlarius:java_str_02</developerConnection>

2. Locally modify files.

3. Execute the command line:

mvn scm:checkin -Dmessage="test modification"

Result:

The modified files are delivered to the stream.

Scenario 4: Checking In an Added File

This scenario is similar to scenario 2 above. The difference is that you have added a file locally, want to schedule a delivery, and check it in (deliver to Dimensions CM).

Steps:

1. To check in files to location in the repository that is different from where you checked them out, see step 1 in scenario 3 above.

2. Add a new local file: AddTest.txt

3. Execute the following commands:

mvn scm:add -Dincludes="AddTest.txt"

mvn scm:checkin -Dmessage="test addition"

Results:

•    The first Maven command ensures the new file is scheduled for delivery.

•     The second Maven command delivers the new file back to the stream.

Scenario 5: Checking Out and Executing Default Goals

This scenario shows you how to mix Maven and Dimensions CM commands.

The boostrap command issues the scm:checkout command and if the project or stream that is fetched has a pom.xml file at its root, the default goals specified in the file are executed. The scenario assumes that:

• Maven has been installed and the mvn executable is on the path.

• The Maven SCM Dimensions CM Provider is installed.

• A stream exists that contains the source code for a simple java app that is compatible with being compiled, unit tested, documented, and packaged as a *.jar file by Maven.

Steps:

1. Check a new pom.xml file into the root of the stream with the following content (replace the user credentials and connection details):

<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/xsd/maven-4.0.0.xsd">

   <modelVersion>4.0.0</modelVersion>

   <groupId>com.acme</groupId>

   <artifactId>SolarSystem</artifactId>

   <version>1.0-SNAPSHOT</version>

   <packaging>jar</packaging>

   <name>SolarSystem</name>

   <url>http://maven.apache.org</url>

   <properties>

      <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

   </properties>

   <scm>

      <connection>scm:dimensions://fred:fred_test@localhost:671/cm_typical@dim12/      qlarius:solarsystem</connection>

      <developerConnection>scm:dimensions://fred:fred_test@localhost:671/   cm_typical@dim12/qlarius:java_str_02</developerConnection>

      <url>http://localhost:8080/dimensions</url>

   </scm>

   <build>

      <defaultGoal>package</defaultGoal>

      <plugins>

         <plugin>

            <groupId>org.apache.maven.plugins</groupId>

            <artifactId>maven-scm-plugin</artifactId>

            <version>1.5</version>

            <dependencies>

               <dependency>

                  <groupId>org.apache.maven.scm</groupId>

                  <artifactId>maven-scm-provider-dimensions</artifactId>

                  <version>1.5</version>

               </dependency>

            </dependencies>

         </plugin>

      </plugins>

   </build>

   <dependencies>

      <dependency>

         <groupId>junit</groupId>

         <artifactId>junit</artifactId>

         <version>3.8.1</version>

         <scope>test</scope>

      </dependency>

   </dependencies>

</project>

2. Manually place a copy of this pom.xml file in a new empty folder to simulate being
   emailed for initial bootstrap.

3. From that folder execute the command line:

mvn scm:bootstrap

Result:

The stream is fetched from Dimensions CM to the "target\checkout" subfolder and Maven then compiles, unit tests, and packages the Java application.