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 an 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 deploy JBoss Server with the Guvnor repository, 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 JBoss AS 5 and 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 experimental 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 Chapter 2, Tasks section to find out what you can do with Guvnor and Eclipse synchronization tool.

As mentioned in the Chapter 1, Introduction section, the main purposeof 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 Connection Wizard (see Section 3.2, “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 association allows for operations such as update and commit in synchronization with the master copy held in the Guvnor repository.

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. In 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 Local Guvnor Repository Resource Decoration Preferences (see the Section 3.6.2, “Local Guvnor Repository Resource Decoration Preferences” section).

Here we see that the Dummy rule.drl file 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. However, the file Sample.drl 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 adds a property page to the standard Eclipse properties dialog, the contents of which are shown above. It displays the specific Guvnor repository, the location within the repository, the version (date/time stamp) and the revision number.

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 Figure 3.4, “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 the 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 – Section 3.4, “Guvnor Repositories View” and Section 3.5, “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

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 by selecting File → Import → Guvnor → Resource from Guvnor or File → New → Other → Guvnor → Resource from Guvnor.

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 Figure 3.4, “Guvnor Connection Wizard”).

Figure 3.5. Resource from Guvnor Wizard

Once the source Guvnor repository is chosen, the wizard prompts for resource selection:

Figure 3.6. Resource Selection

Finally, the target location in the local workspace should be chosen:

Figure 3.7. Choosing the Target Location

On completion the wizard copies the selected files from the Guvnor repository to the local workspace. If a file with the same name already exists in the destination, the wizard uses the Eclipse standard prompt for rename dialog:

Figure 3.8. Prompt for Rename Dialog

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

Figure 3.9. Guvnor Repositories View

You can perform the following actions under the resources in the Guvnor Repositories view:

• create a new Guvnor repository connection. How to do this is describe above in the Section 3.2, “Guvnor Connection Wizard” section.

• Remove a Guvnor repository connection. Use the Delete button ( ) in the tool-bar or the Delete option in the context menu to remove a repository connection.

• Refresh Guvnor repository resorces. Use the Refresh context menu item to reload a tree content for the selected node.

• Make use of "drill-into" functionality. It's represented by a number of tool-bar/context menu items such as Go Home ( ), Go Back ( ) and Go Into ( ).

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

Clicking on the Go Home button ( ) or selecting Go Home in the context menu returns the tree to the top-level structure shown in the previous picture above.

There are a number of operations that can be performed on Guvnor repository files. Selecting a file in the Guvnor repository causes the Eclipse Properties view to update with details about that file:

Figure 3.11. Guvnor Repository Files Properties

The Guvnor Resource History view shows 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 Section 3.4, “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

Here we see that the file test.txt has seven revisions. Double clicking on a revision row (or the context menu Open (Read only)) opens an Eclipse read-only editor with the revision contents.

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

Note:

You can also use the Save As... option when a file is open in a read-only editor to save a local writable copy of the contents. Doing so, however, will not associate the file created with its Guvnor source.

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.