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.


<?xml version="1.0" encoding="UTF-8"?>
<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 http://anonsvn.jboss.org/repos/labs/labs/jbossrules/trunk/drools-api/src/main/resources/change-set-1.0.0.xsd" >
    <add>
      <resource source="http://localhost:8080/guvnor-6.0.0.CR3/org.drools.guvnor.Guvnor/package/mortgages/LATEST" type="PKG" basicAuthentication="enabled" username="uid" password="pwd"/>
    </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 snapshot, replace the name of the snapshot in the URL with the word "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 any element 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}/{guvnorWarFilename}/rest where ServerName is the host name on the server on which Guvnor is deployed, httpPort the port number (8080 by default development) and guvnorWarFilename the name of the archived deployed (guvnor-webapp-5.3.0 for version 5.3.0) without the extension.

Use the URLs listed below to access rules assets by package. The examples below assume a base URL of http://localhost:8080/guvnor-6.0.0.CR3/rest/.

/packages

http://localhost:8080/guvnor-6.0.0.CR3/rest/packages

The GET method produces MIME-Types:

  • application/atom+XML

  • application/json

  • application/xml

The GET method return all packages contained in the repository in the requested format (Atom feed, JSON, or XML).

The POST method produces MIME-Types:

  • application/atom+XML

  • application/json

  • application/xml

The POST method consumes MIME-Types:

  • application/octet-stream

  • application/atom+xml

  • application/json

  • application/xml

The POST method creates a new package from an input stream of DRL, an Atom feed, JSON, or XML, and returns the newly created package in the requested format (Atom feed, JSON, or XML).

/packages/{packageName}

http://localhost:8080/guvnor-6.0.0.CR3/rest/packages/{packageName}

The GET method produces MIME-Types:

  • application/atom+xml

  • application/json

  • application/xml

The GET method returns the metadata of the package {packageName} as an Atom entry when the MIME-Type is application/atom+xml, and as a package element when the MIME-Type is application/json or application/xml.

The PUT method produces MIME-Types:

  • application/atom+xml

  • application/json

  • application/xml

The PUT method updates the metadata of package {packageName} with the provided format (Atom Entry, JSON, or XML).

The DELETE method deletes package {packageName}.

/packages/{packageName}/source

http://localhost:8080/guvnor-6.0.0.CR3/rest/packages/{packageName}/source

The GET method produces MIME-Types:

  • text/plain

The GET method returns the source code of the package {packageName} as a text file.

/packages/{packageName}/binary

http://localhost:8080/guvnor-6.0.0.CR3/rest/packages/{packageName}/binary

The GET method produces MIME-Types:

  • application/octet-stream

The GET method returns 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}/versions

http://localhost:8080/guvnor-6.0.0.CR3/rest/packages/{packageName}/versions

The GET method produces MIME-Types:

  • application/atom+xml

The GET method returns the list of package {packageName} versions as an Atom Feed.

/packages/{packageName}/versions/{version}

http://localhost:8080/guvnor-6.0.0.CR3/rest/packages/{packageName}/versions/{version}

The GET method produces MIME-Types:

  • application/atom+xml

The GET method returns the metadata of package {packageName} and of version {version} as an Atom Entry.

/packages/{packageName}/versions/{version}/source

http://localhost:8080/guvnor-6.0.0.CR3/rest/packages{packageName}/versions/{version}/source

The GET method produces MIME-Types:

  • text/plain

The GET method returns the source code of package {packageName} and of version {version} as a text file.

/packages/{packageName}/versions/{version}/binary

http://localhost:8080/guvnor-6.0.0.CR3/rest/packages/{packageName}/versions/{version}/binary

The GET method produces MIME-Types:

  • application/octet-stream

The GET method returns the binary (compiled code) of package {packageName} and of version {version} as an octet stream. If the package version has not been built, it returns HTTP code 500 with an error message.

/packages/{packageName}/assets

http://localhost:8080/guvnor-6.0.0.CR3/rest/packages{packageName}/assets

The GET method produces MIME-Types:

  • application/atom+xml

  • application/json

  • application/xml

