This post explains how the WorkItem Command Line works. It explains its structure and the main classes. This should allow users to extend the capabilities the code and add new commands or extend the current commands.
Please note, as this is work in progress, things might change slightly in future versions, however the general structure should persist.
Latest Version
See A RTC WorkItem Command Line Version 3.0 for the latest version.
Related posts
License
The post contains published code, so our lawyers reminded me to state that the code in this post is derived from examples from Jazz.net as well as the RTC SDK. The usage of code from that example source code is governed by this license. Therefore this code is governed by this license. I found a section relevant to source code at the and of the license.
Please also remember, as stated in the disclaimer, that this code comes with the usual lack of promise or guarantee.
On the other hand, you have the code and are able to add your own code to it. It would be nice to know what you did and how, if you do so.
Just Starting With Extending RTC?
If you just get started with extending Rational Team Concert, or create API based automation, start with the post Learning To Fly: Getting Started with the RTC Java API’s and follow the linked resources.
You should be able to use the code attached to this post in the development environment you set up in the Rational Team Concert Extensions Workshop and get your own extensions or automation working there as well.
Importing The Project
Download the code from the post A RTC WorkItem Command Line Version 2. The file with the source code is named WorkItemCommandLine_Project-Vx-YYYYMMDD.zip. The x represents the version number and is followed by the date it was created. The file is an exported Eclipse project.
The project expects the Eclipse workspace to be set up as described in the posts Setting up Rational Team Concert for API Development. It requires the SDK to be set up as well as the Plain Java Client Libraries. The SDK is needed, because the project is a Plugin Project. this is done to be able to use the Eclipse Plugin Development Environment (PDE) to look at the API source code. The Plain Java Client Libraries are needed to run the code a Java application.
Use the Eclipse import File>Import. In the wizard window select “Existing Projects into Workspace” in the section General. Click Next and chose the option “Select archive file”, browse to the file you downloaded and select it. Make sure you see the project com.ibm.js.team.workitem.commandline selected and press Finish to start the import.
After the import you should see the project in your workspace. You should see no errors in the project. If you see errors, the most likely reasons for that are:
- The SDK is not set up correctly and the classes can not be resolved
- The SDK version is prior to RTC 4.0.1
- The Plain Java Client Libraries are not installed or the User Library has a different name
The first two will show in the plugin.xml and the manifest file. Setup the SDK correctly, or change the minimal versions needed in the dependencies.
The third will show as an error in the the build path. Define a user library named PlainJavaApi as explained in Setting up Rational Team Concert for API Development or remove the existing user library entry and add you own. Make sure the dependency order of SDK and user library are correct as explained in Understanding and Using the RTC Java Client API.
In case you have other errors you should search the internet for a solution.
Explore the Project
You can now explore the project. The folder structure is shown below.
There are the following files and folders
- src – contains the source code files.
- build – contains a jardesc file to build a jar file for packaging
- Launches – contains launch files used for testing
- License – contains the license files
- scripts – contains the script files used to start WCL, as well as a file with help information
- the root contains a readme file, explaining how to build a releasable version of WCL, scripts used to start WCL in the development setup and a test file for upload attachment tests.
The Source Files
The image below shows the structure of the source code.
The package com.ibm.js.team.workitem.commandline contains the class WirkitemCommandLine, which has the main method to call WCL. The class OperationResult is used to pass result information. This is necessary, since the code could run in RMI mode and the output needs to be transferred to the RMI client. This class needs to support serializing in order to pass the result back. IWorkItemCommandLineConstants contains various constants used by WCL.
The package com.ibm.js.team.workitem.commandline.commands contains the classes that implement the currently available commands. CreateWorkItemCommand creates a work item of a specific type in a specific project area and sets the attributes as provided. PrintTypeAttributesCommand prints the attributes of a specific work item type in a specific project area. UpdateWorkItemCommand finds a work item and updates its attribute values.
The package com.ibm.js.team.workitem.commandline.framework contains a basic framework that is used by commands that are implemented in WCL. The main class requires the interface IWorkItemCommand to run the command. I ended up using this kind of framework, because all commands required some kind of parameters. The command should be able to define the parameters needed. The commands also require to do error handling. To interact with the RTC repository commands also need to login. The framework handles all the common activities and allows to create new commands without having to redevelop all this.
The class AbstractCommand implements the interface IWorkItemCommand and leaves some methods abstract that extending classes need to implement.
The class AbstractTeamRepositoryCommand adds a login to the team repository and the class AbstractWorkItemModificationCommand adds a WorkItemOperation to perform the changes to the work item. WorkItemCommandLineException is the exception class that is used to wrap other exceptions and thrown in case of unrecoverable errors.
The package com.ibm.js.team.workitem.commandline.helper contains helper classes. The class DevelopmentLineHelper is from another blog post Handling Iterations – Automation for the “Planned For” Attribute. It allows to find development lines and iterations on a development line. WorkItemHelper implements modifying work item attribute modification. Most of the RTC API related code is in there. WorkItemTypeHelper helps with printing the attribute information for a work item type.
The package com.ibm.js.team.workitem.commandline.parameter contains classes that implement all the parameter handling needed. The class Parameter is used to describe a parameter, if it is required, if it was already consumed, if it is a switch and the like. ParameterIDMapper defines a list of aliases that can be used instead of an attribute ID. You can add your own aliases that can be used for convenience. ParameterList represents a list of parameters. The class ParameterManager manages a parameter list and provides the central access to the parameters. The class ParameterParser is used to parse the parameters passed from outside and store them in a parameter list.
The package com.ibm.js.team.workitem.commandline.remote contains the remote interface IRemoteWorkItemOperationCall that is used in RMI mode.
The package com.ibm.js.team.workitem.commandline.utils contains some utility classes (providing static methods as interfaces). The class ProcessAreaUtil allows to search process areas. The class SimpleDateFormatUtil helps with conversion of timstamps from and to a string representation.
How The Code Works
The main method of the WorkitemCommandLine basically instantiates the class and then calls the method run(). We will look at that method later.
/**
* The main entry point into the work item commandline
*
* @param args
* - the arguments to be used by the commandline
* @throws RemoteException
*/
public static void main(String[] args) {
OperationResult result = new OperationResult();
System.out.println("WorkItemCommandLine Version "
+ IWorkItemCommandLineConstants.VERSIONINFO + "\n");
WorkitemCommandLine commandline;
try {
commandline = new WorkitemCommandLine();
result = commandline.run(args);
} catch (RemoteException e) {
result.appendResultString("RemoteException: " + e.getMessage());
result.appendResultString(e.getStackTrace().toString());
}
System.out.println(result.getResultString());
if (TeamPlatform.isStarted()) {
TeamPlatform.shutdown();
}
if (!isServer()) {
// If I am not in server mode, I need to exit and return success or
// failure
if (result.isSuccess()) {
// If the operation was unsuccessful, terminate with an error
System.exit(0);
}
System.exit(1);
}
}
The operation run() will return a result if it terminates. The information in this result is used to create the exit code to terminate the call.
In case this WCL is started as RMI server, the process can not terminate with System.exit(). It needs to persist registered to the RMI registry. The static method isServer() is used to communicate this information.
The method run() parses the parameters passed. It then checks if it is supposed to run as RMI server or as RMI client. If that is the case it starts the RMI server mode or, uses RMI to call the server as client. If this is a normal run, it calls runCommands() with the parameters that have been parsed.
If started as RMI server, the method startRMIServer() is used to initialize RMI and to register the class to the registry. The method runOperation() is basically the interface that is used to run the command on the server and is called by RMI clients. The method runOperation() parses the parameters and calls runCommands() as well.
The method runCommands() really executes the command requested in the parameters. The first steps it does is to initialize the data it needs. Then it runs addSupportedCommands() to add the commands that are available.
/**
* Add the supported commands. If introducing a new command, add it here.
*
* @param parameterManager
*/
private void addSupportedCommands(ParameterManager parameterManager) {
addSupportedCommand(new PrintTypeAttributesCommand(
new ParameterManager(parameterManager.getArguments())));
addSupportedCommand(new CreateWorkItemCommand(new ParameterManager(
parameterManager.getArguments())));
addSupportedCommand(new UpdateWorkItemCommand(new ParameterManager(
parameterManager.getArguments())));
}
Now the method runCommands() gets the command from the Parameter Manager. If there is a command string, it gets the class that implements the command. If there is a command registered for this command string, runCommand() calls the command to validate if the required parameters for it to run are available. If this is the case, runCommand() calls the command and returns the result back.
In all other cases runCommand() prepares a result error and also uses the method helpGeneralUsage() to print a help for the command.
Adding Commands to the WorkItemCommandLine
It is easy to add new commands to the WorkitemCommandLine. You need to implement a new command and add a new entry for it in the method addSupportedCommands().
How Commands Work
Commands have to implement the IWorkItemCommand interface. You should pick one of the abstract classes in the framework and extend them. This makes sure the basic workflow will work. If you command needs to create or modify a work item based on property values, use the class AbstractWorkItemModificationCommand. If you only need to have a repository connection, use the class AbstractTeamRepositoryCommand. In both cases all you need to do really is to override and implement the methods required. There are three things that need to be there.
In the method getCommandName() you need to return the name of the command you implement.
@Override
public String getCommandName() {
return IWorkItemCommandLineConstants.COMMAND_CREATE;
}
If your command needs additional parameters, override the method setRequiredParameters(). Call the method of the superclass to have it add its required parameters and add your parameters. Here is an example
/*
* (non-Javadoc)
*
* @see com.ibm.js.team.workitem.commandline.framework.
* AbstractWorkItemCommandLineCommand#setRequiredParameters()
*/
public void setRequiredParameters() {
super.setRequiredParameters();
// Add the parameters required to perform the operation
// getParameterManager().syntaxCommand()
getParameterManager()
.syntaxAddRequiredParameter(
IWorkItemCommandLineConstants.PARAMETER_PROJECT_AREA_NAME_PROPERTY,
IWorkItemCommandLineConstants.PARAMETER_PROJECT_AREA_NAME_PROPERTY_EXAMPLE);
getParameterManager()
.syntaxAddRequiredParameter(
IWorkItemCommandLineConstants.PARAMETER_WORKITEM_TYPE_PROPERTY,
IWorkItemCommandLineConstants.PARAMETER_WORKITEM_TYPE_PROPERTY_EXAMPLE);
getParameterManager().syntaxAddSwitch(
IWorkItemCommandLineConstants.SWITCH_IGNOREERRORS);
getParameterManager().syntaxAddSwitch(
IWorkItemCommandLineConstants.SWITCH_ENABLE_DELETE_ATTACHMENTS);
getParameterManager().syntaxAddSwitch(
IWorkItemCommandLineConstants.SWITCH_ENABLE_DELETE_APPROVALS);
}
Parameters added with syntaxAddRequiredParameter() will be assumed to be required. If they are not available the command line will show an error during the parameter validation. The error message is automatically created from the parameter information provided here.
Finally you have to override and implement the method process() to implement the command.
/*
* (non-Javadoc)
*
* @see com.ibm.js.team.workitem.commandline.framework.
* AbstractWorkItemCommandLineCommand#process()
*/
@Override
public OperationResult process() throws TeamRepositoryException {
// Get the parameters such as project area name and Attribute Type and
// run the operation
String projectAreaName = getParameterManager()
.consumeParameter(
IWorkItemCommandLineConstants.PARAMETER_PROJECT_AREA_NAME_PROPERTY)
.trim();
// Find the project area
IProjectArea projectArea = ProcessAreaUtil.findProjectArea(
projectAreaName, getProcessClientService(), getMonitor());
if (projectArea == null) {
throw new WorkItemCommandLineException("Project Area not found: "
+ projectAreaName);
}
String workItemTypeID = getParameterManager().consumeParameter(
IWorkItemCommandLineConstants.PARAMETER_WORKITEM_TYPE_PROPERTY)
.trim();
// Find the work item type
IWorkItemType workItemType = WorkItemHelper.findWorkItemType(
workItemTypeID, projectArea.getProjectArea(),
getWorkItemCommon(), getMonitor());
// Create the work item
createWorkItem(workItemType);
return this.getResult();
}
To complete the code of this command, here is the method that creates the work item and uses the parameters to update the attributes.
/**
* Create the work item and set the required attribute values.
*
* @param workItemType
* @return
* @throws TeamRepositoryException
*/
private boolean createWorkItem(IWorkItemType workItemType)
throws TeamRepositoryException {
ModifyWorkItem operation = new ModifyWorkItem("Creating Work Item");
this.setIgnoreErrors(getParameterManager().hasSwitch(
IWorkItemCommandLineConstants.SWITCH_IGNOREERRORS));
IWorkItemHandle handle;
try {
handle = operation.run(workItemType, getMonitor());
} catch (TeamOperationCanceledException e) {
throw new WorkItemCommandLineException("Work item not created. "
+ e.getMessage(), e);
}
if (handle == null) {
throw new WorkItemCommandLineException(
"Work item not created, cause unknown.");
} else {
IWorkItem workItem = getAuditableCommon().resolveAuditable(handle,
IWorkItem.SMALL_PROFILE, getMonitor());
this.appendResultString("Created work item " + workItem.getId()
+ ".");
this.setSuccess();
}
return true;
}
In case you wonder where the actual work gets done – I wondered looking at it. The line
handle = operation.run(workItemType, getMonitor());
does all the work. By calling it this way, the WorkItemOperation creates the work item. The operation is based upon the code in the class AbstractWorkItemModificationCommand.
In that class, the execute() method is overwritten with this code:
/*
* This is run by the framework
*
* (non-Javadoc)
*
* @see
* com.ibm.team.workitem.client.WorkItemOperation#execute(com.ibm.team
* .workitem.client.WorkItemWorkingCopy,
* org.eclipse.core.runtime.IProgressMonitor)
*/
@Override
protected void execute(WorkItemWorkingCopy workingCopy,
IProgressMonitor monitor) throws TeamRepositoryException,
RuntimeException {
// run the special method in the execute.
// This is called by the framework.
update(workingCopy);
}
The call to the method update() does the real work. It walks through all the unconsumed parameters in the parameter list – which should contain the attributes and values to be set and applies the changes to the work item.
/**
* This operation does the main task of updating the work item
*
* @param workingCopy
* the workingcopy of the workitem to be updated.
*
* @throws RuntimeException
* @throws TeamRepositoryException
*/
public void update(WorkItemWorkingCopy workingCopy)
throws RuntimeException, TeamRepositoryException {
ParameterList arguments = getParameterManager().getArguments();
// We use a WorkItemHelper to do the real work
WorkItemHelper workItemHelper = new WorkItemHelper(workingCopy,
arguments, getMonitor());
// Run through all properties not yet consumed and try to set the values
// as provide
for (Parameter parameter : arguments) {
if (!(parameter.isConsumed() || parameter.isSwitch() || parameter
.isCommand())) {
// Get the property ID
String propertyName = parameter.getName();
// Get the property value
String propertyValue = parameter.getValue();
try {
workItemHelper.updateProperty(propertyName, propertyValue);
} catch (WorkItemCommandLineException e) {
if (this.isIgnoreErrors()) {
this.appendResultString("Exception! " + e.getMessage());
this.appendResultString("Ignored....... ");
} else {
throw e;
}
} catch (RuntimeException e) {
this.appendResultString("Runtime Exception: Property "
+ propertyName + " Value " + propertyValue + " \n"
+ e.getMessage());
throw e;
} catch (IOException e) {
this.appendResultString("IO Exception: Property "
+ propertyName + " Value " + propertyValue + " \n"
+ e.getMessage());
throw new RuntimeException(e.getMessage(), e);
}
}
}
}
The Class WorkItemHelper
This class is basically doing all the work related to modifying work item data. The helper needs to be instantiated. Then the method updateProperty() can be called.
public void updateProperty(String propertyID, String value)
throws TeamRepositoryException, WorkItemCommandLineException,
IOException {
.
.
.
}
The method checks if the attribute is one of the special ones like the type, or complex attributes such as workflow or state changes, approvals or other pseudo attribute ID’s and handles these if detected. Otherwise it calls the method updateGeneralAttribute() to handle the update.
private void updateGeneralAttribute(ParameterValue parameter,
List exceptions) throws TeamRepositoryException,
WorkItemCommandLineException {
.
.
.
}
The method updateGeneralAttribute() checks if this attribute is actually available on the work item. If so it calls getRepresentation() to get a value that can be set for the attribute.
private Object getRepresentation(ParameterValue parameter,
List exceptions) throws TeamRepositoryException,
WorkItemCommandLineException {
.
.
.
}
The method getRepresentation() basically is a huge list of checks to narrow down what type the attribute to modify is. If the type is narrowed down, it calls a related methods to parse the input data and to create a value for the attribute, that can be returned and set.
Summary
This post explains how the code works and how you can utilize it to implement your own commands. As always, I hope that helps someone out there.
While creating this post, I realized, that I should have named some of the classes differently. This framework is not only good for a work item command line. This code could be used for any command line. Maybe I will adjust this a bit in later versions, should time permit.
rsjazz 