Eclipse Guvnor Tools Reference Guide

The following table lists all valuable features of the Guvnor Tools.

Guvnor Tools is a part of the JBoss Tools project. Thus to get started with Guvnor Tools, you should have the following:

Now refer to the "Functionality Overview" section to find out what you can do with Guvnor and Eclipse synchronisation tool.

The Guvnor Repository Exploring perspective contains two views supplied by EGT – Repository Explorer and Version History, that will be the center of most interaction with Guvnor, and Eclipse standard views such as Properties and Resource Navigator that are also useful.

While each of these views can be opened and positioned independently within an Eclipse workbench, the Guvnor perspective provides a convenient method of getting a suggested layout. In the Eclipse workbench menu, choose Window > Open Perspective > Other to get the perspective list:

Figure 2.1. Enabling the Guvnor Repository Perspective

After opening the Guvnor perspective, the first task is to make a connection to a Guvnor repository. This is handled by the Guvnor Connection wizard. This wizard appears in a number of places within the EGT (as detailed below), but in this section we will cover only the two most basic entry points.

The Guvnor Connection wizard can be started in the following ways:

Choosing either of these will start the Guvnor Connection wizard.

Figure 2.4. Guvnor Connection Wizard

Default values appear in the Location, Port, and Repository fields (See the “Guvnor Preferences” section below for details about how to change these default values.) Of course, any of these fields can be edited by typing in the corresponding text box. Drag-and-drop or paste into the Location field of a typical Guvnor repository URL such as:

http://localhost:8080/drools-guvnor/org.drools.guvnor.Guvnor/webdav

Results in the URL being parsed into the respective fields as well. The authentication information (user name and password) can optionally be stored in the Eclipse workbench's key-ring file based on the selection of Save user name and password.

If authentication information is not stored in the key-ring or the authentication information (key-ring or session) is not valid, the EGT will prompt for authentication information when it has to access the Guvnor repository.

If authentication fails, the EGT will retry once and then issue an authentication failure error.

Note that the EGT calls the Guvnor repository at various times, such as when determining if resource updates are available. Thus if you use session authentication, the authentication dialog will appear at different times during the Eclipse workbench session, depending on what actions you take. For ease of use, we recommend saving the authentication information in the Eclipse key-ring.

The Guvnor Repositories view contains tree structures for Guvnor repository contents.

Figure 2.5. Guvnor Repositories View

Drill-down is useful when working with deeply nested tree structures and when you wish to concentrate on only branch of the tree. For example, drilling into the "defaultPackage" node changes the tree view to:

Figure 2.6. Going Into the "defaultPackage"

Figure 2.7. Guvnor Repository Files Properties

As mentioned in the "Introduction", the main purpose of the EGT is to allow development using resources held in a Guvnor repository. There are two method of getting local copies of Guvnor repository resources:

When local copies of Guvnor repository files are created, the EGT sets an association between the local copy and the master file in the repository. This information is kept in the (normally) hidden .guvnorinfo folder in the local project and, like all metadata, should not be changed by end users.

Figure 2.8. .guvnorinfo metadata

The EGT decorates local resources associated with Guvnor repository master copies. This decoration appears in Eclipse views conforming to the Eclipse Common Navigator framework, such as the Eclipse Resource Navigator and the Java Package Explorer. On the image above you can see the Dummy rule.drl file with the decoration in the Resource Navigator. The Guvnor icon decorator is on the top right of the file image, and the Guvnor revision details are appended to the file name. (The presence/location of these can be changed the Guvnor Preferences.)

Here we see that, Dummy role.drl is associated with a Guvnor repository resource and the local copy is based on revision 0, with a 02-10-2008, 4:21:53 date/time stamp. The file Sample.drl, however, is not associated with a Guvnor repository file. Further details about the association can be found in the standard Eclipse properties page, accessed via the Properties option in the context menu:

Figure 2.9. Association Details

The EGT provides a number of actions (available through the Guvnor context menu on files) for working with files, both those associated with Guvnor repository master copies and those not associated. The actions are:

Each of these actions is described below.

2.5.2. Add Action

The Add action is available for one or more local files that are not associated with a Guvnor repository master copy. Choosing the Add action launches the Add to Guvnor wizard:

Figure 2.10. Add to Guvnor Wizard

The first page of the wizard asks for the selection of the target Guvnor repository and gives the choice to create a new Guvnor repository connection (in which case the second page is the same as the Guvnor Connection wizard). Once the target Guvnor repository is chosen, the wizard then asks for the folder location to add the selection files:

