Documentation

-Starting to document building, deploying and utilising KIE

kie-docs/shared/KIE/BuildDeployUtilizeAndRun.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<chapter version="5.0" xml:id="BuildDeployUtilizeAndRunChapter"
+<section version="5.0" xml:id="BuildDeployUtilizeAndRunSection"
   xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd"
   xml:base="./" xmlns="http://docbook.org/ns/docbook" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xlink="http://www.w3.org/1999/xlink"
@@ -8,4 +8,4 @@
 
   <!--xi:include href="Overview.xml" /-->
 
-</chapter>
+</section>

kie-docs/shared/KIE/BuildDeployUtilizeAndRun/Build.xml

@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section version="5.0" xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd" 
+  xml:base="./../../" xml:id="KIEBuildSection" xmlns="http://docbook.org/ns/docbook" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:ns2="http://www.w3.org/1998/Math/MathML" xmlns:ns="http://docbook.org/ns/docbook">
+  <title>Build</title>
+  <para>6.0 introduces a new configuration and convention approach to building knowledge bases,
+    instead of the using the programmatic builder approach in 5.x. Atlhough a builder is still
+    available for fall back on, as it's used for the tooling integration.</para>
+  <para>Building now uses Maven, and aligns with Maven practices. A KIE projcet or module is simply
+    a Maven java project or module; with an additional meta data file 'META-INF/kmodule.xml'. The
+    'kmodule.xml' file is the descriptor that selects resources to knowledge bases and configures
+    those knowledge bases and sessions. There is also alternative xml support via Spring and OSGi
+    BluePrints.</para>
+  <para>While standard Maven can be build and package KIE resources, it will not provide validation
+    at build time.  There is a Maven plugin which is recommend to use to get build time validation.
+    The plugin also pre-genenerates many classes, making the runtime loading faster too.</para>
+  <para>KIE uses defaults to minimise the amount of configuration. With an empty kmodule.xml being
+    the simplest configuration. There must always be a kmodule.xml file, even if empty, as it's used
+    for discover of the jar and it's contents.</para>
+  <para>KieServices</para>
+  <para>KieModule</para>
+  <para>KieContainer</para>
+  <para>KieBase</para>
+  <para>KieSession</para>
+  <para>The best way to learn the new build system is by example. The source project
+    "drools-examples-api" contains a number of examples, and can be found at github:</para>
+  <para><link xlink:href="https://github.com/droolsjbpm/drools/tree/6.0.x/drools-examples-api"
+      >https://github.com/droolsjbpm/drools/tree/6.0.x/drools-examples-api</link></para>
+  <para>The next setions summarise those examples</para>
+  <section> <title>Empty kmodule.xml</title>
+    <para>An empty kmodule.xml will produce a single knowledge base that includes all files found
+      under resources path, be it DRL, BPMN2, XLS etc.</para>
+    <para>location: META-INF/kmodule.xml</para><programlisting language="XML">
+<![CDATA[<kmodule xmlns="http://jboss.org/kie/6.0.0/kmodule"> </kmodule>]]>
+  </programlisting>
+    <para>The example project layout and maven pom descriptor is illustarted in the screenshot</para>
+    <figure>
+      <title>Example project layout and maven pom</title>
+      <screenshot>
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="images/kie/BuildDeployUtilizeAndRun/defaultkiesession.png" />
+          </imageobject>
+        </mediaobject>
+      </screenshot>
+    </figure>
+    <para>To build and deploy to the local maven repository simply type:</para>
+    <programlisting>mvn install</programlisting>
+    <para>This will build the maven and install artefact and run the unit test. The test shows </para>
+    <programlisting language="JAVA">public class DefaultKieSessionExample {
+
+    public void go(PrintStream out) {
+        KieServices ks = KieServices.Factory.get();
+        KieContainer kContainer = ks.getKieClasspathContainer();
+
+        KieSession kSession = kContainer.newKieSession();
+        kSession.setGlobal("out", out);
+        kSession.insert(new Message("Dave", "Hello, HAL. Do you read me, HAL?"));
+        kSession.fireAllRules();
+    }
+
+
+    public static void main(String[] args) {
+        new DefaultKieSessionExample().go(System.out);
+    }
+
+}</programlisting>
+    <para/>
+    <para/>
+  </section>  
+</section>

kie-docs/shared/KIE/KIE.xml

@@ -6,7 +6,8 @@
   xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:ns="http://docbook.org/ns/docbook">
   <title>KIE</title>
 
-  <xi:include href="BuildDeployUtilizeAndRun.xml" />
+
   <xi:include href="Overview.xml" />
+  <xi:include href="BuildDeployUtilizeAndRun.xml" />
 
 </chapter>

kie-docs/shared/KIE/Overview/Anatomy.xml

@@ -12,7 +12,7 @@
     <title>KIE Anatomy</title>
     <mediaobject>
       <imageobject>
-        <imagedata fileref="images/KIE/Overview/kie.png"/>
+        <imagedata fileref="images/kie/Overview/kie.png"/>
       </imageobject>
     </mediaobject>
   </figure>