The Jazz provider implements Maven's generic SCM API for the Jazz SCM system.

Jazz SCM is included in the Rational Team Concert product.

Use Cases

The provider must handle a number of different use cases:

  • Label a source tree and check out that label to a temp directory (the release plugin).
  • Provide a changelog between dates/revisions and checkout code to a directory (Continuum et al).
  • Map a number of commands designed for CVS/SVN onto the semantics provided by Jazz SCM (the scm plugin).


The main semantic issue faced by the provider is CVS/SVN's (around which the original SCM API and release manager/plugin where written) concept of a working copy versus Jazz SCM's concept of a Sandbox, Repository Workspace and Stream.

CVS/SVN allow the user to checkout any repository location to any local directory at will and tracks this by keeping metadata in a CVS/.svn directory.

Jazz Basics

Jazz SCM uses a "remote repository workspace", or more commonly called a "repository workspace", which is an object in the repository on the Jazz server, used to store items that have been placed under source control. A "sandbox" is a copy of the "repository workspace" on your local machine, which exists as files and directories, where you perform your changes. The .jazz5 metadata directory contains the metadata for the sandbox, which includes information about which files and folders have been loaded from the remote repository workspace. Overlapping sandboxes (a sandbox within a sandbox) are not permitted. This limitation forces us to use the workingDirectory option when using the release:perform goal. The working directory must be outside of the current sandbox.

Relationships between Streams, Repository Workspaces, Components and Sandboxes.

In the simplest case, we have a single Repository Workspace, with a single Component in it. Associated with that, we have a sandbox.

Relationships between Repository Workspaces, Components and Sandboxes.

Adding a Stream introduces the concept of Flow Targets.

Relationships between Streams, Repository Workspaces, Components and Sandboxes.

A Repository Workspace may be configured to have a Flow Target. A flow target may be a Stream or another Repository Workspace. A Repository Workspace can have multiple flow targets simultaneously. Flow targets can also be changed.

A developer will deliver their changes to the flow targets defined for their Repository Workspace. The corresponding action for a Snapshot is the promote operation. Another developer will accept those changes when they are ready too.

Flow Targets

V1.4 of the Maven SCM API introduced an option pushChanges that allows for changes in distributed SCM to be pushed into a central repository.

In Jazz terms, a checkin or load operates between the sandbox and the repository workspace.

A deliver or accept operates between a repository workspace and its flow target, normally a stream but could also be another repository workspace. The promote is used to

The Maven pushChanges option controls the deliver or promote operations.

The pushChanges option, by default is true, but for the deliver or promote operations to have meaning, the repository workspace needs to have a flow target defined.

If the pushChanges option is true (the default), and there is no flow target defined, then no deliver or promote operations are attempted.


One other thing to be aware of, is that Jazz allows you to have the same name for Repository Workspaces, Streams, Components and Baselines. This provider will create a Repository Workspace of the same name as the Snapshot, as currently the underlying tool, scm, does not allow the direct loading of a snapshot into a sandbox. It is recommended that the user implements some namespace standards and policies to help manage this.

URL Format


  • username;password May be provided directly in the pom, or using the server_name:port to obtain the details from the user's settings.xml file.
  • http[s]://server_name:port/contextRoot Specify the jazz server and path to connect to. The context root is usually 'jazz' or 'ccm'.
  • repositoryWorkspace The name of the user's remote repository workspace used to checkin to, or load from.

Working with the Release Plugin

We are able to use the release:prepare and release:perform goals in the one invocation, however, due to the sandbox within a sandbox issues discussed above, we need to use the workingDirectory option.

Here is a sample:

mvn -B -Dresume=false -DworkingDirectory=/tmp/maven release:prepare release:perform

For a complete explanation on the restrictions and limitations of using this provider, see the link, "Working with the Release Plugin" above.

SCM Commands


Although the scm command supports persistent login using the scm login command, it is not used by this provider. The username and password can either come from the URL in the pom.xml file, or from a <server> section in a settings.xml file. The password is masked in the output of the execution of the scm command.