The GET method returns the list of rule assets contained in package {packageName} in the requested format (Atom feed, JSON, or XML).

The POST method produces MIME-Types:

  • application/atom+xml

  • application/octet-stream

The POST method creates an asset in package {packageName}.

When an Atom Entry is provided the following information must be included in the input: asset name, asset description, asset initial category, and asset format.

When an octet-stream is provided the value of slug header is used to indicate the name of the asset. If the slug header is missing a HTTP 500 error is returned.

The POST method produces MIME-Types:

  • application/json

  • application/xml

The POST method consumes MIME-Types:

  • multipart/form-data

The POST method creates the asset {assetName} for the package {packageName}.

/packages/{packageName}/assets/{assetName}

http://localhost:8080/guvnor-6.0.0.CR3/rest/packages{packageName}/assets/{assetName}

The GET method produces MIME-Types:

  • application/atom+xml

  • application/json

  • application/xml

The GET method returns the rule asset {assetName} contained in package {packageName} in the requested format (Atom feed, JSON, or XML).

The PUT method produces MIME-Types:

  • application/atom+xml

  • application/json

  • application/xml

The PUT method consumes MIME-Types:

  • multipart/form-data

The PUT method updates the metadata of the rule asset {assetName} contained in package {packageName} with the provided format (Atom Entry, JSON, or XML). When Multipart/form-data is supplied the asset {assetName} in package {packageName} is updated.

The DELETE method deletes the rule asset {assetName} contained in package {packageName}.

/packages/{packageName}/assets/{assetName}/binary

http://localhost:8080/guvnor-6.0.0.CR3/rest/packages{packageName}/assets/{assetName}/binary

The GET method produces MIME-Types:

  • application/octet-stream

The GET method returns the binary content of rule asset {assetName} contained in package {packageName}. If this asset has no binary content, the source content is returned instead.

The PUT method produces MIME-Types:

  • application/octet-stream

The PUT method updates the binary content of the rule asset {assetName} contained in package {packageName}.

/packages/{packageName}/assets/{assetName}/source

http://localhost:8080/guvnor-6.0.0.CR3/rest/packages{packageName}/assets/{assetName}/source

The GET method produces MIME-Types:

  • plain/text

The GET method returns the content of rule asset {assetName} contained in package {packageName}. If this is a binary asset, the binary data is returned as a byte array.

The PUT method produces MIME-Types:

  • plain/text

The PUT method updates the source code of the rule asset {assetName} contained in package {packageName}.

/packages/{packageName}/assets/{assetName}/versions

http://localhost:8080/guvnor-6.0.0.CR3/rest/packages{packageName}/assets/{assetName}/versions

The GET method produces MIME-Types:

  • application/atom+xml

The GET method returns the list of rule asset {assetName} versions contained in package {packageName} as an Atom Feed.

/packages/{packageName}/assets/{assetName}/versions/{version}

http://localhost:8080/guvnor-6.0.0.CR3/rest/packages{packageName}/assets/{assetName}/versions/{version}

The GET method produces MIME-Types:

  • application/atom+xml

The GET method returns the metadata of rule asset {assetName} of version {version} contained in package {packageName} as an Atom Entry.

/packages/{packageName}/assets/{assetName}/versions/{version}/source

http://localhost:8080/guvnor-6.0.0.CR3/rest/packages{packageName}/assets/{assetName}/versions/{version}/source

The GET method produces MIME-Types:

  • plain/text

The GET method returns the source code of rule asset {assetName} of version {version} contained in package {packageName} as a text file.

/packages/{packageName}/assets/{assetName}/versions/{version}/binary

http://localhost:8080/guvnor-6.0.0.CR3/rest/packages{packageName}/assets/{assetName}/versions/{version}/binary

The GET method produces MIME-Types:

  • application/octet-stream

The GET method returns the binary content of rule asset {assetName} of version {version} contained in package {packageName}. If this asset has no binary content, the source content is returned instead.

/packages/{packageName}/snapshot/{snapshotName}

http://localhost:8080/guvnor-6.0.0.CR3/rest/packages{packageName}/snapshot/{snapshotName}

The POST method creates a snapshot {snapshotName} for the package {packageName}.



