Organizations might be interested in enforcing naming conventions for streams or make sure that stream names must be unique. This post shows some simple example advisor that check for a naming convention and make sure the stream name is unique.
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. Enjoy!
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 following code in this environment and get your own automation or extension working.
The example in this blog post shows RTC Server and Common API.
Compatibility
This code has been used with RTC 6.0 and is prepared to be used with RTC 6.0.x with no changes and it is pretty safe to assume, that the code will work with newer versions of RTC. It should run with any version that provides the operation ID.
The code in this post uses common and server libraries/services that are available in the RTC Server SDK.
Download
The code can be downloaded from here. Please note, there might be restrictions to access Dropbox and therefore the code in your company or download location.
Solution
Since some versions of RTC the operation ID com.ibm.team.scm.server.modifyStream has been made available. The operation allows to write RTC advisors (pre-conditions) and participants (follow up actions) that trigger on saving of a stream. The data that is made available in these operations allows to detect a variety of change types including a rename of a stream.
RTC (version 6.x) ships the following out of the box preconditions for this operation ID:
- Ensure that snapshot names are unique for streams in the process area.
- Prevent Adding Component to Stream When Component and Stream Owners are Different.
- Prevent Adding User Owned Component
- Restrict Stream Visibility to be set to Public
The implementing classes are shipped with the SDK
- com.ibm.team.scm.service.internal.process.advisors.UniqueBaselineSetNameAdvisor
- com.ibm.team.scm.service.internal.process.advisors.StreamAddComponentAdvisor
- com.ibm.team.scm.service.internal.process.advisors.StreamAddUserOwnedComponentAdvisor
- com.ibm.team.scm.service.internal.process.advisors.StreamVisibilityAdvisor
Looking at the source code can be a great inspiration.
This post shows two advisors
- StreamNamingPatternAdvisor
- UniqueStreamNameAdvisor
StreamNamingPatternAdvisor checks for a simple naming convention and prevents creation or renaming of streams that violate the naming convention.
UniqueStreamNameAdvisor checks if the name of the stream is already used by another stream and prevents saving the stream if that is the case. Please note, the operation com.ibm.team.scm.server.modifyStream does not trigger if someone creates or saves a user repository workspace. This means it is not possible to provide this capability for them.
General Approach
The operation ID provides a special interface IModifyStreamOperationData which makes the type of change and the related data available.
The code for the advisors first checks if the operation data provided is of the type IModifyStreamOperationData.If not, the operation terminates. If so, it casts to be able to use the interface to access the change details. If the data indicates anything other than a IModifyStreamOperationData.CHANGES, the advisor terminates.
IModifyStreamOperationData opData = (IModifyStreamOperationData) operationData;
if (!opData.isOperationType(IModifyStreamOperationData.CHANGES)) {
// Nothing to do
return;
}
If the operation is for such a change, the operation data can contain several different changes. So the code gets all the change ID’s for the changes in a set. The code then iterates the change ID’s and gets the change usinf the ID as IStreamChange. This interface allows to get more information, for example the identifier for the operation. In our case, if it is a name change IModifyStreamOperationData.NAME, the advisors are responsible to deal with it.
// Get the set of change IDs and look through the changes
Set changeIDs = opData.getChangeIds();
for (String changeID : changeIDs) {
IStreamChange change = opData.getChange(changeID);
// Is this a stream name change?
if (change.getIdentifier().equals(IModifyStreamOperationData.NAME)){
........
The interface IStreamChange does not provide a whole lot of data to find out what actually happened. But the identifier gives a good idea. The IStreamChange is implemented by several interfaces that provide more information.
- com.ibm.team.scm.common.process.IStreamComponentChanges is an interface to describe component changes on the stream
- com.ibm.team.scm.common.process.IStreamFlowChange is an interface to describe flow target related changes on the stream
- com.ibm.team.scm.common.process.IStreamPropertyChange is an interface to describe property changes such as a name change on the stream
The code can now cast to the specific interface IStreamPropertyChange and access the current and the new value of the property change. These values are the current name and the new name of the stream.
With the new name the code can run a basic validation. If the validation succeeds, the advisor terminates, otherwise it complains and fails the advisor.
The code below shows the whole advisor implementation. In this example the code looks for a very simple prefix ‘TEST_’ on the stream name. If the prefix is available it succeeds, it fails otherwise. This validation can be replaced by a more complex and potentially configurable method.
/*******************************************************************************
* Licensed Materials - Property of IBM
* (c) Copyright IBM Corporation 2017. All Rights Reserved.
*
* Note to U.S. Government Users Restricted Rights: Use, duplication or
* disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
*******************************************************************************/
package com.ibm.js.scm.naming.advisor.service;
import java.util.Set;
import org.eclipse.core.runtime.IProgressMonitor;
import com.ibm.team.process.common.IProcessConfigurationElement;
import com.ibm.team.process.common.advice.AdvisableOperation;
import com.ibm.team.process.common.advice.IAdvisorInfo;
import com.ibm.team.process.common.advice.IAdvisorInfoCollector;
import com.ibm.team.process.common.advice.runtime.IOperationAdvisor;
import com.ibm.team.repository.common.TeamRepositoryException;
import com.ibm.team.scm.common.process.IModifyStreamOperationData;
import com.ibm.team.scm.common.process.IStreamChange;
import com.ibm.team.scm.common.process.IStreamPropertyChange;
import com.ibm.team.scm.service.internal.AbstractScmService;
@SuppressWarnings("restriction")
/**
* This advisor tests the name of a stream against a naming convention pattern.
* If the stream name does not match the pattern, the stream can not be saved.
*
* Note that this extension point does not get any change events for repository workspaces. It only works for streams.
*
*
* There are several examples for extensions that are shipped with the product that can be looked into in the SDK.
* @see com.ibm.team.scm.service.internal.process.advisors.UniqueBaselineSetNameAdvisor
* @see com.ibm.team.scm.service.internal.process.advisors.StreamVisibilityAdvisor
* @see com.ibm.team.scm.service.internal.process.advisors.StreamAddComponentAdvisor
* @see com.ibm.team.scm.service.internal.process.advisors.StreamAddUserOwnedComponentAdvisor
*
*/
public class StreamNamingPatternAdvisor extends AbstractScmService implements
IOperationAdvisor {
public static final String REQUIRED_PREFIX = "TEST_";
public static final String STREAM_NAMING_ADVISOR = "com.ibm.js.scm.naming.advisor.service.streamNaming";
@Override
public void run(AdvisableOperation operation,
IProcessConfigurationElement advisorConfiguration,
IAdvisorInfoCollector collector, IProgressMonitor monitor)
throws TeamRepositoryException {
Object operationData = operation.getOperationData();
if (!(operationData instanceof IModifyStreamOperationData)) {
// There are some stream modify operations that are not process
// enabled so they do not provide any data.
return;
}
// com.ibm.team.scm.server.modifyStream is only called for streams.
// Saving a repository workspace (which is really like a stream) does
// not trigger the extension point.
// This especially implies that it is not possible to test for unique
// names across streams and workspaces. It is possible to
IModifyStreamOperationData opData = (IModifyStreamOperationData) operationData;
if (!opData.isOperationType(IModifyStreamOperationData.CHANGES)) {
// Nothing to do
return;
}
// Get the set of change IDs and look through the changes
Set changeIDs = opData.getChangeIds();
for (String changeID : changeIDs) {
IStreamChange change = opData.getChange(changeID);
// Is this a stream name change?
if (change.getIdentifier().equals(IModifyStreamOperationData.NAME)) {
/***
* Get the change details based on the change we identified
*
* The supported types of changes for this extension point are
*
* @see com.ibm.team.scm.common.process.IStreamPropertyChange
* @see com.ibm.team.scm.common.process.IStreamComponentChanges
* @see com.ibm.team.scm.common.process.IStreamFlowChange
*
* A name change is stored as IStreamPropertyChange
*/
if (change instanceof IStreamPropertyChange) {
IStreamPropertyChange streamPropertyChange = (IStreamPropertyChange) change;
String newName = streamPropertyChange.getNewValue()
.toString();
if (validateName(newName)) {
// We are fine
return;
}
String description = "The stream name violates the naming conventions stream name must have prefix '"
+ REQUIRED_PREFIX + "'!";
String summary = description;
IAdvisorInfo info = collector.createProblemInfo(summary,
description, STREAM_NAMING_ADVISOR);//$NON-NLS-1$
collector.addInfo(info);
}
}
}
}
/**
* Validate the name against the convention
*
* @param name
* @return
*/
private boolean validateName(String name) {
// Implement your own naming convention here
if (name.startsWith(REQUIRED_PREFIX)) {
return true;
}
return false;
}
}
The UniqueStreamNameAdvisor only replaces the validation with a more complex one querying the SCM system for streams with a given name.
The code creates workspace search criteria to search for a stream, that happens to have the same name as the new name for this stream will be. If so, it fails. The search is limited to streams, because it is not possible to do this check for repository workspaces and a conflict would be hard to handle.
/**
* Validate the name against the convention a stream must have a unique name
*
* @param name
* @return
* @throws TeamRepositoryException
*/
private boolean validateName(String name) throws TeamRepositoryException {
// Get the query service and set criteria
IScmQueryService queryService = getService(IScmQueryService.class);
final IWorkspaceSearchCriteria criteria = IWorkspaceSearchCriteria.FACTORY
.newInstance();
criteria.setExactName(name); // Look for the same name
// Only for streams, we can not prevent creation of workspaces with the
// same name either and a user could create a workspace with the same
// name and prevent us from saving the stream later.
criteria.setKind(IWorkspaceSearchCriteria.STREAMS);
// We only have to find one other
ItemQueryResult result = queryService.findWorkspaces(criteria, 1, null);
if (!result.getItemHandles().isEmpty()) {
return false;
}
return true;
}
Consolidation
It is relatively obvious and straight forward to consider refactoring the solution shown here. Create an abstract class that contains all the shared code of both classes, with an abstract method validateName(). Create implementations providing the implementation for the method validateName() and provide these implementation classes in the plugin.xml. That way it is simple to provide new versions for various naming conventions.
Code Structure
The code structure follows the general approach that has been used in this blog for quite some time now. The code comes in the following Eclipse projects used for the purpose explained below.
com.ibm.js.scm.naming.advisor.common is the project that defines the jazz component to be used by this extension. It is in a separate project to allow to use it in case of implementing an aspect editor.
com.ibm.js.scm.naming.advisor.launches is a project that contains the launches that can be used to debug the extension with Jetty.
com.ibm.js.scm.naming.advisor.service is the project that contains the server side extension code.
com.ibm.js.scm.naming.advisor.service.feature defines is the feature for the server side deployment of the extension.
com.ibm.js.scm.naming.advisor.service.updatesite contains the update site to build the server side extension.
com.ibm.js.scm.naming.advisor.service.serverdeploy contains the provision profile as well as the folder structure needed for the final deployment. To prepare deployment Build the update site and copy the plugins and feature folder into the js_scm_naming_advisor folder. To deploy copy the provision_profiles and the sites folder with all their contents into the server/conf/ccm folder of the RTC server.
Configuring the precondition
When running the custom advisor in Jetty or finally deployed the advisor can be configured as usual.
If configured, the advisors prevent saving streams that do not conform to the specific naming condition. The advisor displays the problem like below.
Summary
As always I hope this helps someone out there with running RTC. Please keep in mind that this is as usual a very basic example with no or very limited testing and error handling. Please see the links in the getting started section for more examples, especially if you are just getting started.
rsjazz 