Figure 2.11. Selecting a Target Folder

Here the "defaultPackage" folder is selected as the destination location.

Note:

Note that the "snapshot" folder in the Guvnor repository is read-only for EGT, and hence not visible as a candidate location in this wizard. The Guvnor repository web administration tools must be used to add snapshot content.

Clicking on Finish adds the selected files to the Guvnor repository and creates an association between the local and Guvnor repository files.

Note:

Note that the wizard will not allow for overwrite of existing Guvnor repository files. Another target location must be chosen.

2.5.3. Commit Action

The Commit action is enabled for one or more Guvnor repository associated files that have local changes. The Commit action will write the local changes back to the associated Guvnor repository files and update the association for the new revision created.

If a local change is based on an older revision of a file that is currently in the Guvnor repository (for example, someone else changed the same file), then the Commit action will

Figure 2.12. Add to Guvnor Wizard

ask whether you wish to overwrite the current version in the Guvnor repository with the local content. When such conflicts occur, however, you should use the Eclipse Guvnor version tools, along with Eclipse standard tools, to determine the differences and merge content based on the current version in the Guvnor repository.

2.5.5. Compare with Version Action

The Compare with Version action is enabled for one Guvnor repository associated file. This action first opens a wizard asking for the version for comparison (with the local file contents):

Figure 2.13. Compare with Version Wizard

Once the revision is selected, the action opens the Eclipse Compare editor (read-only):

Figure 2.14. Eclipse Compare Editor

This editor uses Eclipse-standard comparison techniques to show the differences in the two versions. In cases where there are no differences, the editor will not open, rather a dialog saying that there are no differences will appear.

Figure 2.15. Alert Dialog

2.5.6. Switch to Version Action

The Switch to Version action is enabled for one Guvnor repository associated file.

First the Switch to Version action prompts for selection of version:

Figure 2.16. Select Version Window

Once the version is selected, the Switch to Version action replaces the local file contents with those from the revision selected.

2.5.7. Delete Action

The Delete action is enabled for one or more Guvnor repository associated files. After confirmation via a dialog, the Delete action removes the files in the Guvnor repository and deletes local metadata for the Guvnor repository association.

Figure 2.17. Comfirm Delete Dialog

The Guvnor Resource History view should details about revision history for selected files, both local and those in Guvnor repositories. The initial state of this view is shown on the figure below.

Figure 2.18. Initial State of the Guvnor Resource History View

The Guvnor Resource History view is populated by Show History actions in either the local Guvnor context menu or in the context menu for a Guvnor repository file in the Guvnor Repositories view. Once this action is performed, the Guvnor Resource History view updates to show the revision history:

Figure 2.19. IGuvnor Resource History View

Figure 2.20. Eclipse Read-only Editor with the Revision Contents

In addition to the single file drag-and-drop from the Guvnor Repositories view, the EGT also includes a wizard for copying one or more files from a Guvnor repository to the local workspace (and setting the association with the Guvnor repository). This wizard is available from the File > Import > Guvnor > Resource from Guvnor and the File > New > Other > Guvnor > Resource from Guvnor menu items.

The first page of the wizard asks for the selection of the source Guvnor repository and gives the choice to create a new Guvnor repository connection (in which case the second page is the same as the Guvnor Connection wizard).

Figure 2.21. Resource from Guvnor Wizard

Figure 2.22. Resource Selection

Figure 2.23. Choosing the Target Location

Figure 2.24. Prompt for Rename Dialog

There are two preferences that can be set for Guvnor repository connections, that are used when creating new connections:

As with the Guvnor repository URL template, actually whether to save a specific instance of authentication information in the Eclipse platform key-ring can be determined when actually creating the connection. That is, both of these preferences are simply convenience values set to reasonable defaults.

The second category of preferences provided by the EGT deals with how the decoration of local resources associated with Guvnor repository resources is presented. Since the Guvnor repository is not a substitute for a SCM, and since SCM tools in Eclipse tend to decorate local resources, it is useful to be able to control just how the EGT decorate its local resources to avoid messy conflicts with SCM packages.

In the File Decoration section of the preference page, you can choose the location (Top right, Top left, Bottom right, Bottom left) of the decoration icon, or you can choose not to display it. In the Text section, you can format the Guvnor metadata that is appended to the file names:

Any changes to these preferences take effect immediately upon clicking the Apply and then Ok buttons.