Configuring Eclipse to create StarTeam Custom APE (Alternate Property Editor)
This wiki is simply an overview of adding the required StarTeam resources to an already existing Eclipse Java project which is to be used as a Custom APE (Alternate Property Editor) within the StarTeam Cross-Platform Client.
In order to design & code a Custom APE, there are several prerequisites that you first must adhere to.
You must have installed StarFlow Extensions on the machine where you will be coding/designing the form, ideally on the machine where you have Eclipse installed.
Failing that you must have a local copy of the required StarFlow Extensions JAR files and include these in your Eclipse ‘build’ path.
Details of the files required will be covered later in this wiki.
You will also need to have the relevant version of the StarTeam SDK installed on the same machine.
Note: Source code for sample ‘Custom Forms’ is available in the ‘Samples’ folder of the StarFlow Extensions install.
How can a Custom APE be used with StarTeam and what is involved?
The StarTeam CPC uses a single Java Archive (JAR) file which is built using a minimum of 3 essential Java files (extra files can be added if you wish to enhance / extend functionality – however, this will not be discussed in this Wiki at this time).
You will also need to configure the build path in Eclipse to reference JAR files / libraries from the StarFlow Extensions before building the Custom APE JAR file.
Required Java Files:
Required XML File:
Required JAR Files:
Note: Please ensure that you use the corresponding StarTeam SDK jar files for the version of StarTeam Server currently in use. For StarTeam 2009 and earlier, the bridging jar will not be required.
The above JAR files are only required to be referenced in the Development IDE. It should not be necessary to include these in the final packaged/exported Custom APE JAR file.
Reason for the .propertyeditor.xml File:
The StarTeam Client obtains the details about the resources to load and run from the .propertyeditor.xml file.
For example, if you use the APE “Locator ChangeRequest”, the file ChangeRequest.propertyeditor.xml is read by the client to determine which resources are deployed for the APE.
Below is a copy of the sample ChangeRequest.propertyeditor.xml file included with the StarFlow Extensions samples;
<?xml version="1.0" encoding="UTF-8"?>
<propertyeditor name="Change Request Editor" version="1.1">
This file must be checked-in to StarFlow Extensions Projects alongside the create Custom APE JAR file.
Generally this file should not require editing except if the Custom APE JAR file name is different, or if the source code ‘package’ names are changed.
Creating and Building a Custom APE from StarFlow Extensions Example
Create a new Java Project from within Eclipse.
Whichever Runtime Environment you chose, you can now add in the external references to the StarFlow Extensions & StarTeam SDK JAR files at this stage (or leave this until after the Eclipse project is created).
Obviously you will most likely wanting to create your own Custom Change Request form, but for simplicity, you can copy the code & package structure from the (checked-out) sample at
C:\Program Files (x86)\Borland\StarFlow Extensions\Samples\ChangeRequest\src
to your Eclipse Workspace location.
After refreshing the ‘Package Explorer’ window, you will have something like the following.
This is showing the imports section in ‘ChangeRequestForm.java’ .
As we did not include the ‘External JARs’ in the ‘Libraries’ tab when initially creating the Java Project in this example, we can now add these in the Project Build Path.
Likewise add the following JAR files from the StarFlow Extensions ‘Projects’ folder
All the previously highlighted errors should now disappear.
Execute the example Custom APE form within Eclipse
From within Eclipse you ‘run’ the Custom APE to verify the output of the form.
Make sure you have ‘ChangeRequestForm.java’ open in the Eclipse Editor and select from the toolbar ‘Run | Run As | Java Application’
An example of the finished Custom APE form will appear in a window.
This is non-functioning as in it will have no values in drop-down boxes for example.
The labels may refer to actual ‘Usr_’ custom field values rather than the actual field name.
For example, examine the dropdown labelled ‘Usr_StarFlowStatus’. As it is, this will take the correct value as defined in the field in StarTeam CPC. This applies to all fields in the editor, however, you can override these values by using ‘setLabelTextOverride’ method, as below;
Export Custom APE Source Code to Java Archive (JAR) File
Ensure the three Java source files are selected, and I would recommend exporting the JAR file directly into the working folder of the corresponding project location in your StarFlow Extensions Project.
Make sure the resulting JAR file is now checked-in to the StarFlow Extensions Project.
(As well as the ChangeRequest.propertyeditor.xml file and ChangeRequest.Workflow.xml file – this ‘custom workflow’ should have been created separately using the StarTeam Workflow Designer).
Open the target StarTeam Project via the CPC, and navigate to ‘Project | Properties | Editors’ tab;
- choose the required type of editor (in this case ‘Change Request’)
- enter “Locator ChangeRequest” (without the quotes, and the ‘ChangeReqeust’ entry in this example is the name of the created JAR file minus the ‘.jar’ extension) – avoid using the ‘Browse’ button
- Click ‘Add’, and ‘OK’ the dialog to save.
NOTE: If StarFlow Extensions or StarTeam SDK is updated or patched, the JAR files used in your Custom APE should also be updated, and you should re-build your Custom APE JAR file so that any updated files will also be included in the your Custom APE Form.