Eclipse Guvnor Tools Reference Guide
This guide is for developers .
Edition 5.3.1
Abstract
Preface
Chapter 1. Preface
1.1. Business Integration
1.2. What is a Service-Oriented Architecture?
A Service Oriented Architecture (SOA) is not a single program or technology. Think of it, rather, as a software design paradigm.
Note
1.3. Key Points of a Service-Oriented Architecture
- the messages being exchanged
- the agents that act as service requesters and providers
- the shared transport mechanisms that allow the messages to flow back and forth.
1.4. What is the JBoss Enterprise SOA Platform?
1.5. The Service-Oriented Architecture Paradigm
- Service Provider
- A service provider allows access to services, creates a description of a service and publishes it to the service broker.
- Service Requester
- A service requester is responsible for discovering a service by searching through the service descriptions given by the service broker. A requester is also responsible for binding to services provided by the service provider.
- Service Broker
- A service broker hosts a registry of service descriptions. It is responsible for linking a requester to a service provider.
1.6. Core and Components
1.7. Components of the JBoss Enterprise SOA Platform
- A full Java EE-compliant application server (the JBoss Enterprise Application Platform)
- an enterprise service bus (JBoss ESB)
- a business process management system (jBPM)
- a business rules engine (JBoss Rules)
- support for the optional JBoss Enterprise Data Services (EDS) product.
1.8. JBoss Enterprise SOA Platform Features
- The JBoss Enterprise Service Bus (ESB)
- The ESB sends messages between services and transforms them so that they can be processed by different types of systems.
- Business Process Execution Language (BPEL)
- You can use web services to orchestrate business rules using this language. It is included with SOA for the simple execution of business process instructions.
- Java Universal Description, Discovery and Integration (jUDDI)
- This is the default service registry in SOA. It is where all the information pertaining to services on the ESB are stored.
- Smooks
- This transformation engine can be used in conjunction with SOA to process messages. It can also be used to split messages and send them to the correct destination.
- JBoss Rules
- This is the rules engine that is packaged with SOA. It can infer data from the messages it receives to determine which actions need to be performed.
1.9. Features of the JBoss Enterprise SOA Platform's JBossESB Component
- Multiple transports and protocols
- A listener-action model (so that you can loosely-couple services together)
- Content-based routing (through the JBoss Rules engine, XPath, Regex and Smooks)
- Integration with the JBoss Business Process Manager (jBPM) in order to provide service orchestration functionality
- Integration with JBoss Rules in order to provide business rules development functionality.
- Integration with a BPEL engine.
- Be configured to work with a wide variety of transport mechanisms (such as e-mail and JMS),
- Be used as a general-purpose object repository,
- Allow you to implement pluggable data transformation mechanisms,
- Support logging of interactions.
Important
org.jboss.internal.soa.esb and org.jboss.soa.esb. Use the contents of the org.jboss.internal.soa.esb package sparingly because they are subject to change without notice. By contrast, everything within the org.jboss.soa.esb package is covered by Red Hat's deprecation policy.
1.10. Task Management
1.11. Integration Use Case
1.12. Utilising the JBoss Enterprise SOA Platform in a Business Environment
Chapter 2. Introduction
2.1. Intended Audience
2.2. Aim of the Guide
2.3. Requirements and Installation
- To get started with Guvnor Tools, you should have the following:
- JBoss Developer Studio, which can be downloaded through the RedHat customer portal.
- JBoss EAP with Guvnor repository deployed.
- To deploy JBoss EAP with the Guvnor repository, download JBoss Enterprise BRMS. 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, perform the following steps:
- 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 will 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. It looks like this: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
2.4. Guvnor Tools
Chapter 3. Tasks
3.1. Creating a New Guvnor Connection
- Open a new connection.
- Start the Guvnor Connection wizard in one of the following ways:
- Select → → → → within Eclipse
- Go to the Guvnor Repositories view using the drop-down menu
- Use the menu button
3.2. Getting Local Copies of Guvnor Files
- To get local copies of Guvnor repository resources, you can drag-and-drop them from the Guvnor Repositories View. You can also perform this action in the Guvnor Wizard.
- Local copies of Guvnor repository files will be created. The EGT will set an association between the local copy and the master file in the repository. You should not alter this information. The association allows for operations such as update and commit in synchronization with the master copy held in the Guvnor repository.

Figure 3.1. Diagram
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. TheDummy rule.drlfile 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. You can change the location of these in the Local Guvnor Repository Resource Decoration Preferences. - You can see that the
Dummy rule.drlfile is associated with a Guvnor repository resource, and the local copy is based on revision 0, with a02-10-2008, 4:21:53date/time stamp. However, the fileSample.drlis not associated with a Guvnor repository file. - The EGT adds a property page to the standard Eclipse properties dialog. Use it to view the specific Guvnor repository, the location within the repository, the version (date/time stamp) and the revision number.

