This is the Specification User's Guide for the JSR-147 Workspace Versioning and Configuration Management (WVCM) API . The Java source code has already been compiled and the resulting class files archived into a "wvcm.jar" file, located at "dist/lib/wvcm.jar". Javadoc documentation has been generated for it, located at "dist/docs"; this page you are now reading is the Overview document for that generated Javadoc.

For details on how to load the project into Eclipse and/or recompile the sources and the Javadoc, read below.

Setup

The specification should be originally distributed as a zip file, with the top level of the file being a directory named "jsr147". Extract this to a place of your choosing, e.g. "C:\" to create the "jsr147" subdirectory. This directory is a valid Eclipse project for Eclipse versions 3.1 and higher. Eclipse is not required, however, since the directory also contains an Ant build script "build.xml". The source may be recompiled, either through Eclipse or through Ant.

The instructions assume you have installed any needed tools, such as Eclipse, Ant or the JDK. Only JDK is required. Either Eclipse or Ant (or both) is highly recommended. However, it is possible to get by without Ant and Eclipse if you want to do all the setup and compilation yourself.

Ant details and installation instructions can be found at the Apache Ant Project. The build scripts were developed with Ant 1.6.5.

Eclipse details and installation instructions can be found at the Eclipse web site. Eclipse 3.1.x was used for development of the WVCM reference implementation and the TCK.

The specification has been developed with Sun's Java 1.4.2 JDK.

Eclipse

To use Eclipse, run Eclipse and import the "jsr147" project. This is typically done by selecting menu item "File->Import" and selecting "Existing Projects into Workspace". Menus and dialogs vary slightly depending on Eclipse version.

Once imported, the Java source should automatically compile without error. The result of the compilation will be Java class files in a "bin" directory beside the "src" directory.

Eclipse Ant build

Note that the distribution zip file is shipped with the jar file and Javadoc already built. You are free to rebuild them, though. The "build.xml" Ant script can be used from within Eclipse, via Eclipse's "external tools" feature. This does not require a separate install of Ant nor does it require setting up any environment variables to find Ant. Before doing this, follow the previous instructions for setting up Eclipse.

The Ant script is capable of the following:

Select the "jsr147" project's "build.xml" file within the Project Explorer view. Select menu item "Run->External Tools->Run As->Ant Build".

When you run this script, it'll run the default "jar" target, resulting in a "wvcm.jar" file at "dist/lib/wvcm.jar". To make it do something else such as generate Javadoc, edit the configuration and specify "doc" for its target. Or, specify "all" to make it do everything.

Ant command line

Whether or not you have Eclipse installed and are using it, you may also build the sources using Ant from the command line. This option is good for automated builds or for when Eclipse is otherwise not in use.

To use Ant, you will of course need Ant. If you already have Eclipse installed, then you probably already have Ant; it is included as an Eclipse plugin and is typically at C:\eclipse\plugins\org.apache.ant_1.6.5.

Briefly, you can set up a script on Windows to use Ant like this:

set ANT_HOME=C:\apache-ant-1.6.5
set JAVA_HOME=C:\java142
set path=%ANT_HOME%\bin;%JAVA_HOME%\bin;%path%

And on Unix within the CSH or TCSH shells, like this:

setenv ANT_HOME ~/apache-ant-1.6.5
setenv JAVA_HOME ~/jdk142
setenv PATH $ANT_HOME/bin:$JAVA_HOME/bin:$PATH

Modify the paths appropriately to point to where you have installed Ant and the Java JDK.

Once you have Ant configured properly, change directory to the "jsr147" project. Then, type "ant -p" to see what choices you have available. The default target just compiles the source and creates jar files. You may also choose to generate Javadoc. The "all" target builds everything.

Creating a WVCM Implementation

You may create a WVCM implementation that conforms to the WVCM specification.

This will require implementing the WVCM interfaces, so these interfaces will need to be in your classpath. The interfaces are located in the wvcm.jar file that this project builds. If you are developing your implementation within Eclipse, you can have the Eclipse build path preferences for a project point to this wvcm.jar file. If building from Ant, do whatever is necessary within your implementation's build.xml file to add wvcm.jar to the classpath of any Ant task that makes use of a classpath.

What Next?

If you are writing your own WVCM implementation, you will want to make use of the JSR-147 TCK to test your implementation for compliance. See the separately distributed "jsr147_tck" project for details on how to invoke the TCK against your implementation.

You may also examine, run and test the WVCM Reference Implemenation (RI) to learn more about the functionality that is expected by the WVCM specification. The RI is the separately distributed "jsr147_ri" project. The TCK can also be used to test the RI (and does so by default). And, the source code for the TCK's unit tests can also be useful in understanding how a WVCM implementation is supposed to function.