Use the URLs listed below to access rules assets by category. The examples below assume a base URL of http://localhost:8080/guvnor-6.0.0.CR3/rest/

/categories/

http://localhost:8080/guvnor-6.0.0.CR3/rest/categories

The GET method produces MIME-Types:

  • application/json

  • application/xml

The GET method lists all categories.

/categories/{categoryPath}

http://localhost:8080/guvnor-6.0.0.CR3/rest/categories/{categoryPath}

The GET method produces MIME-Types:

  • application/json

  • application/xml

The GET method returns information for a single category.

The PUT method creates a new category with the supplied category path {categoryPath}.

The DELETE method deletes the category with the supplied category path {categoryPath}.

/categories/{categoryPath}/children

http://localhost:8080/guvnor-6.0.0.CR3/rest/categories/{categoryPath}/children

The GET method produces MIME-Types:

  • application/json

  • application/xml

The GET method lists all subcategories under the provided category {categoryPath}.

/categories/{categoryPath}/assets

http://localhost:8080/guvnor-6.0.0.CR3/rest/categories/{categoryPath}/assets

The GET method produces MIME-Types:

  • application/atom+xml

  • application/json

  • application/xml

The GET method returns an Atom feed to all the rule assets that the listed category {category} when the MIME-type is application/atom+xml, and returns a list of asset objects representing rule assets that have the category {categoryPath} when the MIME-Type is either application/json or application/xml.

/categories/{categoryPath}/assets/page/{page}

http://localhost:8080/guvnor-6.0.0.CR3/rest/categories/{categoryPath}/assets/page/{page}

The GET method produces MIME-Types:

  • application/json

  • application/xml

The GET method returns a list of asset objects representing rules assets that have the listed category {categoryPath} and retrieves page {page}, which is a numeric value starting at 1. A page contains 10 elements. If the list contains 20 elements then the list will have 2 pages. Page 1 must be called before page 2 and so on.

We are giving a list of examples 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 in 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 in 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.


In this example we are using Apache Abdera to help parsing and creating Atom Entry and Feed.

Example 9.4. Retrieving all packages contained in the Guvnor repository in Atom Feed format



    public void testGetPackagesForAtom() throws MalformedURLException, IOException {
        URL url = new URL("http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages");
        HttpURLConnection connection = (HttpURLConnection)url.openConnection();
        connection.setRequestProperty("Authorization",
                "Basic " + new Base64().encodeToString(( "admin:admin".getBytes() )));
        connection.setRequestMethod("GET");
        connection.setRequestProperty("Accept", MediaType.APPLICATION_ATOM_XML);
        connection.connect();
        //System.out.println(IOUtils.toString(connection.getInputStream()));
        InputStream in = connection.getInputStream();
        Document<Feed> doc = abdera.getParser().parse(in);
        Feed feed = doc.getRoot();
        System.out.println("BaseUriPath: " + feed.getBaseUri().getPath());
        System.out.println("Title: " + feed.getTitle());
        Iterator<Entry> it = feed.getEntries().iterator();
        while (it.hasNext()) {
            Entry entry = it.next();
            System.out.println("Title: " + entry.getTitle());
            List<Link> links = entry.getLinks();
            System.out.println("Href: " + links.get(0).getHref().getPath());
        }
    }


The client can navigate to specific packages using the package URL retrieved from package list.

