Forthcoming; extension beyond W3C Standard Schema processing.
This document is included in the zip download as readme.htm.
zip file contents: The zip file contains this page (as readme.htm), the DRL schema
set, and tools (batch and script in html file) for running W3C Standard XML Schema processors.
The schema processors themselves are not included, but may be downloaded from other sites.
All Rights Reserved
Copyright © 2004 Roger F. Gay
Intelligent Systems Research Corporation
Document Information
This document is included in the zip download as readme.htm.
Document Status: Complete
Original Document Date: October 19, 2004
Last Document Change: October 22, 2004
Last Schema Modification: October 30, 2004
Document Location:
http://www.geocities.com/rogerfgay/drltk/instructions.htm
Target Audience: Drools developers, drools application developers, and systems
managers involved in managing use of drools applications.
Subject: This version of the DRL XML Schema set has been developed according to the DRL
specification of drools release 2.0-BETA-1.7 (October, 2004) It is a modification
of the DRL XML Schema developed by the same author (for drools version 1 BETA) that was made
available to the drools community in September, 2003. This document provides some general
background on drools, drl, and schema, and detailed information on installation, use,
and maintenance of the drools DRL schema set.
Document Author: Roger F. Gay
Document Last Updated By: Roger F. Gay
Schema Author: Roger F. Gay
Schema Last Updated By: Roger F. Gay
All Rights Reserved
Copyright © 2004 Roger F. Gay
Intelligent Systems Research Corporation
This is an Open Source document that supports Open Source code. It may be
redistributed as is, or with changes that are documented by including the date(s) of
change(s), the name(s) of person(s) who made the change(s), and note(s) describing the
change(s) that were made, so long as the original document and schema author and
original copyright notice are included in the changed version of the document.
The Original Author, Roger F. Gay
would appreciate being notified of changes, especially those that improve the document,
but notifying the Original Author of changes is not required.
Feel free to report any errors or deficiencies.
About Drools and DRL
Drools is an Open Source, high-powered rule processing system written in the Java
programming language. Rule bases for applications are stored in W3C Standard XML
files written in the Drools Rule Language (DRL). The DRL schema set (the
subject of this document) consists of schemata written in accordance with the
W3C XML Schema Standard
that define the structure of and relationships within DRL files.
You may use this document whether or not you are not familiar with drools, DRL
files, and rule engines if you need to install or maintain DRL schemata or validate
existing DRL files. If you are interested in learning about rule processing and the
drools rule processing engine, it is best to start with the articles and tutorials
at the drools project website. If you are looking
for a basic tutorial on W3C Standard Schema,
W3C Schools is a good place to start.
DRL is an XML-based language that uses modern XML features such as XML-Namespaces
and XML Schema. DRL files are XML files that use DRL tags. DRL files are typically
named with suffix .drl. drools requires that they be accessible through a URL:
- Local File System
DRL files can be stored in a local file system and accessed using file://
URLs.
- Web/FTP Server
DRL files can be stored on the Internet and accessed using http:// and
ftp:// URLs.
- Java Classpath
DRL files can be stored in the Java classpath or in a JAR file, and accessed
using the getResource() method on java.lang.ClassLoader and
java.lang.Class classes.
The base semantics of a DRL file include the top-level "rule-set" which contains
any number of rules. Parameters and declarations within rules contain objects that
are processed by drools at run-time to provide data that is tested by the rules.
A particularly interesting feature of drools is that the inner contents of some of
the rule elements, such as the condition and consequence elements that make up the
fundamentally important "if-then" part of the rule specification, are "semantic-
module-independent." (The drools Guide, The Werken Company, July 11, 2003)
This means that drools is designed to allow the use of any language – even a custom
language defined for an application world like general business management or nuclear
power-plant management – for the inner content of some of its elements.
The current version of drools (2.0-BETA-1.7) supports three general programming
language semantic modules; for java, python, and groovy. (BETA 1 supported
java, python, and jelly.) The existing support for general programming languages
means that a wide variety of applications can be built immediately, without defining
a new application specific language. The fact that three different semantic modules
are supported (historical total: four) demonstrates the semantic flexibility of drools.
It can also present interesting challenges in schema development and maintenance and
in system management. Handled well, drools can add an exceptional level of power and
intelligence to automated systems.
Open Source License Agreement
Copyright 2004 (C) Roger F. Gay. All Rights Reserved.
Intelligent Systems Research Corporation
This schema is the original work of Roger F. Gay ( rogerfgay@yahoo.com ),
provided as a contribution to the drools Open Source project
( http://www.drools.org ). This schema may be redistributed, subject to
the conditions that appropriate written notification of this author's contribution
is included in every copy and derivative of this schema by including this
statement along with your statement of changes if any, and by including the above
copyright notice and an author acknowledgment in documentation associated with
any redistribution of this schema or derivative of this schema. This schema is
provided "as is" without warranty of any kind. Neither Roger F. Gay nor
Intelligent Systems Research Corporation nor the drools Open Source project
are liable for any use of this schema.
Feedback regarding errors and improvements would be appreciated.
About this Version
This version of the DRL XML Schema set has been developed according to the DRL
specification of drools release 2.0-BETA-1.7 (October, 2004) It is a modification
of the DRL XML Schema developed for version 1 BETA that was made available to the
drools community in September, 2003.
This version replaces all previous versions of the drools DRL schema. This version
has been verified using MS, Xerces, XSV, and XMLmind W3C Standard Schema processing
tools and has successfully validated all DRL sample files available in the drools
code base at the time of release. The validity of the DRL sample file set was
confirmed by the drools development team (including empty rule-sets).
This version is designed to perform the most stringent checking of DRL file structure.
Every tag and tag attribute is specified, including those defined for the java, python,
and groovy semantic modules. The base schema (drl.xsd) also specifies a test to
see that each (java, python, or groovy) extractor.target attribute matches a
parameter.identifier or declaration.identifier attribute.
Content within semantic module tags is defined as text. This schema set does not
specify any test to validate application objects within semantic module tags. Work
is underway however, to provide deeper validation with the addition of non-W3C-Standard
schema processing.
Use of tags defined for semantic modules other than java, python, and groovy is
strictly prohibited in this version of the base schema. Instructions in this
document however, explain how support for additional semantic modules may be added
to the base schema and how support for semantic modules prohibited for an application
may be removed.
Download the DRL Schema Set
You may download the DRL schema set and instructions in a
zip file.
The schema set is Open Source. You may use and distribute the source code
free of charge, subject to the Open Source License Agreement
that is included in the schema files.
Basically, you are required to acknowledge the author and include acknowledgment
and the license agreement with any and all distribution of the code or any derivative.
In other words, do not delete the license agreement and author information from the
source code. Just add comments to document any changes you make. In addition to being
honest, that will help you adapt to any new versions that become available, because
you will have documented specific differences between the versions on your site and
the originals. You, your clients, and your company will have the information needed
for successful and efficient maintenance, even if it involves adopting to a major
new drools release with a new DRL format.
Additional tools and extensions to DRL logic that make use of the schema are also
in the works by independent developers such as myself. Making systematic adjustments
to the schema set with proper documentation intact will avoid chaos in the flow of
work and processing related to the schema and simplify integration of future tools
and extensions.
Installing the Schemata
You may place the DRL base schema (drl.xsd) wherever you wish, so long as it is
accessible when you run a schema processor. In other sections of this document
(Preparing your DRL files and DRL File Validation)
there are instructions for specifying the location of the base schema. A reasonable
suggestion for placement of the base schema is {schemas}/org/drools/rule/,
where {schemas} is your system's schemas subdirectory. This location corresponds to
class locations for drools. The base schema corresponds to the classes in subdirectory
{classes}/org/drools/rule/.
You may place the other semantic support schemata (java.xsd, python.xsd, and groovy.xsd)
anywhere you wish, so long as they are accessible when you run a schema processor.
Specify the locations of the other semantic specific schemata in the base schema
(drl.xsd) as described below.
{It is recommended that you complete this next step even if you are aware of and
prefer alternative approaches. This installation does not rely on other components
for semantic specific schemata locations. Once this installation is verified,
you can create custom versions to your specifications.}
<xs:import namespace="http://drools.org/semantics/java"
schemaLocation="anyURI/java.xsd" />
<xs:import namespace="http://drools.org/semantics/python"
schemaLocation="anyURI/python.xsd" />
<xs:import namespace="http://drools.org/semantics/groovy"
schemaLocation="anyURI/groovy.xsd" />
Use the complete file path (anyURI / filename) to specify
schemaLocation, indicating where you have placed the schemata for
the semantic modules (corresponding to supported programming languages).
It is best to carefully place all three semantic support schemata and specify
all three locations when you first install the schemata whether or not you
currently intend to use all three. Once you have verified the
complete installation (making use of sample DRL files that came with drools),
you can create custom versions of the base schema according to instructions in
this document:
Removing Semantic Module Support and
Adding a New Semantic Module.
Note that if support for a specific language is not completely
removed, then the location of its corresponding schema must be specified.
If you are installing on a local machine, the URI will
look something like the following examples.
C:/user/xml/schemas/org/drools/semantics/java/java.xsd
C:/user/xml/schemas/org/drools/semantics/python/python.xsd
C:/user/xml/schemas/org/drools/semantics/groovy/groovy.xsd
Note that forward slashed (/) are used even if you are running in the MS Windows OS.
A path specification that uses backslashes (\) is not valid in this context.
If you are installing on an Internet server and will access through http,
the URI will look something like the following examples.
http://www.picslt.org/user/xml/schemas/org/drools/semantics/java/java.xsd
http://www.picslt.org/user/xml/schemas/org/drools/semantics/python/python.xsd
http://www.picslt.org/user/xml/schemas/org/drools/semantics/groovy/groovy.xsd
Preparing your DRL files
Installing the Schemata explains that the base schema
(drl.xsd) must be located in a place that is accessible when you run a schema
processor, and also suggests a subdirectory. To prepare your DRL files for
schema processing, you need to define namespaces, define the DRL file as
an XMLSchema-instance, and specify the schemaLocation of the
base schema (drl.xsd).
{If sample DRLs that you find in the
zip download
fail to validate, check the schema location as explained below.}
<?xml version="1.0"?>
<rule-set name="Your Choice Of Names"
xmlns="http://drools.org/rules"
xmlns:java="http://drools.org/semantics/java"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://drools.org/rules anyURI/drl.xsd">
</rule-set>
If you are installing on a local machine, the file path will
look something like the following example.
C:/user/xml/schemas/org/drools/rule/drl.xsd
Note that forward slashed (/) are used even if you are running in the MS Windows OS.
A path specification that uses backslashes (\) is not valid in this context.
If you are installing on an Internet server and will access through http,
the URL will look something like the following examples.
http://www.picslt.org/user/xml/schemas/org/drools/rule/drl.xsd
DRL File Validation
Use drl_msxsd.htm to run the Microsoft XML validator, which is the easiest to use and I
think most convenient for quick checks while writing a DRL file. Modify validate.bat
to use Xerces 2 or XSV. Modifying the batch file involves changing paths to the location
of your Xerces or XSV jar files. Validate.bat can also run IBM's schema processor.
I have not used the IBM processor, and only know that it uses online components.
To run drl_msxsd.htm, you have to make sure that the JavaScript line
var xsd_files = new Array("drl.xsd");
knows where drl.xsd is. If drl.xsd is not in the same directory as drl_msxsd.htm,
modify the argument to provide the path to drl.xsd (using forward slashes /).
You of course have to have Microsoft's XML processing software installed for this to work.
Just try it first. If you don't have it, there's a link on the html page
that tells you where to get the download. It's easy to install and use, and it was
certainly free when I got it - I assume it still is.
Specifying the location of the base schema (drl.xsd) may seem to conflict with
instructions in Preparing your DRL files. You have already
been instructed to specify the location of the base schema in your DRL files. The
specification of the location of the base schema in the MS schema processor script
overrides the specification in the DRL file and is a feature of the processor
script. It is possible to re-write the script in a number of ways and additional
MS Schema processor scripts might be provided in the future if there is sufficient
demand.
The current version of the MS Schema processor script will check a DRL file
that does not specify a schema.
<?xml version="1.0"?>
<rule-set name="fibonacci"
xmlns="http://drools.org/rules"
xmlns:java="http://drools.org/semantics/java">
<!-- without XMLSchema-instance and schemaLocation -->
...
You can still verify the base schema location in your DRL files by copy-pasting
the schemaLocation of the base schema to the MS Schema processor
script or by running one of the other (strict validation) schema processors
without providing a schema location as an argument.
Adding a New Semantic Module
To adapt the schema set to allow use of an alternative semantic module, a new
semantic module specific schema must be created and the base schema (drl.xsd)
must be modified. The base schema provided with this download supports java,
python, and groovy semantics. So it provides examples of exactly what
needs to be specified and how. This instruction relies on the fact that there
is existing support for semantics in the base schema, asking that you
search for and duplicate existing semantic support elements.
- Create a semantic module specific schema. See java.xsd, python.xsd, and
groovy.xsd for examples.
- Add a semantic module namespace specification to the xs:schema tag in drl.xsd.
Java, python, and groovy namespace specifications are examples in this version of
drl.xsd.
- Add an import element for the new semantic module schema. Java, python, and
groovy import specifications are examples in this version of drl.xsd.
- Search for use of a semantic module namespace. (java:, python:, or groovy:)
For every reference to existing specialized semantic module namespace
(java:, python:, groovy:), consider whether the new semantic module supports
that element. (extractor, condition, consequence, class) If the new semantic
module supports the element, duplicate one copy of the element and change
the namespace reference. (For example: dog:extractor rather than java:extractor
if "dog" refers to your new namespace)
If your application requires use of the new semantic module for
some elements, it would be a good idea to delete support for
alternatives while executing step #4. To completely remove support for one or
more semantic modules, see Removing Semantic Module Support
in this document.
Removing Semantic Module Support
If you wish to remove some but not all support for a particular
semantic module, apply the delete instruction that follows step #4 in section
Adding a New Semantic Module of this document.
This section explains how to completely remove support for a semantic
module, thereby prohibiting any reference to elements of that semantic
module in a DRL.
Modify the base schema (drl.xsd) as follows to completely eliminate support
for a semantic module.
- Delete the semantic module specific namespace declaration from the xs:schema element.
- Delete the semantic module specific xs:import element.
- Remove the semantic module specific reference to the extractor element from
keyref "targetToIdentifier".
- Search and delete all elements that are defined in the specific semantic module
namespace. For example, searching for "java:", "python:", or "groovy:" will yield
the elements that are defined in the java, python, or groovy semantic module namespaces.
Acknowledgements
Thanks to drools users and developers for their encouragement during development
of the BETA release of the schema set for the original version of DRL.
If it had not been for the interest of Bob McWhirter of
The Werken Company,
I would probably not have proceeded on drools schema development with as
much gusto. From the experience, I have become confident that schema
development is extremely important. I believe its importance will be demonstrated
during future development of drools; with the foresight of drools and application
developers who work with the schemata, down the road as system managers face
requirements for traffic control, by innovative developments related to DRLs and
schema related tools, and probably all of the above.
I would also like to thank W3C Schools
for providing beginning W3C Schema tutorials to everyone who has access to the
Internet, and Roger L. Costello for contributions to advanced Schema education.
At this point, we all must admit that it kind-of looks like some of the
W3C Standards might just work out.
User Feedback and Discussion
The author welcomes feedback, comments, thanks, congratulations, and civilized
how-do-you-do-s via
email.
Drools users, developers, and watchers can also provide feedback and discuss all
drools related issues by joining the
drools community.