Figure 3.2. Properties
3.3. Managing Guvnor Resources
- Update Action
- Available for Guvnor resources that are not synchronized with the Guvnor repository master copies. These resources may not have synchronized due to local changes and/or changes to the master copy. Performing the Update action replaces the local file contents with the current contents from the Guvnor repository master copies.
- Add Action
- Available for local files that are not associated with a Guvnor repository master copy. Choosing the Add action launches the Add in 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. Once the target Guvnor repository is chosen, the wizard asks for the folder location to add the selection files. Clicking on the Finish button adds the selected files to the Guvnor repository and creates an association between the local and Guvnor repository files.
Note
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.Note
The wizard will not allow existing Guvnor repository files to be overwritten. Another target location must be chosen. - Commit Action
- Enabled for Guvnor repository associated files that have local changes. The Commit action will write the 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, 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, you should use the Eclipse Guvnor version tools and the Eclipse standard tools to determine the differences and merge content based on the current version.
- Show History Action
- Populates the Guvnor Resource History View with revision history for the selected file.
- Compare with Version Action
- Enabled for singular Guvnor repository associated files. 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) which shows the differences in the two versions.
- Switch to Version Action
- Enabled for singular Guvnor repository associated files. It first 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.
- Delete Action
- Enabled for one or more Guvnor repository associated files. After the action has been confirmed, the Delete action removes the files in the Guvnor repository and deletes local metadata for the Guvnor repository association.
- Disconnect Action
- Enabled for one or more Guvnor repository associated files. Removes local metadata from the Guvnor repository association.
Chapter 4. Reference
4.1. Guvnor Repository Exploring Perspective
- In the Eclipse workbench menu, select → → to view the perspective list.
- Choose the perspective you wish to use. Eclipse standard views such as Properties and Resource Navigator are useful.

Figure 4.1. Perspective list
4.2. Starting the Guvnor Connection Wizard
- To start the Guvnor Connection wizard, open Eclipse and select → → → → .
- Alternatively, open the Guvnor Repositories and click the menu button in the drop-down list.
4.3. Configuring the Guvnor Connection Wizard
- Default values appear in the Location, Port and Repository fields. You can edit these fields using their corresponding text boxes.
- To input a Guvnor repository URL into the respective fields, drag and drop it into the Location field.
Important
When using Eclipse tooling, you will not be able to access Guvnor data if this Guvnor is deployed on a secured HTTP (HTTPS). - The EGT calls the Guvnor repository at various times, such as when it is determining if any resource updates are available. If you use session authentication, the authentication dialog will appear at different times during the Eclipse workbench session, depending on what actions you take. We recommend saving the authentication information in the Eclipse key-ring.Click on save username and password to save your details into the Eclipse workbench's key-ring file.
Note
If the authentication information is not stored in the key-ring, then the EGT uses a session authentication. This means that the credentials supplied are only used during the lifetime of the Eclipse workbench instance.Note
If an authentication failure error occurs, you can retry the same operation and supply different authentication information.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.
4.4. Resource from Guvnor Wizard
- This wizard allows you to copy files to your local workspace from the Guvnor repository. Open the wizard by selecting → → → or → → → → .
- You will be prompted to enter the source Guvnor repository. You can also create a new Guvnor repository connection.
- Once the source Guvnor repository is chosen, the wizard prompts for the resources to be copied.
- Finally, choose the target location for the files in the local workspace.
- 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, you will be prompted to rename it.
4.5. Guvnor Repositories View
Table 4.1. Guvnor Repositories View Actions
| Action | Description |
|---|---|
| Create a new Guvnor repository connection | Use the wizard to create a new connection by selecting → → → → in Eclipse. |
| Remove a Guvnor repository connection | Click (
![]() |
| Refresh Guvnor repository resources. | Use the context menu item to reload the tree for the selected node. |
| "Drill-into" functionality | Use icons on the toolbar such as the , and buttons to navigate deeply nested structures. |
button (
![]() | Returns the tree to the top-level structure. |
| Selecting a file in the Guvnor repository | Doing this causes the Eclipse Properties view to display the details of that file. |
4.6. Guvnor Resource History View
4.7. Configuring the Guvnor Resource History View
- Select Show History in the local Guvnor context menu. Alternatively, select it in the context menu for a Guvnor repository file in the Guvnor Repositories View.
- The Guvnor Resource History view is refreshed to display the revision history.
- To open an Eclipse read-only editor with the revision contents, double-click on a revision row or select the option from the context menu.
- Click on the option when a file is open in a read-only editor to save a local writable copy of the contents. (This will not associate the file created with its Guvnor source.)
4.8. Guvnor Preferences
- Guvnor repository connections
- Local Guvnor repository resource decorations
4.9. Guvnor Repository Connection Preferences
Table 4.2. Guvnor Repository Connection Preferences
| Preference | Description |
|---|---|
| Default Guvnor repository URL template | Simplifies the process of creating additional similar connections by changing part of the field, such as the host name. |
| Authentication information | Defines whether or not authentication information should be saved in the Eclipse platform key-ring by default. As with the Guvnor repository URL template, this decision can be determined when creating the connection. |
4.10. Local Guvnor Repository Resource Decoration Preferences
- 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
Appendix A. Revision History
| Revision History | |||
|---|---|---|---|
| Revision 5.3.1-30.400 | 2013-10-31 | ||
| |||
| Revision 5.3.1-30 | Wed Feb 20 2013 | ||
| |||


