JBoss.orgCommunity Documentation

Chapter 9. Integrating rules with your applications

9.1. The Knowledge Agent
9.2. REST API
9.2.1. REST
9.2.2. Guvnor REST API
9.2.3. Source code Example
9.3. WebDAV and HTTP
9.3.1. WebDAV
9.3.2. URLs
9.4. Eclipse Guvnor integration
9.4.1. Source Code and Plug-in Details
9.4.2. Functionality Overview
9.4.3. Guvnor Connection Wizard
9.4.4. Guvnor Repository Explorer
9.4.5. Local Copies of Guvnor Files
9.4.6. Actions for Local Guvnor Resources
9.4.7. Importing Guvnor Repository Resources
9.4.8. Guvnor plugin Preferences

Its all very interesting to manage rules, but how to you use or "consume" them in your application? This section covers the usage of the KnowledgeAgent deployment component that automates most of this for you.

The knowledge agent is a component which is embedded in knowledge-api. To use this, you don't need any extra components. In fact, if you are using Guvnor, your application should only need to include the knowledge-api and drools-core dependencies in its classpath (drools and mvel JARs only), and no other rules specific dependencies.

Note that there is also a drools-ant ant task, so you can build rules as part of an Ant script (for example in cases where the rules are edited in the IDE) without using Guvnor at all - the drools-ant task will generate .pkg files the same as Guvnor.

Once you have "built" your rules in a package in Guvnor (or from the ant task), you are ready to use the agent in your target application.

The Following example constructs an agent that will build a new KnowledgeBase from the files specified in the path String. It will poll those files every 60 seconds, which is the default, to see if they are updated. If new files are found it will construct a new KnowledgeBase. If the change set specifies a resource that is a directory it's contents will be scanned for changes too.

KnowledgeAgent kagent = KnowledgeAgentFactory.newKnowledgeAgent( "MyAgent" );

kagent.applyChangeSet( ResourceFactory.newUrlResource( url ) );
KnowledgeBase kbase = kagent.getKnowledgeBase();

The KnowledgeAgent can accept a configuration that allows for some of the defaults to be changed. An example property is drools.agent.scanDirectories, by default any specified directories are scanned for new additions, it is possible to disable this.

KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();

KnowledgeAgentConfiguration kaconf = KnowledgeAgentFactory.newKnowledgeAgentConfiguration();
// we do not want to scan directories, just files
kaconf.setProperty( "drools.agent.scanDirectories", "false" ); 
// the name of the agent
KnowledgeAgent kagent = KnowledgeAgentFactory.newKnowledgeAgent( "test agent", kaconf );
// resource to the change-set xml for the resources to add                                                                  
kagent.applyChangeSet( ResourceFactory.newUrlResource( url ) ); 

An example of the change-set.xml file.


<change-set xmlns='http://drools.org/drools-5.0/change-set'";
  xmlns:xs='http://www.w3.org/2001/XMLSchema-instance'
  xs:schemaLocation='http://drools.org/drools-5.0/change-set drools-change-set-5.0.xsd' >
    <add>
      <resource source='http://localhost:9000/TEST.pkg' type='PKG' />
    </add> 
</change-set>

Resource scanning is not on by default, it's a service and must be started, the same is for notification. This can be done via the ResourceFactory.

ResourceFactory.getResourceChangeNotifierService().start();

ResourceFactory.getResourceChangeScannerService().start();

Following shows the deployment screen of Guvnor, which provides URLs and downloads of packages.


You can see the "Package URI" - this is the URL that you would copy and paste into the change-set.xml file to specify that you want this package. It specifies an exact version (in this case to a snapshot) - each snapshot has its own URL. If you want the "latest" - then replace "NewSnapshot" with "LATEST".

You can also download a .pkg file from here, which you can drop in a directory and use the "file" or "dir" feature of the KnowledgeAgent if needed (in some cases people will not want to have the runtime automatically contact Guvnor for updates - but that is generally the easiest way for many people).

The repository back end can also be accessed via Rest. Rest is a http based protocol API - which has clients on all platforms and in all programming languages.

Representational State Transfer (REST) is a style of software architecture for distributed hypermedia systems such as the World Wide Web. The term Representational State Transfer was introduced and defined in 2000 by Roy Fielding in his doctoral dissertation.