Example 9.6. Retrieving the metadata of the specified package as an Atom Entry

    public void testGetPackageForAtom() throws MalformedURLException, IOException {

        URL url = new URL("http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages");
        HttpURLConnection connection = (HttpURLConnection)url.openConnection();
        connection.setRequestProperty("Authorization",
                "Basic " + new Base64().encodeToString(( "admin:admin".getBytes() )));
        connection.setRequestMethod("GET");
        connection.setRequestProperty("Accept", MediaType.APPLICATION_ATOM_XML);
        InputStream in = connection.getInputStream();
        //System.out.println(IOUtils.toString(connection.getInputStream()));
        
        Document<Entry> doc = abdera.getParser().parse(in);
        Entry entry = doc.getRoot();
        System.out.println("BaseUri: " + entry.getBaseUri().getPath());
        System.out.println("Title: " + entry.getTitle());
        System.out.println("Published: " + entry.getPublished());
        System.out.println("Author: " + entry.getAuthor().getName());
        System.out.println("Summary: " + entry.getSummary());
        System.out.println("ContentSrcPath: " + entry.getContentSrc().getPath());
        List<Link> links = entry.getLinks();
        Map<String, Link> linksMap = new HashMap<String, Link>();
        for(Link link : links){
            System.out.println("Link Title: " + link.getTitle());
            System.out.println("Link Path: " + link.getHref().getPath());
            linksMap.put(link.getTitle(), link);
        }
        ExtensibleElement metadataExtension  = entry.getExtension(Translator.METADATA);
        ExtensibleElement archivedExtension = metadataExtension.getExtension(Translator.ARCHIVED);
        System.out.println("ARCHIVED: " + archivedExtension.getSimpleExtension(Translator.VALUE));
        ExtensibleElement uuidExtension = metadataExtension.getExtension(Translator.UUID);
        System.out.println("UUID: " + uuidExtension.getSimpleExtension(Translator.VALUE));
        ExtensibleElement checkinCommentExtension = metadataExtension.getExtension(Translator.CHECKIN_COMMENT);
        System.out.println("CHECKIN_COMMENT: " + checkinCommentExtension.getSimpleExtension(Translator.VALUE));
        ExtensibleElement versionNumberExtension = metadataExtension.getExtension(Translator.VERSION_NUMBER);
        System.out.println("VERSION_NUMBER: " + versionNumberExtension.getSimpleExtension(Translator.VALUE));
    }
    

Example 9.7. Sample message returned from server


<entry xmlns="http://www.w3.org/2005/Atom"
  xml:base="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages">
  <title type="text">mortgages</title>
  <summary type="text">Mortgages that aren't stupid</summary>
  <published>2011-05-02T09:16:16.246Z</published>
  <author>
    <name>mic</name>
  </author>
  <id>http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages
  </id>
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/drools"
    title="drools" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/MortgageModel"
    title="MortgageModel" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/Underage"
    title="Underage" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/Are%20they%20old%20enough"
    title="Are they old enough" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/No%20bankruptcies"
    title="No bankruptcies" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/Bankruptcies"
    title="Bankruptcies" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/Bankruptcy%20history"
    title="Bankruptcy history" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/credit%20ratings"
    title="credit ratings" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/No%20bad%20credit%20checks"
    title="No bad credit checks" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/Good%20credit%20history%20only"
    title="Good credit history only" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/no%20NINJAs"
    title="no NINJAs" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/NINJAs"
    title="NINJAs" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/Pricing%20loans"
    title="Pricing loans" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/Pricing%20low%20end"
    title="Pricing low end" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/Unapprove%20by%20default"
    title="Unapprove by default" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/Dummy%20rule"
    title="Dummy rule" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/ApplicantDsl"
    title="ApplicantDsl" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/CreditScoreApproval"
    title="CreditScoreApproval" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/CreditApproval"
    title="CreditApproval" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/DateDslRule"
    title="DateDslRule" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/RegexDslRule"
    title="RegexDslRule" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/DSLWithDate"
    title="DSLWithDate" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/myws"
    title="myws" rel="asset" />
  <metadata xmlns="">
    <archived>
      <value>false</value>
    </archived>
    <uuid>
      <value>da98caef-e1c4-4f98-880c-46a740c9131f</value>
    </uuid>
    <state>
      <value></value>
    </state>
    <versionNumber>
      <value>2</value>
    </versionNumber>
    <checkinComment>
      <value>Mortgages that aren't stupid</value>
    </checkinComment>
  </metadata>
  <content src="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/binary" />
</entry>



Retrieving package metadata with specified version as an Atom Entry.

