This section covers the technical aspects of Guvnor (previously known as the Business Rules Management System or BRMS), it is not necessary to use this if you are integrating or an end user of the BRMS application. However, Drools is open source, so build instructions form part of the manual.
You may want to build from source if you want to re-use components, or embed the application within another.
The above diagram shows the major components of the system and how they integrate and are deployed. The User Guide has more details on the parts that are highly configurable (eg database).
The BRMS is deployed as a war, which provides user interfaces over the web, and provides binary packages via URLs (or files). It utilized the JSR-170 standard for data storage (JCR). JBoss Seam is used as the component framework, and GWT is used as the widget toolkit for constructing the ajax based web user interface.
This section will go over the steps necessary to build various components. Mostly this is automated, but the manual process is described for thoroughness.
There are 2 modules: drools-repository (back end) and drools-guvnor (front end and rules integration). The drools-guvnor module depends on the drools-repository module, as well as other components. Guvnor is part of the main build for all of Drools - when building Drools, Guvnor is built alongside it.
Maven 2 is used as the build system. To get started, the WHOLE of the source tree for JBoss Rules will need to be checked out. This includes the other modules, and the top level lib and repository directories (which are needed by the build); as the BRMS build is part of the main drools build.
Initially, go into the root of the jboss-rules checked out source tree, and run mvn install to install all the components for the inter project dependencies. If the build is broken (all care is taken for this eventuality not to occur), the flag -Dmaven.test.skip=true can be used to prevent failing unit tests from preventing the build.
When wishing to build the BRMS, go into the drools-jbrms
directory, and run mvn package
. This will run the tests,
and then build a deployable war. The only thing this will not do is
rebuild the GWT front end (see the next section for details on that).
Once the war file is in the target directory, the BRMS is ready to
go.
The GUI widgets for the web front end are developed with GWT
(Google Web Toolkit). If there is a need to make changes to or build the
GUI, GWT will need to be downloaded separately. Once GWT is downloaded,
the build.properties
file in the drools-jbrms
directory to point to where GWT is installed. Once this is completed,
the ant tasks can be used to build the GWT components, as well as launch
GWT in debug/hosted mode if it is desired. If running the build, it will
update the webapp directory in the project with the new
compiled artifacts (GWT does not use JSP, only html
and javascript at runtime).
Each module has a ready to go and up to date eclipse project
configuration, so they can merely be imported into the eclipse
workspace. These projects are generated by Maven (mvn
eclipse:eclipse
to refresh them in case they are wrong or
outdated). They have been manually modified to have project dependencies
(this means the code can be stepped through when debugging).
Some environment variables are required in eclipse (for Window: >Preferences->Java->Build path->Classpath variables): the M2_REPO, as normal, to point to where Maven downloads shared dependencies. GWT_HOME should point to where you installed GWT. GWT_DEV must point to the platform specific "dev" jar that ships with the version of GWT you have.
How to launch from Eclipse: unit tests can be launched, as normal
(in which case only M2_REPO setup is needed, GWT does not need to be
downloaded seperately), or it can be launched it in hosted
mode using the GWT browser, which is great for debugging
(from GUI to back end, the code can be stepped through, and changes made
on the fly and simply hit refresh). There is a
Guvnor.launch
file in in the drools-jbrms
directory. To launch Guvnor in debug mode, open the Run dialog
(Run->Run), and then choose JBRMS from the list.
Launching this will open a new window, with the BRMS in debug mode,
ready to go
Normally
Downloading and debugging the BRMS with GWT is optional, so if there are no GUI issues being worked on then this step can be safely skipped.
The BRMS uses a service interface to separate the GUI from the back end functionality. In this case the back end both includes the asset repository (drools-repository and JCR) as well as the compiler specifics to deal with rules.
The main interface is RepositoryService, which is implemented in
ServiceImplementation. The GWT ajax front end talks to this interface (via
the asynchrony callback mechanism that GWT uses). The seam configuration
file is components.xml
(consult Seam documentation,
and the components.xml file for details).
This service interface may be re-used by alternative components or front ends.
The GWT user interface may be re-used, as it is GWT is only one html
page: Guvnor.html
.
Normally Guvnor is intended to be deployed as its own war, however it can be combined with another application (with some care), but it is easier to keep it as a separate war. Deploying Guvnor by itself will also make it easier to upgrade to newer releases as they come out (and is recommended).
The JBRMS.html
file can be customized. For
example to change logos or embed the BRMS in another page. Take a look at
the Guvnor.html
file for details.
The User Guide, Admin Section covers configuration options in some detail, for database and filesystems.
Versions of assets are stored in the database along with the data.
When snapshots are created, copies are made of the entire package into a separate location in the JCR database.
For those familiar with jcr and jackrabbit, the *.cnd files are in the source for the node type definitions as some wish to view these. In a nutshell, a package is a folder and each asset is a file: an asset can either be textual or have a binary attachment.
As an open source project, contributions from the wider community are encouraged. In order to contribute consult the wiki and project home pages. A useful way to contribute is via logging issues or feature requests in JIRA. The JIRA link to use is: https://jira.jboss.org/jira/browse/GUVNOR