[jboss-svn-commits] JBL Code SVN: r24452 - in labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook: en-US/Chapter-API and 10 other directories.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Sat Dec 20 18:52:13 EST 2008
Author: KrisVerlaenen
Date: 2008-12-20 18:52:13 -0500 (Sat, 20 Dec 2008)
New Revision: 24452
Added:
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-API/
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-API/Chapter-API.xml
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-ProcessModel/
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-ProcessModel/Chapter-ProcessModel.xml
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-API/
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-API/AuditView.png
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-Eclipse/drools-runtimes-add.png
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-Eclipse/drools-runtimes-add2.png
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-Eclipse/drools-runtimes-newproject.png
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-Eclipse/drools-runtimes-project.png
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-Eclipse/drools-runtimes.png
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-Eclipse/drools-runtimes2.png
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-Eclipse/drools-runtimes3.png
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-Introduction/process.bmp
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-ProcessModel/
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-ProcessModel/ProcessInstanceModel.png
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-ProcessModel/ProcessModel.png
Modified:
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Eclipse/Chapter-Eclipse.xml
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Flow/Chapter-RuleFlow.xml
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-GettingStarted/Chapter-GettingStarted.xml
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Introduction/Chapter-Introduction.xml
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/master.xml
Log:
- added more Drools Flow documentation
Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-API/Chapter-API.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-API/Chapter-API.xml (rev 0)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-API/Chapter-API.xml 2008-12-20 23:52:13 UTC (rev 24452)
@@ -0,0 +1,145 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter version="5.0" xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns:m="http://www.w3.org/1998/Math/MathML"
+ xmlns:html="http://www.w3.org/1999/xhtml"
+ xmlns:db="http://docbook.org/ns/docbook" xml:base="./">
+
+ <title>Drools Flow API</title>
+
+ <section>
+ <title>Knowledge Base</title>
+
+ <para>Our knowledge-based API allows you to first create a knowledge base
+ that contains all the necessary knowledge. This includes of course all the
+ relevant process definitions, but also other knowledge types like rules. The
+ following code snippet shows how to create a knowledge base consisting of only
+ one process definition: use a knowledge builder to add a resource, check for
+ errors and create the knowledge base.</para>
+
+<programlisting>
+KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
+kbuilder.add(ResourceFactory.newClassPathResource("ruleflow.rf"), ResourceType.DRF);
+KnowledgeBuilderErrors errors = kbuilder.getErrors();
+if (errors.size() > 0) {
+ for (KnowledgeBuilderError error: errors) {
+ System.err.println(error);
+ }
+ throw new IllegalArgumentException("Could not parse knowledge.");
+}
+KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();
+kbase.addKnowledgePackages(kbuilder.getKnowledgePackages());
+</programlisting>
+
+ <para>Note that the knowledge-based API allows users to add different types of
+ resources (e.g. rules and processes) in almost identical ways into the same
+ knowledge base. This allows user that know how to user Drools Flow to start using
+ Expert of Fusion (and even integrate these different types of knowledge) almost
+ instantaniously.</para>
+
+ </section>
+
+ <section>
+ <title>Session</title>
+
+ <para>Next, you should create a session to interact with the engine. Again, the
+ API is knowledge-based, supporting different types of knowledge, with a specific
+ extension for each knowledge type. The following code snippet shows how easy it
+ is to create a session based on the earlier created knowledge base and start a
+ process.</para>
+
+<programlisting>
+StatefulKnowledgeSession ksession = kbase.newStatefulKnowledgeSession();
+ProcessInstance processInstance = ksession.startProcess("com.sample.ruleflow");
+</programlisting>
+
+ <para>The ProcessRuntime interface defines all the methods on the session for
+ interacting with processes, as shown below. Check out the JavaDocs to get a detailed
+ explanation for each of the methods.</para>
+
+<programlisting>
+ProcessInstance startProcess(String processId);
+ProcessInstance startProcess(String processId, Map<String, Object> parameters);
+void signalEvent(String type, Object event);
+Collection<ProcessInstance> getProcessInstances();
+ProcessInstance getProcessInstance(long id);
+WorkItemManager getWorkItemManager();
+</programlisting>
+
+ </section>
+
+ <section>
+ <title>Events</title>
+
+ <para>Both the stateful and stateless knowledge session provide methods for
+ registering (and removing) listeners. ProcessEventListeners can be used to
+ listen to process-related events, like starting or completing a processes and
+ triggering and leaving a node. Below the different methods of a
+ ProcessEventListener are shown. The event object provides access to related
+ information like the process instance and/or node instance linked to the event.
+ </para>
+
+<programlisting>
+public interface ProcessEventListener {
+
+ void beforeProcessStarted(ProcessStartedEvent event);
+ void afterProcessStarted(ProcessStartedEvent event);
+ void beforeProcessCompleted(ProcessCompletedEvent event);
+ void afterProcessCompleted(ProcessCompletedEvent event);
+ void beforeNodeTriggered(ProcessNodeTriggeredEvent event);
+ void afterNodeTriggered(ProcessNodeTriggeredEvent event);
+ void beforeNodeLeft(ProcessNodeLeftEvent event);
+ void afterNodeLeft(ProcessNodeLeftEvent event);
+
+}
+</programlisting>
+
+ <para>An audit log can be created based on the information provided by these process
+ listeners. We provide various default logger implementations:
+ <orderedlist>
+ <listitem>Console logger: This logger writes out all the events to the console.</listitem>
+ <listitem>File logger: This logger writes out all the events to a file using an
+ XML representation. This log file can then for example be used in the IDE to generate
+ a tree-based visualization of the events that occured during execution.</listitem>
+ <listitem>Threaded file logger: Because a file logger only writes the events to disk
+ when closing the logger (or when the number of events in the logger reaches a predefined
+ level), it cannot be used when debugging processes at runtime. A threaded file logger
+ writes out the events to file at a specified time interval, making it possible to use
+ the logger for example to visualize the progress when debugging processes in realtime.
+ </listitem>
+ </orderedlist>
+ </para>
+
+ <para>The KnowledgeRuntimeLoggerFactory can be used to easily add a logger to your session,
+ as shown below. When creating a console logger, the knowledge session for which the logger
+ needs to be created needs to be passes as an argument. The file logger also requires the
+ name of the log file to be created, and the threaded file logger requires the interval (in
+ milliseconds) after which the events should be saved.</para>
+
+<programlisting>
+KnowledgeRuntimeLogger logger = KnowledgeRuntimeLoggerFactory.newFileLogger(ksession, "test");
+// add invocations to the process engine here, e.g. ksession.startProcess(processId);
+...
+logger.close();
+</programlisting>
+
+ <para>The log file can be opened in the Eclipse when using the Audit View in the Drools
+ Eclipse plugin, where the events are visualized in a tree-based manner (events that occur
+ between the before and after event are shown as children of that event). The following
+ screenshot shows a simple example, where a process is started, resulting in the triggering
+ of the start node, an action node and an end node, after which the process was completed.
+ </para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" format="PNG" role=""
+ fileref="images/Chapter-API/AuditView.png"/>
+ </imageobject>
+ </mediaobject>
+
+ </section>
+
+
+</chapter>
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-API/Chapter-API.xml
___________________________________________________________________
Name: svn:executable
+ *
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Eclipse/Chapter-Eclipse.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Eclipse/Chapter-Eclipse.xml 2008-12-20 20:45:28 UTC (rev 24451)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Eclipse/Chapter-Eclipse.xml 2008-12-20 23:52:13 UTC (rev 24452)
@@ -13,6 +13,138 @@
might be interesting for developers.</para>
<section>
+ <title>Drools Runtimes</title>
+
+ <para>A Drools runtime is a collection of jars on your file system that represent
+ one specific release of the Drools project jars. To create a runtime, you must
+ point the IDE to the release of your choice. If you want to create a new runtime
+ based on the latest Drools project jars included in the plugin itself, you can also
+ easily do that. You are required to specify a default Drools runtime for your
+ Eclipse workspace, but each individual project can override the default and select
+ the appropriate runtime for that project specifically.</para>
+
+ <section>
+ <title>Defining a Drools runtime</title>
+
+ <para>You are required to define one or more Drools runtimes using the Eclipse preferences
+ view. To open up your preferences, in the menu Window select the Preferences
+ menu item. A new preferences dialog should show all your preferences. On the
+ left side of this dialog, under the Drools category, select "Installed Drools
+ runtimes". The panel on the right should then show the currently defined Drools
+ runtimes. If you have not yet defined any runtimes, it should like something like
+ the figure below.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/Chapter-Eclipse/drools-runtimes.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
+
+ <para>To define a new Drools runtime, click on the add button. A dialog as shown
+ below should pop up, requiring the name for your runtime and the location on your
+ file system where it can be found.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/Chapter-Eclipse/drools-runtimes-add.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
+
+ <para>In general, you have two options:</para>
+ <orderedlist>
+ <listitem><para>If you simply want to use the default jars as included in the Drools
+ Eclipse plugin, you can create a new Drools runtime automatically by clicking the
+ "Create a new Drools 5 runtime ..." button. A file browser will show up, asking
+ you to select the folder on your file system where you want this runtime to be
+ created. The plugin will then automatically copy all required dependencies to
+ the specified folder. After selecting this folder, the dialog should look like
+ the figure shown below.</para></listitem>
+
+ <listitem><para>If you want to use one specific release of the Drools project, you should
+ create a folder on your file system that contains all the necessary Drools libraries
+ and dependencies. Instead of creating a new Drools runtime as explained above, give
+ your runtime a name and select the location of this folder containing all the required
+ jars.</para></listitem>
+ </orderedlist>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/Chapter-Eclipse/drools-runtimes-add2.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
+
+ <para>After clicking the OK button, the runtime should show up in your table of installed
+ Drools runtimes, as shown below. Click on checkbox in front of the newly created runtime
+ to make it the default Drools runtime. The default Drools runtime will be used as the
+ runtime of all your Drools project that have not selected a project-specific runtime.
+ </para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/Chapter-Eclipse/drools-runtimes2.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
+
+ <para>You can add as many Drools runtimes as you need. For example, the screenshot below
+ shows a configuration where three runtimes have been defined: a Drools 4.0.7 runtime, a
+ Drools 5.0.0 runtime and a Drools 5.0.0.SNAPSHOT runtime. The Drools 5.0.0 runtime is
+ selected as the default one.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/Chapter-Eclipse/drools-runtimes3.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
+
+ <para>Note that you will need to restart Eclipse if you changed the default runtime and
+ you want to make sure that all the projects that are using the default runtime update
+ their classpath accordingly.</para>
+
+ </section>
+
+ <section>
+ <title>Selecting a runtime for your Drools project</title>
+
+ <para>Whenever you create a Drools project (using the New Drools Project wizard or by
+ converting an existing Java project to a Drools project using the "Convert to Drools
+ Project" action that is shown when you are in the Drools perspective and you right-click
+ an existing Java project), the plugin will automatically add all the required jars to
+ the classpath of your project.</para>
+
+ <para>When creating a new Drools project, the plugin will automatically use the default
+ Drools runtime for that project, unless you specify a project-specific one. You can do
+ this in the final step of the New Drools Project wizard, as shown below, by deselecting
+ the "Use default Drools runtime" checkbox and selecting the appropriate runtime in the
+ drop-down box. If you click the "Configure workspace settings ..." link, the workspace
+ preferences showing the currently installed Drools runtimes will be opened, so you can
+ add new runtimes there.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/Chapter-Eclipse/drools-runtimes-newproject.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
+
+ <para>You can change the runtime of a Drools project at any time by opening the project
+ properties (right-click the project and select Properties) and selecting the Drools
+ category, as shown below. Check the "Enable project specific settings" checkbox and select
+ the appropriate runtime from the drop-down box. If you click the "Configure workspace
+ settings ..." link, the workspace preferences showing the currently installed Drools
+ runtimes will be opened, so you can add new runtimes there. If you deselect the "Enable
+ project specific settings" checkbox, it will use the default runtime as defined in your
+ global preferences.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/Chapter-Eclipse/drools-runtimes-project.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
+
+ </section>
+
+ </section>
+
+ <section>
<title>Process skins</title>
<para>We have introduced the concept of a (process) skin, which controls how the
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Flow/Chapter-RuleFlow.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Flow/Chapter-RuleFlow.xml 2008-12-20 20:45:28 UTC (rev 24451)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Flow/Chapter-RuleFlow.xml 2008-12-20 23:52:13 UTC (rev 24452)
@@ -102,9 +102,9 @@
<programlisting>
<?xml version="1.0" encoding="UTF-8"?>
-<process xmlns="http://drools.org/drools-4.0/process"
+<process xmlns="http://drools.org/drools-5.0/process"
xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
- xs:schemaLocation="http://drools.org/drools-4.0/process drools-processes-4.0.xsd"
+ xs:schemaLocation="http://drools.org/drools-5.0/process drools-processes-5.0.xsd"
type="RuleFlow" name="ruleflow" id="com.sample.ruleflow" package-name="com.sample" >
<header>
@@ -152,23 +152,23 @@
<para>This is a simple example of a basic process with a ruleset node only:
<programlisting>
- RuleFlowProcessFactory factory =
- RuleFlowProcessFactory.createProcess("org.drools.HelloWorldRuleSet");
- factory
- // Header
- .name("HelloWorldRuleSet")
- .version("1.0")
- .packageName("org.drools")
- // Nodes
- .startNode(1).name("Start").done()
- .ruleSetNode(2)
- .name("RuleSet")
- .ruleFlowGroup("someGroup").done()
- .endNode(3).name("End").done()
- // Connections
- .connection(1, 2)
- .connection(2, 3);
- RuleFlowProcess process = factory.validate().getProcess();
+ RuleFlowProcessFactory factory =
+ RuleFlowProcessFactory.createProcess("org.drools.HelloWorldRuleSet");
+ factory
+ // Header
+ .name("HelloWorldRuleSet")
+ .version("1.0")
+ .packageName("org.drools")
+ // Nodes
+ .startNode(1).name("Start").done()
+ .ruleSetNode(2)
+ .name("RuleSet")
+ .ruleFlowGroup("someGroup").done()
+ .endNode(3).name("End").done()
+ // Connections
+ .connection(1, 2)
+ .connection(2, 3);
+ RuleFlowProcess process = factory.validate().getProcess();
</programlisting>
</para>
@@ -207,28 +207,28 @@
<para>This example is using Split and Join nodes:
<programlisting>
- RuleFlowProcessFactory factory =
- RuleFlowProcessFactory.createProcess("org.drools.HelloWorldJoinSplit");
- factory
- // Header
- .name("HelloWorldJoinSplit")
- .version("1.0")
- .packageName("org.drools")
- // Nodes
- .startNode(1).name("Start").done()
- .splitNode(2).name("Split").type(Split.TYPE_AND).done()
- .actionNode(3).name("Action 1").action("mvel", "System.out.println(\"Inside Action 1\")").done()
- .actionNode(4).name("Action 2").action("mvel", "System.out.println(\"Inside Action 2\")").done()
- .joinNode(5).type(Join.TYPE_AND).done()
- .endNode(6).name("End").done()
- // Connections
- .connection(1, 2)
- .connection(2, 3)
- .connection(2, 4)
- .connection(3, 5)
- .connection(4, 5)
- .connection(5, 6);
- RuleFlowProcess process = factory.validate().getProcess();
+ RuleFlowProcessFactory factory =
+ RuleFlowProcessFactory.createProcess("org.drools.HelloWorldJoinSplit");
+ factory
+ // Header
+ .name("HelloWorldJoinSplit")
+ .version("1.0")
+ .packageName("org.drools")
+ // Nodes
+ .startNode(1).name("Start").done()
+ .splitNode(2).name("Split").type(Split.TYPE_AND).done()
+ .actionNode(3).name("Action 1").action("mvel", "System.out.println(\"Inside Action 1\")").done()
+ .actionNode(4).name("Action 2").action("mvel", "System.out.println(\"Inside Action 2\")").done()
+ .joinNode(5).type(Join.TYPE_AND).done()
+ .endNode(6).name("End").done()
+ // Connections
+ .connection(1, 2)
+ .connection(2, 3)
+ .connection(2, 4)
+ .connection(3, 5)
+ .connection(4, 5)
+ .connection(5, 6);
+ RuleFlowProcess process = factory.validate().getProcess();
</programlisting>
</para>
@@ -243,34 +243,34 @@
<para>Now we show a more complex example with a ForEach node, where we have nested nodes:
<programlisting>
- RuleFlowProcessFactory factory =
- RuleFlowProcessFactory.createProcess("org.drools.HelloWorldForeach");
- factory
- // Header
- .name("HelloWorldForeach")
- .version("1.0")
- .packageName("org.drools")
+ RuleFlowProcessFactory factory =
+ RuleFlowProcessFactory.createProcess("org.drools.HelloWorldForeach");
+ factory
+ // Header
+ .name("HelloWorldForeach")
+ .version("1.0")
+ .packageName("org.drools")
+ // Nodes
+ .startNode(1).name("Start").done()
+ .forEachNode(2)
+ // Properties
+ .linkIncomingConnections(3)
+ .linkOutgoingConnections(4)
+ .collectionExpression("persons")
+ .variable("child", new ObjectDataType("org.drools.Person"))
// Nodes
- .startNode(1).name("Start").done()
- .forEachNode(2)
- // Properties
- .linkIncomingConnections(3)
- .linkOutgoingConnections(4)
- .collectionExpression("persons")
- .variable("child", new ObjectDataType("org.drools.Person"))
- // Nodes
- .actionNode(3)
- .action("mvel", "System.out.println(\"inside action1\")").done()
- .actionNode(4)
- .action("mvel", "System.out.println(\"inside action2\")").done()
- // Connections
- .connection(3, 4)
- .done()
- .endNode(5).name("End").done()
+ .actionNode(3)
+ .action("mvel", "System.out.println(\"inside action1\")").done()
+ .actionNode(4)
+ .action("mvel", "System.out.println(\"inside action2\")").done()
// Connections
- .connection(1, 2)
- .connection(2, 5);
- RuleFlowProcess process = factory.validate().getProcess();
+ .connection(3, 4)
+ .done()
+ .endNode(5).name("End").done()
+ // Connections
+ .connection(1, 2)
+ .connection(2, 5);
+ RuleFlowProcess process = factory.validate().getProcess();
</programlisting>
</para>
@@ -290,51 +290,63 @@
<title>Using a process in your application</title>
<para>There are two things you need to do to be able to execute processes from
- within your application: (1) you need to create a rulebase that contain
+ within your application: (1) you need to create a knowledge base that contain
the definition of the process; and (2) you need to start the process by creating
a session to communicate with the process engine and start the process.</para>
<orderedlist>
- <listitem><para><emphasis>Creating a rulebase</emphasis>: Once you
- have a valid process, you can add a process to a package (just like adding a rule):
+ <listitem><para><emphasis>Creating a knowledge base</emphasis>: Once you
+ have a valid process, you can add the process to the knowledge base (note
+ that this is almost identical to adding rules to the knowledge base, except
+ for the type of knowledge added):</para>
<programlisting>
-PackageBuilder builder = new PackageBuilder();
-Reader processReader = ... (process reader, select your *.rf file here)
-builder.addProcessFromXml(processReader);</programlisting>
- Alternatively, you can upload the .rf file to Guvnor (as a
- process asset) and it will automatically be included in packages that are
- deployed from it.</para>
- <para>Next you need to create a rulebase that contains all the necessary rules
- and processes, like this:
+KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
+kbuilder.add(ResourceFactory.newClassPathResource("MyProcess.rf"), ResourceType.DRF);</programlisting>
+ <para>After adding all your knowledge to the builder (you can add more than one
+ process or even rules), you should probably check whether the process (and/or rules)
+ have been parsed correctly and write out any errors like this:</para>
<programlisting>
-RuleBase ruleBase = RuleBaseFactory.newRuleBase();
-ruleBase.addPackage(builder.getPackage());</programlisting>
- </para></listitem>
+KnowledgeBuilderErrors errors = kbuilder.getErrors();
+if (errors.size() > 0) {
+ for (KnowledgeBuilderError error: errors) {
+ System.err.println(error);
+ }
+ throw new IllegalArgumentException("Could not parse knowledge.");
+}</programlisting>
+ <para>Next you need to create the knowledge base that contains all the necessary
+ processes (and rules) like this:</para>
+ <programlisting>
+KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();
+kbase.addKnowledgePackages(kbuilder.getKnowledgePackages());</programlisting>
+ </listitem>
<listitem><para><emphasis>Starting a process</emphasis>: Processes are only executed
if you explicitly state that they should be executed. This is because you could
- potentially define a lot of processes in your rulebase and the engine has no way
+ potentially define a lot of processes in your knowledge base and the engine has no way
to know when you would like to start each of these. To activate a particular process,
you will need to start the process by calling the startProcess method on your session.
For example:
- <programlisting>StatefulSession session = ruleBase.newStatefulSession();
-session.startProcess("com.sample.MyProcess");</programlisting>
+ <programlisting>
+StatefulKnowledgeSession ksession = kbase.newStatefulKnowledgeSession();
+ksession.startProcess("com.sample.MyProcess");</programlisting>
The parameter of the startProcess method represents the id of the process that needs to
be started (the process id needs to be specified as a property of the process, which are
shown in the properties view when you click the background canvas of your process).
If your process also requires the execution of rules during the execution of the process,
- you also need to call the session.fireAllRules() method. Thats it !</para>
- <para>You can also specify additional parameters that are used to pass on additional data
+ you also need to call the ksession.fireAllRules() method to make sure the rules are
+ executed as well. That's it!</para>
+ <para>You can also specify additional parameters that are used to pass on input data
to the process, using the startProcess(String processId, Map parameters)
- method, that takes an additional set of parameters as name-value pairs.
+ method, that takes an additional set of parameters as name-value pairs. These parameters
+ are then copied to the newly created process instance as top-level variables of the process.
+ </para>
+ <para>You can also start a process from within a rule consequence, using
+ <programlisting>kcontext.getKnowledgeRuntime().startProcess("com.sample.MyProcess");</programlisting>
</para></listitem>
</orderedlist>
- <para>You can also start a process from within a rule consequence using
- <programlisting>drools.getWorkingMemory().startProcess("...");</programlisting>
- </para>
</section>
<section>
@@ -452,6 +464,10 @@
<para>Discriminator means that it continues if one of its incoming branches has been completed.
</para>
</listitem>
+ <listitem>
+ <para>n-of-m means that it continues if n of its m incoming branches have been completed. The n variable could either be hardcoded to a fixed value, or could also refer to a process variable that will contain the number of incoming branches to wait for.
+ </para>
+ </listitem>
</itemizedlist>
It contains the following properties:
</para>
@@ -459,6 +475,7 @@
<listitem><para><emphasis>Id</emphasis>: The id of the node (which is unique within one node container).</para></listitem>
<listitem><para><emphasis>Name</emphasis>: The display name of the node.</para></listitem>
<listitem><para><emphasis>Type</emphasis>: The type of the join node, t.e. AND, XOR or Discriminator (see above).</para></listitem>
+ <listitem><para><emphasis>n</emphasis>: The number of incoming connections to wait for (in case of a n-of-m join).</para></listitem>
</itemizedlist>
</listitem>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-GettingStarted/Chapter-GettingStarted.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-GettingStarted/Chapter-GettingStarted.xml 2008-12-20 20:45:28 UTC (rev 24451)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-GettingStarted/Chapter-GettingStarted.xml 2008-12-20 23:52:13 UTC (rev 24452)
@@ -11,31 +11,31 @@
will guide you to create and execute your first Drools Flow process.</para>
<section>
- <title>Installation</title>
+ <title>Installation</title>
+
<para>The best way to get started is to use the Drools Eclipse Plugin. This
is a plugin for the Eclipse development environment that allows users to
- create, execute and debug Drools processes and rules.</para>
-
- <para>To get started, you need an Eclipse 3.4.x, as well as the Eclipse
- Graphical Editing Framework (GEF) plugin installed. Eclipse can be downloaded
- from:</para>
+ create, execute and debug Drools processes and rules. To get started with the
+ plugin, you first need an Eclipse 3.4.x (as well as the Eclipse
+ Graphical Editing Framework (GEF) plugin installed). Eclipse can be downloaded
+ from the following link (if you do not know which version of eclipse you need,
+ simply choose the "Eclipse IDE for Java Developers", and this one already includes
+ the GEF plugin as well):</para>
<para><ulink url="http://www.eclipse.org/downloads/">http://www.eclipse.org/downloads/</ulink></para>
- <para>If you do not know which version you need, simply choose the "Eclipse IDE
- for Java Developers". This one already includes the GEF plugin as well.</para>
<para>Next you need to install the Drools Eclipse plugin. There are two ways to do
this, (1) manually downloading and installing the plugin or (2) using the Drools
Eclipse update site.</para>
- <para><emphasis role="strong">Manual download:</emphasis> Download the Drools Eclipse IDE plugin from:</para>
+ <para><emphasis role="strong">Manual download:</emphasis> Download the Drools Eclipse
+ IDE plugin from the link below. Unzip the downloaded file in your main eclipse folder
+ (so that the feature and plugin jars end up in the features and plugin directory of
+ eclipse) and (re)start Eclipse.</para>
<para><ulink url="http://www.jboss.org/auth/drools/downloads.html">http://www.jboss.org/auth/drools/downloads.html</ulink></para>
- <para>Unzip the downloaded file in your main eclipse folder (so that the feature
- and plugin jars end up in the features and plugin directory of eclipse) and
- (re)start Eclipse.</para>
- <para><emphasis role="strong">Using the update site:</emphasis> Open up Eclipse, and in the "Help" menu,
- select "Software Updates ...", and in the "Available Software" tab, click the
- "Add Site ..." button. TODO </para>
+ <para><emphasis role="strong">Using the update site:</emphasis> Open up Eclipse,
+ and in the "Help" menu, select "Software Updates ...", and in the "Available Software"
+ tab, click the "Add Site ..." button. TODO: all link + explanation for update site.</para>
<para>To check that the installation was successful, try opening the Drools perspective:
Click the 'Open Perspective' button in the top right corner of your Eclipse window,
@@ -45,18 +45,13 @@
<section>
<title>Creating your first process</title>
- <para>If you haven't done so already, you should switch to the Drools perspective within
- Eclipse first, as this will open all the relevant views for you. You can do this by
- clicking on the Open Perspective button (top right of your screen), select "Other ..."
- and pick the Drools perspective.</para>
-
<para>A new Drools project wizard can be used to set up an executable project that contains
the necessary files to get started easily with defining and executing processes. This wizard
will setup a basic project structure, the classpath, a sample process and execution code to
- get you started. To create a new Drools Project, select "File" -> "New" -> "Project ..." and in
- the Drools folder, select Drools Project. As an alternative, you could also simply left-click
- on the Drools action button (with the Drools head) in the Eclipse toolbar and select
- "New Drools Project". This should open the following dialog:</para>
+ get you started. To create a new Drools Project, simply left-click on the Drools action button
+ (with the Drools head) in the Eclipse toolbar and select "New Drools Project". Alternatively,
+ you could also select "File" -> "New" -> "Project ..." and in the Drools folder, select Drools
+ Project. This should open the following dialog:</para>
<mediaobject>
<imageobject>
@@ -162,9 +157,9 @@
<programlisting>
<?xml version="1.0" encoding="UTF-8"?>
-<process xmlns="http://drools.org/drools-4.0/process"
+<process xmlns="http://drools.org/drools-5.0/process"
xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
- xs:schemaLocation="http://drools.org/drools-4.0/process drools-processes-4.0.xsd"
+ xs:schemaLocation="http://drools.org/drools-5.0/process drools-processes-5.0.xsd"
type="RuleFlow" name="ruleflow" id="com.sample.ruleflow" package-name="com.sample" >
<header>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Introduction/Chapter-Introduction.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Introduction/Chapter-Introduction.xml 2008-12-20 20:45:28 UTC (rev 24451)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Introduction/Chapter-Introduction.xml 2008-12-20 23:52:13 UTC (rev 24452)
@@ -5,8 +5,67 @@
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml"
- xmlns:db="http://docbook.org/ns/docbook" >
+ xmlns:db="http://docbook.org/ns/docbook" xml:base="./">
<title>Introduction</title>
- <para>Drools Flow is a workflow and process engine that allows
- advanced integration of processes and rules.</para>
+ <para>Drools Flow is a workflow or process engine that allows
+ advanced integration of processes and rules. A process or a
+ workflow describes the order in which a series of steps need
+ to be executed, using a flow chart. For example, the following
+ figure shows a process where first Task1 and Task2 need to be
+ executed in parallel. After completion of both, Task3 needs to
+ be executed.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" format="BMP" role=""
+ fileref="images/Chapter-Introduction/process.bmp"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>The following chapters will learn you everything you need
+ to know about Drools Flow. It's distinguishing characteristics
+ are:
+ <orderedlist>
+ <listitem><emphasis role="strong">Advanced integration of processes
+ and rules:</emphasis> Processes and rules are usually considered as
+ two different paradigms when it comes to defining business logic.
+ While loose coupling between a processes and rules is possible by
+ integrating both a process and a rules engine, we provide advanced
+ integration of processes and rules out-of-the-box. This allows
+ users to use rules to define part of their business logic when
+ defining their business processes and vice versa.</listitem>
+ <listitem><emphasis role="strong">Unification of processes and
+ rules:</emphasis> We consider rules, processes and event processing
+ all as different types of knowledge. Not only do we allow the advanced
+ integration of these three types, we also offer a unified API and
+ unified tooling so that users should not learn three different products
+ but can easily combine these three types using our knowledge-based API.
+ The tooling also allows seamless integration of these different kinds of
+ knowledge, including things like a unified knowledge repository, audit
+ logs, debugging, etc.</listitem>
+ <listitem><emphasis role="strong">Declarative modelling:</emphasis>
+ Drools Flow tries to keep processes as declarative as possible, i.e.
+ focussing on what should happen instead of how. As a result, we try
+ to avoid having to hardcode details into your process but offer ways
+ to describe your work in an abstract way (e.g. using pluggable work
+ items, a business scripting language, etc.). We also allows users
+ to easily create domain-specific extension, making it much easier to
+ read, update or create these processes as they are using
+ domain-specific concepts that are closely related to the problem you
+ are trying to solve and can be understood by domain experts.</listitem>
+ <listitem><emphasis role="strong">Generic process engine supporting
+ multiple process languages:</emphasis> We do not believe that there
+ is one process language that fits all purposes. Therefore, the Drools
+ Flow engine is based on a generic process engine that allows the
+ definition and execution of different types of process languages, like
+ for example our RuleFlow language, WS-BPEL (a standard targeted towards
+ web service orchestration), OSWorkflow (another existing workflow
+ language), jPDL (the process language defined by the jBPM project), etc.
+ All these languages are based on the same set of core building blocks,
+ making it easier to implement your own process language by reusing and
+ combining these low-level building blocks the way you want to.</listitem>
+ </orderedlist>
+ All these features (and many more) will be explained in the following
+ chapters.
+ </para>
</chapter>
Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-ProcessModel/Chapter-ProcessModel.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-ProcessModel/Chapter-ProcessModel.xml (rev 0)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-ProcessModel/Chapter-ProcessModel.xml 2008-12-20 23:52:13 UTC (rev 24452)
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter version="5.0" xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns:m="http://www.w3.org/1998/Math/MathML"
+ xmlns:html="http://www.w3.org/1999/xhtml"
+ xmlns:db="http://docbook.org/ns/docbook" xml:base="./">
+
+ <title>Drools Flow process model</title>
+
+ <para></para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" format="PNG" role=""
+ fileref="images/Chapter-ProcessModel/ProcessModel.png"/>
+ </imageobject>
+ </mediaobject>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" format="PNG" role=""
+ fileref="images/Chapter-ProcessModel/ProcessInstanceModel.png"/>
+ </imageobject>
+ </mediaobject>
+
+</chapter>
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-ProcessModel/Chapter-ProcessModel.xml
___________________________________________________________________
Name: svn:executable
+ *
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/master.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/master.xml 2008-12-20 20:45:28 UTC (rev 24451)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/master.xml 2008-12-20 23:52:13 UTC (rev 24452)
@@ -52,6 +52,8 @@
<xi:include href="Chapter-Introduction/Chapter-Introduction.xml" />
<xi:include href="Chapter-GettingStarted/Chapter-GettingStarted.xml" />
<xi:include href="Chapter-Flow/Chapter-RuleFlow.xml" />
+ <xi:include href="Chapter-API/Chapter-API.xml" />
+ <xi:include href="Chapter-ProcessModel/Chapter-ProcessModel.xml" />
<xi:include href="Chapter-RulesAndProcesses/Chapter-RulesAndProcesses.xml" />
<xi:include href="Chapter-DomainSpecificProcesses/Chapter-DomainSpecificProcesses.xml" />
<xi:include href="Chapter-HumanTasks/Chapter-HumanTasks.xml" />
Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-API/AuditView.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-API/AuditView.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-Eclipse/drools-runtimes-add.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-Eclipse/drools-runtimes-add.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-Eclipse/drools-runtimes-add2.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-Eclipse/drools-runtimes-add2.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-Eclipse/drools-runtimes-newproject.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-Eclipse/drools-runtimes-newproject.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-Eclipse/drools-runtimes-project.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-Eclipse/drools-runtimes-project.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-Eclipse/drools-runtimes.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-Eclipse/drools-runtimes.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-Eclipse/drools-runtimes2.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-Eclipse/drools-runtimes2.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-Eclipse/drools-runtimes3.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-Eclipse/drools-runtimes3.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-Introduction/process.bmp
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-Introduction/process.bmp
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-ProcessModel/ProcessInstanceModel.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-ProcessModel/ProcessInstanceModel.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-ProcessModel/ProcessModel.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-ProcessModel/ProcessModel.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
More information about the jboss-svn-commits
mailing list