1) Prepare a java file with the following implementation of CustomTrigger class

A constructor with the following signatures
( I.e. public CustomTrigger (com.starteam.File file, com.starteam.Label label, com.starteam.File.Operation operation). The first param is the target file of the operation, the second param label is the target label that will be detached or attached where applicable and operation is one of the four supported operations: check-in, check-out, attach label and detach label)

2 accessors with the following names and signatures
(I.e. public boolean cancel () - Basically, you can place whatever checks in this method that you will need to perform before committing to check-in,check-out, attach and detach of a label. Returning true will cancel the entire current operation without a commit. Return false if everything is alright.

and

public String getDescription () - This method returns a string which is used for different purposes for different operations.

For attaching, detaching of labels and checking out, the string that is returned will simply appear in a informational message box.

For checking in of files, the string returned in this method will appear in the subsequent File Comment (check-in reason) dialog box.

You can find a sample of the CustomTrigger java file example that will be used in this article here: 1212.CustomTrigger.zip

The implementation here is simple:

i) In the cancel method where checks can be performed on the files, there is a dialog box (I.e. JOptionPane) which will pop up confirming if the user wishes to commit to the operation. If the user clicks Yes, the cancel method will return false and the operation will carry on. If not, the operation will cease.

ii) In the getDescription method, the string returned is simply the target file name and the file operation. If you look at the conditions, you should be able to see the corresponding IDs to each operation. (I.e. check in being ID 0, check out being ID 1, attach label being ID 2 and detach label being ID 3).

2) Once the CustomTrigger class has been implemented, it is time to compile the java file into a jar file. You will need to name the jar file custom.trigger.jar.

While there are many Java sources online to show you how to do this, below are the commands you can run to do so. Please take note of the first command where there is a dependency to the starteam160.jar if you are using StarTeam v16.0 which is the latest version at the time of this writing.

You can find the starteam160.jar under C:\Program Files\Micro Focus\StarTeam SDK 16.0\lib where you have installed the StarTeam SDK 16.0.

javac -cp ".;starteam160.jar" CustomTrigger.java

echo Main-Class: CustomTrigger >manifest.txt

jar cvfm Custom.Trigger.jar manifest.txt *.class

You can find a batch script sample that can used to perform the compilation automatically in the archive file CustomTrigger.zip provided above.

In case you do not have a copy of starteam160.jar, you can find it in the CustomTrigger.zip above.

Simply create a new folder, copy the compile.bat, the CustomTrigger.java and the starteam160.jar files into that folder, open up command prompt, navigate to that folder and simply run compile. The custom.trigger.jar will be generated in the same folder.

3) Once you have the custom.trigger.jar file generated, you will need to add the jar file to the StarFlow Extensions project, root view and root folder of the server configuration where you wish the custom trigger to be fired. If you are using StarTeam v16.0, the ST server administrator basically has a button "load StarFlow Extensions project" that allows you to do that via a mouse click.

Simply check-out the StarFlow Extensions project and add the jar file to the root folder (I.e. StarFlow Extensions) of the work-space. Then add the jar file. You are done. (If you have problems deploying the jar file where you get exceptions when the custom trigger is fired up, you can make amendements to the CustomTrigger.java, run the compilation again, replace the jar file in the workspace and check-in again)

4) To test if this is working, create a new project or just open an existing project in the same server configuration. For a new project, simply create a few files and folders to populate the work-space here. Also create a custom label as we will be trying out the attaching and detaching of the label.

To test out the scenario for attaching labels, simply select a file, select the Label tab, right click on a branch revision,select Attach.. from the context menu, select the custom label you have created and click OK. You should see the dialog box which we have implemented in the CustomTrigger.java which asks the user if they really want to complete the operation. This is the behavior exhibited from the cancel method mentioned earlier.

Clicking Yes moves us to the next dialog box where the message is actually the string that is returned from the getDescription method (i.e. name of the target file and operation on it). As highlighted earlier, the cancel method is called and then the getDescription method next. 

If you select No instead, you will still see the same dialog box and an additional dialog box which states that the operation is cancelled will appear after you close the dialog box which displays the file name and operation.

The behaviors for detaching and checking out of the files are the same.

For checking in of files, it is imperative that in the check-in dialog box, the option checkbox "Prompt for a comment of launch a custom trigger for a check-in reason for each file" is checked or the custom trigger will not be fired.

Once you have checked the checkbox, you will see the same dialog box defined in cancel method and clicking Yes will show you the File comment dialog box with the string returned from getDescription appearing in the Comment text box.

Click Yes and the file will be checked in and if you look at the comments (I.e. Properties) of the version of that file, the comment is set exactly the same.

4) You are pretty much equipped to start customizing your own implementation for the cancel method to impose your own checks like coding standards before checking-in and check if there are any code reviews before checking out instead of printing out output on dialog boxes.

Please take note that custom triggers do work on multiple files check-in and check-out as well. The custom trigger simply works on each file one at a time.

If you wish to learn more about the Java classes used in the StarTeam Java SDK like File.Operation, you can refer to the latest StarTeam v16.0 Java Doc.

Happy customizing!