The purpose of this document is to describe briefly the functionality present in the Eclipse Guvnor Tools (EGT) for Drools 5. While not intended as a comprehensive reference, there should be enough detail included for early adopters using these tools.
The table below lists the key features of Guvnor Tools:
The following table lists all valuable features of the Guvnor Tools.
Table 1.1. Key Functionality of Guvnor Tools
| Feature | Benefit | Chapter |
|---|---|---|
|
Guvnor Repositories View |
The purpose of this view is to enable access to Guvnor repository resources in a standard tree format | Section 3.4, “Guvnor Repositories View” |
|
Guvnor Connection Wizard |
This wizard helps to create a connection to a Guvnor repository. | Section 3.2, “Guvnor Connection Wizard” |
|
Guvnor Resource History View |
This view shows revisions of specific resources available in the repository. | Section 3.5, “Guvnor Resource History View” |
|
Resource from Guvnor wizard |
This wizard helps to get local copies of Guvnor repository resources. | Section 3.3, “Resource from Guvnor Wizard” |
|
A number of actions for working with files |
The Guvnor actions (available through the Guvnor context menu on files) are provided for working with files, both those associated with Guvnor repository master copies and those not associated. | Section 2.3, “Managing Guvnor Resources” |
The Guvnor repository is not intended to be 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:
JBoss Developer Studio, which can be downloaded through the RedHat customer portal.
JBoss Server 4.2 or higher with Guvnor repository deployed.
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 perform the following steps to get Guvnor Tools running:
Remove the JBoss Security libraries (
authorization-spi-2.0.2.CR6.jar,identity-*,acl-spi-2.0.2.CR6.jar) from drools WAR file (not the app server itself). The JBoss Security libraries are provided in AS 5.Remove the JAXP libraries (
xercesImpl-2.8.0.jar,xml-apis-2.*)Remove the EL libraries (
el-*)
When these steps have been performed, 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 features in guvnor that have 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
This chapter provides an overview of the functionality provided by the Guvnor Tools.
As mentioned in Chapter 1, 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 Connection Wizard (see Section 3.2, “Guvnor Connection Wizard”).
There are two methods of getting local copies of Guvnor repository resources:
Drag-and-drop from the Guvnor Repositories View, as described in Section 3.4, “Guvnor Repositories View”
Using the Resource from Guvnor Wizard, as described in Section 3.3, “Resource from Guvnor Wizard”
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.
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 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:
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.
The Update action is available for one or more Guvnor resources that are not synchronized with the Guvnor repository master copies. These resources would not synchronized due to one or or both of the following conditions:
There are local changes to these resources
The master copies have been changed in the Guvnor repository
Performing the Update action replaces the local file contents with the current contents from the Guvnor repository master copies (equivalent to Section 2.3.6, “Switch to Version Action” for the latest version).
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:
The first page of the wizard asks for the selection of the target Guvnor repository, and provides the option of creating a new Guvnor repository connection (in which case the second page is the same as 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:
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 button 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 existing Guvnor repository files to be overwritten. Another target location must be chosen.
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 than is currently in the Guvnor repository (for example, someone else changed the same file), then the Commit action will 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.
The Show History action is enabled for one Guvnor repository associated file, and populates the Section 3.5, “Guvnor Resource History View” with revision history for the selected file.
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):
Once the revision is selected, the action opens the Eclipse Compare editor (in a read-only mode):
This editor uses the standard Eclipse comparison techniques to show the differences in the two versions. In cases where there are no differences, the editor will not open, and instead a dialog saying that there are no differences will be displayed.
The Switch to Version action is enabled for one Guvnor repository associated file.
First the Switch to Version action prompts for the selection of a version:
Once the version is selected, the Switch to Version action replaces the local file contents with those from the revision selected.
The Delete action is enabled for one or more Guvnor repository associated files. After the action has been confirmed using the dialog shown below, the Delete action removes the files in the Guvnor repository and deletes local metadata for the Guvnor repository association.
This chapter includes detailed reference information about Views and Wizards used to manage Guvnor Tools.
The Guvnor Repository Exploring perspective contains two views supplied by EGT, described in Section 3.4, “Guvnor Repositories View” and Section 3.5, “Guvnor Resource History View”, that will be the center of most interactions with Guvnor. Eclipse standard views such as Properties and Resource Navigator 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 for displaying a common layout. In the Eclipse workbench menu, select → → to view the perspective list:
Selecting the option will open the Guvnor perspective.
The Guvnor Connection 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:
Selecting → → → → within Eclipse
In the Guvnor Repositories view using the drop-down menu
using the menu button (
)
Choosing either of these will start the Guvnor Connection wizard.
Default values appear in the Location, Port and Repository fields (See Chapter 3, Reference for details about on changing these default values). Of course, any of these fields can be edited by editing the corresponding text box. Drag-and-drop or paste into the Location field a typical Guvnor repository URL such as:
http://localhost:8080/drools-guvnor/org.drools.guvnor.Guvnor/webdav
This 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.
Note:
If the authentication information is not stored in the key-ring, then the EGT uses a session authentication, what means that the credentials supplied are only used during the lifetime of the Eclipse workbench instance.
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 the authentication information once it has to access the Guvnor repository.
If authentication fails, the EGT will retry once and then issue an authentication failure error.
Tip:
If an authentication failure error occurs, you can retry the same operation and supply different authentication information.
Note that the EGT calls the Guvnor repository at various times, such as when it is determining if any 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.
Note:
The Eclipse key-ring file is distinct from key-ring files found in some platforms such as Mac OS X and many forms of Linux. Thus, sometimes if you access a Guvnor repository outside the EGT, the key-ring files might become outdated, and you will be unexpectedly prompted for your credentials in Eclipse. This is nuisance, but in this case you can simply re-enter the appropriate username and password.
In addition to the single file drag-and-drop features provided within 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 → → → or → → → → .
Note:
Note that the wizard is identical but appears in both locations to accommodate users who tend to view this functionality as being in either category.
The first page of the wizard asks for the selection of the source Guvnor repository and gives the option 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 source Guvnor repository is chosen, the wizard prompts for the resources to be copied:
Finally, the target location in the local workspace should be chosen:
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:
The Guvnor Repositories view contains tree structures representing the contents of Guvnor repositories.
You can perform the following actions under the resources in the Guvnor Repositories view:
Create a new Guvnor repository connection. This process is described above in Section 3.2, “Guvnor Connection Wizard”.
Remove a Guvnor repository connection. Use the Delete button (
) in the toolbar or the option in the context menu to remove a repository connection.
Refresh Guvnor repository resources. Use the context menu item to reload the tree for the selected node.
Make use of "drill-into" functionality. It's represented by a number of toolbar and context menu items such as (
), ( 
) and ( 
).
Drill-down is useful when working with deeply nested tree structures, and when you wish to concentrate on only a single branch of the tree. For example, drilling into the defaultPackage node changes the tree view to:
Clicking on the button ( ) or selecting 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 display the details of that file:
The Guvnor Resource History view displays details about the revision history for the selected files, both local and those in Guvnor repositories. The initial state of this view is shown on the figure below.
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 (see Section 3.4, “Guvnor Repositories View”). Once this action is performed, the Guvnor Resource History view is refreshed to display the revision history:
Here we see that the file test.txt has seven revisions. Double clicking on a revision row or selecting the option from the context menu opens an Eclipse read-only editor with the revision contents.
Note:
You can also use the 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:
The preferences cover two categories:
Guvnor repository connections
Local Guvnor repository resource decorations.
There are two preferences that can be set for Guvnor repository connections, which are used when creating new connections:
The first is a default Guvnor repository URL template, which can simplify the process of creating additional similar connections by simply changing part of the field, such as the host name.
The second defines whether or not authentication information should be saved in the Eclipse platform key-ring by default.
As with the Guvnor repository URL template, the decision whether to save authentication information in the Eclipse platform key-ring can be determined when 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 can be used to define 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 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 which is appended to the file names:
Whether to show an indicator (>) when the local file has changes not committed back to the Guvnor repository
Whether to show the revision number
Whether to show the date/time stamp
Any changes to these preferences take effect immediately upon clicking the and then buttons.
As stated at the beginning of this document, the key goal of the EGT is to provide a way to interact with Guvnor repository resources in a local Eclipse workspace. While clearly there is a lot more that could be done, and no doubt there will be aspects of the current tooling that require revision going forward, we feel that the current state of the EGT is sufficient for the major use cases.
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.