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

Download Maven from the following web site:

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

Install Maven.
Download the Dimensions CM Maven SCM plug-in from Support and Services:

https://www.microfocus.com/support-and-services/

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:

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

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

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.

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:

Goal

Description

scm:bootstrap

n Executes scm:checkout to fetch the project or stream to a clean area.

n Executes the default goal specified in the newly fetched pom.xml file located at the root of the project/stream.

release

Through a combination of release:prepare, release:perform and release:rollback supports the automatic revision of pom.xml versions, tagging and deployment. scm:tag creates a Dimensions baseline.

Note: Dimensions CM deployment is currently not supported with the release goal.

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.

Command	Options	Extension or deviation to standard Maven command
add		n Currently there is no way to 'move' the association of an added file if after the command is complete but before check-in, the file is subsequently moved or renamed. n Currently there is no way to explicitly schedule folders for addition. This only affects delivery of empty folders since new folders containing files scheduled for delivery will be created implicitly. n Any message or binary parameter specified by the command is ignored.
changelog	n dimensions.project n dimensions.relativeLocation	n The file set specified by the command is currently ignored and all changes in the project or stream scope and date range are reported. n Any branch parameter specified by the command is ignored. n dateFormat is ignored. n ’Excludes’ and ’includes’ parameters are ignored.
checkin	n dimensions.all n dimensions.add n dimensions.project n dimensions.relativeLocation n dimensions.requests	n Executes a Dimensions DELIVER command. n Any scmVersion parameter specified by the command is ignored.
checkout	n dimensions.baseline n dimensions.project n dimensions.relativeLocation	n Executes a Dimensions UPDATE command to a clean work area. n Any scmVersion parameter specified by the command is ignored.
status	n dimensions.all n dimensions.add n dimensions.project
tag	n dimensions.attributes n dimensions.project n dimensions.requests n dimensions.type	n Server operation to create a baseline using the specified tag as the new tip baseline ID. n The file set specified by the command is currently ignored and all latest items within the project or stream scope are included in the baseline. n Any scmTagParameters values specified by the command are ignored.
update	n dimensions.baseline n dimensions.project n dimensions.relativeLocation	n Any scmVersion parameter specified by the command is ignored. n Parallel development is not supported.

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.

Key	Type	Description
dimensions.all	boolean	Specifies to scm:checkin and scm:status that all foreign content is to be considered, not just files known to have been fetched from the stream being delivered to. This is a stream specific option that has been implemented to support the case where scm:checkout is against a baseline, but scm:checkin is back to the stream from where the baseline originated.
	Example: mvn scm:checkin -Ddimensions.all=true
dimensions.add	boolean	Specifies to scm:checkin and scm:status that all additions are to be considered, not just those scheduled for delivery by scm:add.
	Example: mvn scm:checkin -Ddimensions.add=true
dimensions.attributes	user defined attributes	JSON formatted set of Dimensions CM user defined attributes.
	Example: When creating a baseline use the tag command for a type with a mandatory attribute called 'planet': mvn:tag -Dtag="MYTIPBL" -Ddimensions.type="MYBLTYPE" -Ddimensions.attributes={planet:Mars}
dimensions.baseline	baseline specification	Baseline specification that overrides any project or stream specified within the URL for scm:checkout or scm:update. You can specify just the baseline ID on the command line with the product obtained from the URL.
	Example: mvn:checkout -Ddimensions.baseline=mybaseline
dimensions.project	project/stream specification	Project or stream specification that overrides any specified in the URL. You can specify just the product in the URL and the project/stream ID on the command line.
	Example: mvn:checkout -Ddimensions.project=mystream
dimensions.relativeLocation	repository relative path	Project or stream relative path (using forward slashes) that overrides any path specified in the URL.
	Example: mvn:checkout -Ddimensions.relativeLocation="Qlarius_Underwriter/Qlarius_Underwriter/Dialogs"
dimensions.requests	request list	Request specification, or a comma separated list of requests. Primarily used with the scm:checkin command.
	Example: mvn:checkin -Dmessage="the comment" -Ddimensions.requests="QLARIUS_CR_99"
dimensions.type	object type name	Dimensions object type to override the default or for specifying user defined attributes. See the scm:tag command specified in the example for dimensions.attributes above.

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:

Create an empty folder on disk.
Copy the following into a new file called pom.xml in that folder:

<artifactId>JavaStr01</artifactId>

<version>1.0-SNAPSHOT</version>

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

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

</properties>

<scm>

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

</connection>

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

</scm>

<build>

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

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

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

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

</dependency>

</dependencies>

</plugin>

</plugins>

</build>

</project>

Edit the <connection> element in pom.xml to specify your user credentials and server connection details.
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:

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>

Locally modify files.
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:

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.
Add a new local file: AddTest.txt
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:

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

<artifactId>SolarSystem</artifactId>

<version>1.0-SNAPSHOT</version>

<name>SolarSystem</name>

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

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

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

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

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

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

</dependency>

</dependencies>

</plugin>

</plugins>

</build>

<groupId>junit</groupId>

<artifactId>junit</artifactId>

</dependency>

</dependencies>

</project>

Manually place a copy of this pom.xml file in a new empty folder to simulate being
emailed for initial bootstrap.
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.