Eclipse Guvnor Tools Reference Guide

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

The Guvnor repository is not intended as a Source Code Management (SCM) solution, and the EGT is not intended to be Eclipse “team provider” extension or replacement. Rather, the Guvnor repository is a location where certain artifacts (such as rules and SOA policy definitions) are controlled (“governed”) by policies defined by the deployment environment. The purpose of the EGT is then to enable access to resources held by the Guvnor repository, so they can be used in development. Thus, limited capabilities for reading, writing, adding, and removing Guvnor repository resources are provided in the EGT.

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

To have JBoss Server with Guvnor repository deployed, you should download Drools Guvnor. When downloading you may choose either web based Guvnor to deploy to your JBoss Server or Standalone Guvnor with JBoss AS.

If you use a JBoss AS 5 and a Guvnor Tools doesn't work when deployed to the server, you should do the following to get Guvnor Tools running:

After this, Guvnor should operate as normal. During deployment, you would see the following exception in the log which indicates that the experiemental JBoss Security based ACL integration has defined some EJB3/JPA stuff in guvnor that has not been configured.

ERROR [AbstractKernelController] Error installing to Start: name=persistence.unit:unitName=#ACL state=Create
java.lang.RuntimeException: Specification violation [EJB3 JPA 6.2.1.2] - You have not defined a non-jta-data-source 
for a RESOURCE_LOCAL enabled persistence context named: ACL            
        

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

As mentioned in the "Introduction", the main purpose of the EGT is to allow development using resources held in a Guvnor repository. The first task is to make a connection to a Guvnor repository. This is handled by the Guvnor Connection wizard.

There are two methods 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.1. .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 in the Guvnor Preferences.)

Here we see that, Dummy rule.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.2. 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.3.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.3. 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.4. 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.3.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.5. Compare with Version Wizard

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

Figure 2.6. 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.7. Alert Dialog

2.3.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.8. 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.3.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.9. Comfirm Delete Dialog

The Guvnor Repository Exploring perspective contains two views supplied by EGT – Guvnor Repositories view and Guvnor Resource History view, that will be the center of most interactions 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 3.1. Enabling the Guvnor Repository Perspective

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 3.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.

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 3.5. Resource from Guvnor Wizard

Figure 3.6. Resource Selection

Figure 3.7. Choosing the Target Location

Figure 3.8. Prompt for Rename Dialog

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

Figure 3.9. 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 3.10. Going Into the "defaultPackage"

Figure 3.11. Guvnor Repository Files Properties

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 3.12. 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 3.13. Guvnor Resource History View

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

The EGT provides a preference page in the Guvnor category:

Figure 3.15. Resource Selection

For more information visit the following resources:

If you have some questions, comments or suggestions on the topic, please feel free to ask in the Jboss Tools Forum.