Note Having the username and password set in the pom.xml takes precedence over the <server> entry from settings.xml.


Jazz SCM does not have the equivalent of an add command. This implementation uses the scm checkin command. However, it does not call the scm deliver command, nor does it create a changeset.


This provider uses the scm annotate command.


Not implemented.

A branch in Jazz SCM is roughly equivalent to a Stream or possibly even a Repository Workspace, depending on how the flow targets have been defined, thus the branch command could be used to create a new Stream or Repository Workspace. The Jazz SCM command scm create workspace can be used to create new Repository Workspaces, however, there is currently no scm create stream command.

Jazz SCM also further complicates the issue by allowing multiple flow targets.

This provider does not currently explicitly support multiple flow targets. When there are multiple flow targets defined, the flow target defined as "current" will be used, not the "default" one. This information is obtained from the output of the scm status command.

Note Some commands, such as edit and unedit work with the implicit flow targets of the Repository Workspace.


This provider uses the scm history command to obtain a list of all changesets. It then uses the scm list changesets to obtain the details of each individual changeset.


This provider will create a changeset with the provided message. The implementation uses the scm checkin command, it uses the Add command implementation.

If the repository workspace has a valid flow target (ie, not itself) and the pushChanges option it true, which by default it is, then this provider will also deliver the changes to the flow target using the scm deliver command.

Note: Only a single flow target is currently supported. When multiple flow targets have been defined, the flow target marked as "current" will be used. This provider is not aware of the other targets. This information is not available from the scm status command.


The implementation uses the scm load command.


The diff implementation produces a diff based on the difference between changes in the sandbox and the repository workspace. A flow target, if defined, is not used. The scm command is not currently able to produce a single diff output of all files that have changed. So the scm status command is used to determine all changed files, and then iterates through the list, calling scm diff for each individual file.

By default, an ${artifactId}.diff file will be produced in the current working directory. This .diff file can be then imported into the Eclipse Client using the following procedure.

Right click, then, Team > Apply Patch...

In the dialog that opened, select the patch file. Note that no files will be shown in the 'This patch effects the following files' list. Select Next. Choose the 'Workspace Root' radio button and then click on the Finish button.

In the 'Pending Changes' view, select 'Merge into Workspace'. The patch will be applied.


The implementation uses the scm lock acquire command, and uses the implicit flow targets defined for the repository workspace. If none are defined, the command will fail.


The scm status command is called first to obtain the remote repository workspace and component name. These are then used as parameters for the scm list remotefiles command.


This provider uses the scm status command.


The scm status command is called first to obtain the remote repository workspace and stream name. The Jazz SCM equivalent of a tag is a snapshot. A baseline could have been used, however, baselines are not supported or used by this provider. Please note however, that when a snapshot is created, a baseline will also be implicitly created. Also, Jazz SCM currently does not support the loading of a snapshot directly, we can only load from a repository workspace. So, to facilitate this, the tag command also creates a remote workspace repository of the same name as the tag, ie: ${artifactId}-${version}.

This provider can call up to four different scm commands to fully accomplish this function.

  • The scm create snapshot command is first called to create snapshot.
  • The scm create workspace command is called to create a repository workspace that can later be loaded by the checkout command (for the release plugin).
  • The scm deliver command is called to deliver the changes to the flow target (if defined and pushChanges is true).
  • The scm snapshot promote command is called to promote the snapshot to the flow target (if defined and pushChanges is true).


The implementation uses the scm lock release command, and uses the implicit flow targets defined for the repository workspace. If none are defined, the command will fail.


This provider uses the scm accept command to receive updates into the remote repository workspace. If a sandbox has been loaded from the remote repository workspace, it too will also be updated.


Generally to get yourself out of trouble you'll need to manipulate Jazz externally by either using the scm command or using the RTC Eclipse client to resolve the issues encountered.


The scm command still has a number of issues dealing with files in the sandbox root directory. There are a number of Work Items on that have been opened to track this, and other issues raised by the implementation of this provider.

However, despite this, this implemention provides sufficient functionality to be able to successfully work with the maven release plugin.