Example Crucible SCM Plugin for JSR-170 (Apache JackRabbit)

Description/Features

This plugin contains an implementation of Crucible SCM for Java Content Repositories (JSR-170), using the Apache JackRabbit implementation. Note that although this code can be used without modification, it is NOT supported and intended as example code only. It should not be used in a production environment, because of several known issues discussed below. Having said that, feel free to improve on this code

Usage

Check out the source and build the plugin jar file using mvn package. Note that this plugin depends on com.sun.jdmk:jmxtools:1.2.1 and com.sun.jmx:jmxrmi:1.2.1. These libraries are provided by Sun, but may not be present in your maven repository, as Sun requires each user to agree to its license terms. If you get the following build error:

[INFO] ------------------------------------------------------------------------
[ERROR] BUILD ERROR
[INFO] ------------------------------------------------------------------------
[INFO] Failed to resolve artifact.

Missing:
----------
1) com.sun.jdmk:jmxtools:jar:1.2.1

  Try downloading the file manually from:
      http://java.sun.com/products/JavaManagement/download.html

  Then, install it using the command:
      mvn install:install-file -DgroupId=com.sun.jdmk -DartifactId=jmxtools -Dversion=1.2.1 -Dpackaging=jar -Dfile=/path/to/file

  Alternatively, if you host your own repository you can deploy the file there:
      mvn deploy:deploy-file -DgroupId=com.sun.jdmk -DartifactId=jmxtools -Dversion=1.2.1 -Dpackaging=jar -Dfile=/path/to/file -Durl=[url] -DrepositoryId=[id]

  Path to dependency:
  	1) com.atlassian.crucible.example.scm:jackrabbit-scm-plugin:atlassian-plugin:1.0-SNAPSHOT
  	2) com.sun.jdmk:jmxtools:jar:1.2.1

2) com.sun.jmx:jmxri:jar:1.2.1

  Try downloading the file manually from the project website.

  Then, install it using the command:
      mvn install:install-file -DgroupId=com.sun.jmx -DartifactId=jmxri -Dversion=1.2.1 -Dpackaging=jar -Dfile=/path/to/file

  Alternatively, if you host your own repository you can deploy the file there:
      mvn deploy:deploy-file -DgroupId=com.sun.jmx -DartifactId=jmxri -Dversion=1.2.1 -Dpackaging=jar -Dfile=/path/to/file -Durl=[url] -DrepositoryId=[id]

  Path to dependency:
  	1) com.atlassian.crucible.example.scm:jackrabbit-scm-plugin:atlassian-plugin:1.0-SNAPSHOT
  	2) log4j:log4j:jar:1.2.15
  	3) com.sun.jmx:jmxri:jar:1.2.1

----------
2 required artifacts are missing.

Then download the two libraries from Sun, extract the jar files from the zip files and follow the instructions above to manually install the artifact in your local repository. You should then be able to complete the build.

Installation

Copy the jackrabbit-scm-plugin-1.0-SNAPSHOT.jar file from the 'target/' directory to the var/plugins/user directory in your Crucible installation. Then login to the administration section, go to Plugins and click the link "Check for new plugins in...". This should detect your plugin:

Configuring the plugin

Next, click "Configure" and add a repository. The current version of this plugin can only read JackRabbit repositories directly from the local file system (as opposed to connecting to a remote JackRabbit server), so when configuring a repository, specify the location of the repository's XML file and the repository's home directory (the directory containing workspaces/, repository/ and version/).

The plugin comes with a ready to use, pre-populated JackRabbit repository in testrepo.zip (the unit tests run against this repository). When trying things out, unzip this file somewhere on the file system and point the plugin to it.

Known Limitations

As this plugin is intended as example material for those interested in building Crucible SCM Plugins, readability of the source code is more important than features, flexibility or performance and as result there are quite a number of known limitations:

• Only file based JackRabbit 1.x repositories on the local file system are currently supported. This makes this plugin impossible to use with "active" repositories, because the JackRabbit acquires an exclusive lock on the repository.
• The plugin only recognizes nodes of JCR types "nt:file" and "nt:folder". All other nodes are ignored.
• All file and folder nodes must have the mixin type "mix:versionable".
• Every file or folder node must have at least one checked-in version (hence: at least one version of each resource must have been committed).
• JSR-170 does not support ChangeSets where a changeset represents a collection of related changes to multiple entities at once. As a consequence, the plugin represents every individual change as a ChangeSet containing one file. The UUID of the version node is used as the changeset ID.
• This plugin does not detect files that are deleted.
• Due to file locking issues in JackRabbit, the plugin uses a single JCR Session instance per repository. Access is synchronized.
• The implementation for listing a set of changesets traverses the entire repository and does not cache results, which kills scalability.

Version History

Screenshots