REST-style architectures consist of clients and servers. Clients initiate requests to servers; servers process requests and return appropriate responses. Requests and responses are built around the transfer of representations of resources. A resource can be essentially any coherent and meaningful concept that may be addressed. A representation of a resource is typically a document that captures the current or intended state of a resource. the REST protocol is often considered as a light protocol versus SOAP

The Guvnor Rest API is divided in two groups of services : one around accessing rule assets by their names and packages and the second accessing rule assets by categories.

A rule asset represents all elements that can be stored and handled in Guvnor : a guided rule, a web decision table, a test scenario, etc.

The http address to use as base address is http://{ServerName}/{httpPort}/{drools-Guvnor}/rest where ServerName is the host name on the server on which Guvnor is deployed, httpPort the port number (8080 by default development), drools-guvnor the name of the archived deployed (guvnor-webapp-5.3.0 for version 5.3.0).

This part of the API allows to access all rule assets by package (with its name) and by the asset name.

Table 9.2. Accessing Rule Assets by Package

URLModeProduces MIME-TypeConsumes MIME-TypeDescription
/packagesGETapplication/atom+xmlnoneReturns all packages contained in the Guvnor repository in Atom Feed format
/packagesGETapplication/json and application/xmlnoneReturns all packages contained in the Guvnor repository in JSON or XML format
/packagesPOSTapplication/atom+xmlapplication/octet-streamCreates a new package from an input stream of DRL. Returns the newly created package in Atom Entry format.
/packagesPOSTapplication/json and application/xmlapplication/octet-streamCreates a package from an input stream of DRL. Returns the newly created package in JSON or XML format.
/packagesPOSTapplication/atom+xmlapplication/atom+xmlCreates a package from an Atom Entry. Returns the newly created package in Atom Entry format
/packagesPOSTapplication/json and application/xmlapplication/json and application/xmlCreates a package from JSON or XML. Returns the newly created package in JSON or XML format.
/packages/{packageName}GETapplication/atom+xmlnoneReturns the metadata of the package {packageName} as an Atom Entry.
/packages/{packageName}GETapplication/json and application/xmlnoneReturns the metadata of the package {packageName} as a Package element (see UML representatin below).
/packages/{packageName}/sourceGETplain/textnoneReturns the source code of the package {packageName} as a text file.
/packages/{packageName}/binaryGETapplication/octet-streamnoneReturns the compiled binary of the package {packageName} as a binary stream. If the package has not been compiled yet or its binary is not up to date, this will compile the package first.
/packages/{packageName}/versionsGETapplication/atom+xmlnoneReturns the list of package {packageName} versions as an Atom Feed .
/packages/{packageName}/versions/{version}GETapplication/atom+xmlnoneReturns the metadata of package {packageName} and of version {version} as an Atom Entry .
/packages/{packageName}/versions/{version}/sourceGETtext/plainnoneReturns the source code of package {packageName} and of version {version} as a text file.
/packages/{packageName}/versions/{version}/binaryGETapplication/octet-streamnoneReturns the binary (compiled code) of package {packageName} and of version {version} as an octet stream. If the package version was never built, it returns HTTP code 500 with an error message.
/packages/{packageName}PUTapplication/atom+xmlnoneUpdates the metadata of package {packageName} with a given Atom Entry.
/packages/{packageName}DELETEnonenoneDeletes package {packageName}.
/packages/{packageName}/assetsGETapplication/atom+xmlnoneReturns the list of rule assets contained in package {packageName} as an Atom Feed.
/packages/{packageName}/assetsGETapplication/json and application/xmlnoneReturns the list of rule assets contained in package {packageName} in JSON or XML format
/packages/{packageName}/assets/{assetName}GETapplication/atom+xmlnoneReturns the rule asset {assetName} contained in package {packageName} in Atom Entry format.
/packages/{packageName}/assets/{assetName}GETapplication/json and application/xmlnoneReturns the rule asset {assetName} contained in package {packageName} as an Asset in JSON or XML format (see the UML representation below).
/packages/{packageName}/assets/{assetName}/binaryGETapplication/octet-streamnoneReturns the binary content of rule asset {assetName} contained in package {packageName}. If this asset has no binary content, returns its source content instead.
/packages/{packageName}/assets/{assetName}/sourceGETplain/textnoneReturns the content of rule asset {assetName} contained in package {packageName}. If this is a binary asset, returns the binary data as a byte array.
/packages/{packageName}/assetsPOSTapplication/atom+xmlapplication/atom+xmlCreates an asset in package {packageName} from the Atom Entry provided. Following info are required from the input Atom Entry: asset name, asset description, asset initial category, asset format.
/packages/{packageName}/assetsPOSTapplication/octet-streamapplication/atom+xmlCreates a binary asset in package {packageName} from the input stream. The value of Slug header is used to indicate the name of the asset. This returns HTTP 500 error is the slug header is missing.
/packages/{packageName}/assets/{assetName}PUTapplication/atom+xmlnoneUpdates the metadata of the rule asset {assetName} contained in package {packageName} with a given Atom Entry.
/packages/{packageName}/assets/{assetName}PUTapplication/json and application/xmlnoneUpdates the metadata of the rule asset {assetName} contained in package {packageName} with a given Asset (see the UML representation below).
/packages/{packageName}/assets/{assetName}/sourcePUTplain/textnoneUpdates the source code of the rule asset {assetName} contained in package {packageName}.
/packages/{packageName}/assets/{assetName}/binaryPUTapplication/octet-streamnoneUpdates the binary content of the rule asset {assetName} contained in package {packageName}.
/packages/{packageName}/assets/{assetName}/versionsGETapplication/atom+xmlnoneReturns the list of rule asset {assetName} versions contained in package {packageName} as an Atom Feed .
/packages/{packageName}/assets/{assetName}/versions/{version}GETapplication/atom+xmlnoneReturns the metadata of rule asset {assetName} of version {version} contained in package {packageName} as an Atom Entry .
/packages/{packageName}/assets/{assetName}/versions/{version}/sourceGETtext/plainnoneReturns the source code of rule asset {assetName} of version {version} contained in package {packageName} as a text file.
/packages/{packageName}/assets/{assetName}/versions/{version}/binaryGETapplication/octet-streamnoneReturns the binary content of rule asset {assetName} of version {version} contained in package {packageName}. If this asset has no binary content, returns its source content instead.
/packages/{packageName}/assets/{assetName}DELETEnonenoneDeletes the rule asset {assetName} contained in package {packageName}.