Example 9.12. Retrieving package metadata with specified version as an Atom Entry



    public void testGetHistoricalPackageForAtom() throws MalformedURLException, IOException {
        URL url = new URL("http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5");
        HttpURLConnection connection = (HttpURLConnection)url.openConnection();
        connection.setRequestProperty("Authorization",
                "Basic " + new Base64().encodeToString(( "admin:admin".getBytes() )));
        connection.setRequestMethod("GET");
        connection.setRequestProperty("Accept", MediaType.APPLICATION_ATOM_XML);
        connection.connect();
        //System.out.println(IOUtils.toString(connection.getInputStream()));
        InputStream in = connection.getInputStream();
        Document<Entry> doc = abdera.getParser().parse(in);
        Entry entry = doc.getRoot();
        System.out.println("BaseUri: " +  entry.getBaseUri().getPath());
        System.out.println("Title: " + entry.getTitle());
        System.out.println("Summary: " +  entry.getSummary());
        System.out.println("ContentSrc: " +  entry.getContentSrc().getPath());
        List<Link> links = entry.getLinks();
        Map<String, Link> linksMap = new HashMap<String, Link>();
        for(Link link : links){
            System.out.println("Link Title: " + link.getTitle());
            System.out.println("Link Path: " + link.getHref().getPath());
            linksMap.put(link.getTitle(), link);
        }
        ExtensibleElement metadataExtension  = entry.getExtension(Translator.METADATA);
        ExtensibleElement archivedExtension = metadataExtension.getExtension(Translator.ARCHIVED);
        System.out.println("ARCHIVED: " + archivedExtension.getSimpleExtension(Translator.VALUE));
        ExtensibleElement uuidExtension = metadataExtension.getExtension(Translator.UUID);
        System.out.println("UUID: " + uuidExtension.getSimpleExtension(Translator.VALUE));
        ExtensibleElement checkinCommentExtension = metadataExtension.getExtension(Translator.CHECKIN_COMMENT);
        System.out.println("CHECKIN_COMMENT: " + checkinCommentExtension.getSimpleExtension(Translator.VALUE));
        ExtensibleElement versionNumberExtension = metadataExtension.getExtension(Translator.VERSION_NUMBER);
        System.out.println("VERSION_NUMBER: " + versionNumberExtension.getSimpleExtension(Translator.VALUE));
    }

Example 9.13. Sample message returned from server


<entry xmlns="http://www.w3.org/2005/Atom"
  xml:base="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5">
  <title type="text">mortgages</title>
  <summary type="text">update package description</summary>
  <published>2012-04-26T09:36:11.588Z</published>
  <author>
    <name>admin</name>
  </author>
  <id>http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5
  </id>
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/drools"
    title="drools" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/MortgageModel"
    title="MortgageModel" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/Underage"
    title="Underage" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/Are%20they%20old%20enough"
    title="Are they old enough" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/No%20bankruptcies"
    title="No bankruptcies" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/Bankruptcies"
    title="Bankruptcies" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/Bankruptcy%20history"
    title="Bankruptcy history" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/credit%20ratings"
    title="credit ratings" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/No%20bad%20credit%20checks"
    title="No bad credit checks" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/Good%20credit%20history%20only"
    title="Good credit history only" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/no%20NINJAs"
    title="no NINJAs" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/NINJAs"
    title="NINJAs" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/Pricing%20loans"
    title="Pricing loans" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/Pricing%20low%20end"
    title="Pricing low end" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/Unapprove%20by%20default"
    title="Unapprove by default" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/Dummy%20rule"
    title="Dummy rule" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/ApplicantDsl"
    title="ApplicantDsl" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/CreditScoreApproval"
    title="CreditScoreApproval" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/CreditApproval"
    title="CreditApproval" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/DateDslRule"
    title="DateDslRule" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/RegexDslRule"
    title="RegexDslRule" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/DSLWithDate"
    title="DSLWithDate" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/myws"
    title="myws" rel="asset" />
  <metadata xmlns="">
    <archived>
      <value>false</value>
    </archived>
    <uuid>
      <value>8c4ed0f7-a034-4411-98ed-3e7fc3af994a</value>
    </uuid>
    <state>
      <value></value>
    </state>
    <versionNumber>
      <value>5</value>
    </versionNumber>
    <checkinComment>
      <value>update package description</value>
    </checkinComment>
  </metadata>
  <content
    src="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/binary" />
</entry>

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-6.0.0.CR3/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.