We are giving a list of example to help using the Guvnor's Rest API

We are using apache CXF in our example to show how to access the Rest API of Guvnor. In the example here we are getting and updating a web decision table. But this example applies to all Guvnor asset type.


In the first line of code above, we are first creating a WebClient variable that points to the server (here on localhost on port 8080).

In the second line of code above, we are retrieving the source content by accessing the /rest/packages/{packageName}/assets/{assetName}/source where i our case packageName is "essaiRest" and assetName is "tab2".

In the third line of code above, the source code we get is the data structure of a Web decision table. So to be able to manipulate the Web decision table, we have to transform the string variable (the source code that contains the xml of the data structure of the web decision table) in the java structure (a java class) for web decision table GuidedDecisionTable52. All guided asset in Guvnor have a java structure to manipulate them


In the first line of code above, we are first creating a java String variable that contains the authorization element needed to update an asset on the Guvnor repository.

In the next lines of code above, we are doing some stuff to modify the Web decision table.

In the following lines of code above, we are first transforming the java structure in an xml structure that we put in a java String variable. Then we again create a WebClient but this time we are also filling the header with a variable "Authorization" that contains the String we built in the first line and that contains the user name "guest" and its password (here no password). We then put the new content on the Guvnor repository.

Next you can find the pom.xml file to use the Guvnor Rest API in case you are using Maven.


The repository back end can also be accessed via webdav. WebDAV is a http based file system API - which has clients on all platforms (some operating systems such as windows can connect directly to WebDAV repositories almost like a file system.

The Eclipse Guvnor tools (EGT) provide the ability to push/pull artifacts from the Guvnor repository server and the developers workspace in eclipse. It is therefore possible for artifacts to be both managed via Guvnor as well as in traditional developer friendly SCM systems (such as subversion). The Guvnor repository is not intended as a Source Code Management (SCM) solution, and the EGT are not intended to be Eclipse “team provider” extensions or replacements. 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.

The source code for the EGT is available in github. EGT consist of two plug-ins: org.guvnor.tools and org.eclipse.webdav. They require Eclipse 3.3.x. The current Eclipse Drools plug-ins are also useful for viewing Guvnor repository resources such as rule definitions, but not required for operation of the EGT.

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 using the Eclipse menu: File , New , Other , Guvnor , Guvnor repository location, or in the Guvnor Explorer using the drop-down menu:


or the menu button:


Choosing either of these will start the Guvnor connection wizard:


Default values appear in the Location, Port, and Repository fields. (See "Guvnor plugin Preferences" 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/guvnor-webapp/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 the authentication information is not stored in the key-ring, then the EGT uses session authentication, which means that the credentials supplied are used only for 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 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. (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 determining if resource updates are available, so, 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 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 unsynchronized and you will be unexpectedly prompted for authentication in Eclipse. This is nuisance, but your usual credentials should apply in this case.)

Once the Guvnor connection wizard is complete, the new Guvnor repository connection will appear in the Guvnor Repository Explorer. You can then expand the tree to view Guvnor repository contents.


The Guvnor Repository Explorer view contains tree structures for Guvnor repository contents. As described above, there are menu and tool-bar actions for creating Guvnor repository connections. The red “X” in the tool-bar and “Delete” in the menu removes a Guvnor repository connection, and the “Refresh” menu item reloads tree content for the selected node. Finally, there are a number of tool-bar/menu items in support of “drill-into” functionality: one the tool-bar these are represented by the house (“return to top level/home”) and the arrows (go into/back). 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 shown above changes the tree view to:


That is, we see only the contents of “defaultPackage” in the tree. Clicking on the house button, or selecting “Go Home” 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:


Double-clicking on a folder (directory) in the tree will cause that folder to expand if collapsed and collapse if expanded. Double-clicking on a file in the tree will cause a read-only editor in Eclipse to open, showing the contents of that file:


Dragging a file from the Guvnor repository tree to a folder in an Eclipse local project (for example in the Eclipse Resource Navigator view) will cause a copy of that file to be made in the local Eclipse workspace. (Note: You can also “Save As...” 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.) Finally, you can view the revision history of a file selected in the tree using the “Show History” context menu item. (The details of resource history will be discussed below.)

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.) This 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. The image below shows decoration in the Eclipse Resource Navigator:


Note the Guvnor icon decorator on the top right of the file images, and the Guvnor revision details appended to the file names. (The presence/location of these can be changed. See "Guvnor plugin Preferences" for details.) Here we see that, for example, simpleRule.drl is associated with a Guvnor repository resource and the local copy is based on revision 3, with a 7-15-2008, 15:37:34 date/time stamp. The file deleteTest.txt, however, is not associated with a Guvnor repository file. Further details about the association can be found in the standard Eclipse properties page, via the context menu “Properties” selection:


The EGT contributes a property page to the standard Eclipse properties dialog, the contents of which are shown above. The specific Guvnor repository, the location within the repository, the version (date/time stamp) and revision number are displayed.

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: 1.Update 2.Add 3.Commit 4.Show History 5.Compare with Version 6.Switch to Version 7.Delete 8.Disconnect Each of these actions will be described below.

Update Action:

The Update action is available for one or more Guvnor resources that are not in synchronization with the Guvnor repository master copies. These resources would not be in synchronization because either/both (1) there are local changes to these resources or (2) the master copies have 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 “Switch to version” for latest version).

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:


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 described above). Once the target Guvnor repository is chosen, the wizard then asks for the folder location to add the selection files:


Here I have selected the folder “anotherPackage” as the destination location1. Clicking on “Finish” adds the selected files to the Guvnor repository and creates an association between the local and Guvnor repository files. (Not that the wizard will not allow for overwrite of existing Guvnor repository files – another target location must be chosen.)

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):


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


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.

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:


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

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.

Disconnect Action:

The Disconnect action is enabled for one or more Guvnor repository associated files, and removes local metadata for the Guvnor repository association.

Guvnor Resource History View:

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:


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 Repository Explorer. Once this action is performed, the Guvnor Resource History view updates to show the revision history:


Here we see that the file “simpleRule.drl” has three revisions. Double clicking on a revision row (or context menu “Open (Read only)”) opens an Eclipse read-only editor with the revision contents. (Note: You can also “Save As...” 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 and local Guvnor repository resource decorations.

Guvnor Repository Connection Preferences

There are two preferences that can be set for Guvnor repository connections, and these are used when creating new connections. The first is a default Guvnor repository URL template, which can make it easier to create multiple similar connections by simply changing part of the field, such as the host name. The second is whether saving of authentication information in the Eclipse platform key-ring should be enabled by default. 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.

Local Guvnor Repository Resource Decoration Preferences

The second category of preferences provided by the EGT deals with how 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, bottom right, top left, 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: 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 “Apply” or “Ok” buttons.