[jboss-svn-commits] JBL Code SVN: r22534 - labs/jbossrules/trunk/drools-docs/drools-docs-guvnor/en/Chapter-Guvnor.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Tue Sep 9 02:59:02 EDT 2008
Author: michael.neale at jboss.com
Date: 2008-09-09 02:59:01 -0400 (Tue, 09 Sep 2008)
New Revision: 22534
Added:
labs/jbossrules/trunk/drools-docs/drools-docs-guvnor/en/Chapter-Guvnor/running_execution_server.png
Modified:
labs/jbossrules/trunk/drools-docs/drools-docs-guvnor/en/Chapter-Guvnor/Section-UserGuide.xml
Log:
added section on rule execution server
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-guvnor/en/Chapter-Guvnor/Section-UserGuide.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-guvnor/en/Chapter-Guvnor/Section-UserGuide.xml 2008-09-09 06:58:15 UTC (rev 22533)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-guvnor/en/Chapter-Guvnor/Section-UserGuide.xml 2008-09-09 06:59:01 UTC (rev 22534)
@@ -1448,6 +1448,230 @@
</section>
<section>
+ <title>Drools execution server</title>
+
+ <para>The drools execution server (drools-server) module is a war which
+ you can deploy to execute knowledgebases (rulebases) remotely for any
+ sort of client application. This is not limited to JVM application
+ clients, but any technology that can use HTTP, and either XML or JSON.
+ Currently this execution server is for stateless sessions (which also
+ makes it easy to scale out).</para>
+
+ <para>A "restful" style of interface is provided, with URLs defining
+ what knowledgebase is being accessed. Client applications then execute
+ knowledgebases remotely via HTTP(S). The rule execution server uses the
+ rule agent described in the sections above.</para>
+
+ <section>
+ <title>Configuration and deployment</title>
+
+ <para>drools-server is a war file, which can be deployed in a
+ application server (such as JBoss AS). As the service is stateless, it
+ is possible to have have as many of these services deployed as you
+ need to serve the client load. The war file should be expanded to a
+ folder for deployment (which will be clear later) - so you can deploy
+ this as a folder called drools-server.war.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="running_execution_server.png"
+ format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+
+ <para>Once the war has been deployed, you should be able to go to
+ http://localhost:8080/drools-server and see a page like the above
+ (obviously substitute a correct server address). The page shown should
+ provide information on how to use it, and indicates that it is
+ healthy.</para>
+
+ <para>To configure a "knowledgebase" - you create a properties file
+ with a rule agent configuration in it (see the section above for
+ details on the options in the rule agent configuration). The name of
+ this properties file will be the name in the URL that you use to
+ access this servive. So lets take the example of
+ teamallocation.properties: an agent configuration for a service that
+ will allocated some piece of work to a team. teamallocation.properties
+ should contain details on what packages are to be loaded, and from
+ where.</para>
+
+ <para>Place teamallocation.properties in the WEB-INF/classes directory
+ in the war directory (and restart the server if needed). Importantly,
+ you will ALSO need any jar files that your rules need placed in the
+ WEB-INF/lib directory of each execution server instance (eg your
+ model, if you are using pojo models, or supporting classes if needed -
+ you may not need any). Typically if you are using the execution
+ server, your client code will not use a object model jar to talk to
+ the service so</para>
+
+ <para>Once this is done, the server is accessed via a url of the
+ pattern: http://your-server/drools-server/knowledgebase/{agent
+ configuration name}. So in the example above it would be:
+ <programlisting>http://your-server/drools-server/knowledgebase/teamallocation</programlisting>
+ You can see from this that you can have as many agents configured as
+ you like, perhaps for many concurrent versions of
+ knowledgebases.</para>
+ </section>
+
+ <section>
+ <title>Consuming the service</title>
+
+ <para>Consuming the service is quite simple, you need to choose to use
+ either XML or JSON. By default XML is used, but by setting the
+ Content-Type HTTP header to application/json, JSON will be used (JSON
+ can be more performant in some circumstances).</para>
+
+ <para>Client libraries: one of the nice things about a REST service is
+ that no special client libraries are required, regardless of the
+ langugae used. In java however, Apache commons "HttpClient" is
+ recommended as an easier API to use then the defaults. Only HTTP is
+ required (of course https can be used for secure transport if on an
+ untrusted network).</para>
+
+ <para>A sample request:</para>
+
+ <programlisting><knowledgebase-request>
+ <globals>
+ <named-fact>
+ <id>myglobal</id>
+ <fact class="org.drools.server.ExampleFact">
+ <carType>Saab</carType>
+ <carPrice>42</carPrice>
+ </fact>
+ </named-fact>
+ </globals>
+ <inOutFacts>
+ <named-fact>
+ <id>myfact</id>
+ <fact class="org.drools.server.ExampleFact">
+ <carType>BMW</carType>
+ <carPrice>50</carPrice>
+ </fact>
+ </named-fact>
+ </inOutFacts>
+ <inFacts>
+ <anon-fact>
+ <fact class="org.drools.server.ExampleFact">
+ <carType>Audi</carType>
+ <carPrice>55</carPrice>
+ </fact>
+ </anon-fact>
+ <anon-fact>
+ <fact class="org.drools.server.ExampleFact">
+ <carType>Mercedes</carType>
+ <carPrice>65</carPrice>
+ </fact>
+ </anon-fact>
+ </inFacts>
+</knowledgebase-request></programlisting>
+
+ <para>Elements of the request: note that there are 3 parts: globals,
+ inOutFacts and inFacts. Both globals and inOutFacts are returned in
+ the response message. Globals and inOutFacts are named (each name must
+ be unique) for this purpose (in the case of globals, the name of the
+ global is the name used in the rules). The "id" tag is used for the
+ name. Note that the "fact" tag refers to a fact as used by the
+ knowledgebase - the fields inside that enclosing tag are defined by
+ the fact class itself. If a fact class has a nested class, then the
+ data for that nested data would show up as <nestedFactFieldName>
+ - where nestedFactFieldName is the name of the field in the "parent"
+ class. Inside that tag are the tags with the values of the fields for
+ that nested data (the class name is not needed as that is derived from
+ the parent fact).</para>
+
+ <para>A sample response:</para>
+
+ <programlisting><knowledgebase-response>
+ <globals>
+ <named-fact>
+ <id>myglobal</id>
+ <fact class="org.drools.server.ExampleFact">
+ <carType>Saab</carType>
+ <carPrice>42</carPrice>
+ </fact>
+ </named-fact>
+ </globals>
+ <inOutFacts>
+ <named-fact>
+ <id>myfact</id>
+ <fact class="org.drools.server.ExampleFact">
+ <carType>BMW</carType>
+ <carPrice>50</carPrice>
+ </fact>
+ </named-fact>
+ </inOutFacts>
+</knowledgebase-response></programlisting>
+
+ <para>Elements of response: Similar to the request (note the enclosing
+ tags are different) - of course only the global and inOutFacts have
+ their state returned.</para>
+
+ <para>JSON: (Javascript Object Notation) follows the same basic object
+ graph layout as the requests above. Some notes: in JSON, @class is
+ used to indicate the type of the fact that the rules use. Also, in
+ javascript, associative arrays (maps) are indicated by "{" and "}",
+ and arrays via "[" and "]". In some cases, if there would be a list
+ (array) but only 1 element of data is present, then "[" will not be
+ shown. eg {"a" : "b"} can have the same meaning as [{"a" : "b"}] in
+ results.</para>
+
+ <para>A sample request:</para>
+
+ <programlisting>{"knowledgebase-request":
+{"globals":{"named-fact":{"id":"myglobal","fact":{"@class":"org.drools.server.ExampleFact","carType":"Saab","carPrice":42}}},
+"inOutFacts":{"named-fact":{"id":"myfact","fact":{"@class":"org.drools.server.ExampleFact","carType":"BMW","carPrice":50}}},
+"inFacts":{"anon-fact":[{"fact":{"@class":"org.drools.server.ExampleFact","carType":"Audi","carPrice":55}},{"fact":{"@class":"org.drools.server.ExampleFact","carType":"Mercedes","carPrice":65}}]}}}</programlisting>
+
+ <para>A sample response:</para>
+
+ <programlisting>{"knowledgebase-response":
+{"globals":{"named-fact":{"id":"myglobal","fact":{"@class":"org.drools.server.ExampleFact","carType":"Saab","carPrice":42}}},
+"inOutFacts":{"named-fact":{"id":"myfact","fact":{"@class":"org.drools.server.ExampleFact","carType":"BMW","carPrice":50}}}}}</programlisting>
+
+ <para>Following is an example code snippet showing how a knowledgebase
+ is accessed using JSON from Ruby:</para>
+
+ <programlisting>
+ require 'json'
+ http = Net::HTTP.new('localhost', 8080)
+ path = "/drools-server/knowledgebase/teamallocation"
+ post_data = {"knowledgebase-request" => {
+ :globals => {"named-fact" => [{:id => "a", :fact => {"@class" => "teamallocation.Assignment"}}]},
+ :inFacts => {"anon-fact" => [{:fact => {"@class" => "teamallocation.Claim", "value" => 150}}]},
+ :inOutFacts => {"named-fact" => [{:id => "x", :fact => {"@class" => "teamallocation.Team", "specialty" => "FATAL"}},
+ {:id => "y", :fact => {"@class" => "teamallocation.Team"}}]}
+ }
+ }
+ headers = {
+ "Content-Type" => "application/json"
+ }
+ resp, data = http.post(path, post_data.to_json, headers)
+
+
+ answer = JSON.parse(data)
+ #digging out the results:
+ puts answer["knowledgebase-response"]["globals"]["named-fact"]["fact"]["teamName"]
+ #if there is more then one fact, they are a list
+ puts answer["knowledgebase-response"]["inOutFacts"]["named-fact"][0]["fact"]["specialty"]
+</programlisting>
+ </section>
+ </section>
+
+ <section>
+ <title>JMS, SOAP/WSDL integration</title>
+
+ <para>A stateless rule execution server may not be enough for your
+ needs. If you require WSDL+SOAP, JMS or other integration, JBoss ESB
+ (http://www.jboss.org/JBossESB/) can be used.</para>
+
+ <para>The esb can provide stateful and stateless rule services via
+ multiple transport mechanisms (such as http/soap, or JMS, and many many
+ more) as needed. Load balancing, failover, monitoring and more is also
+ provided. Refer to the ESB site (http://www.jboss.org/JBossESB/) for
+ more information on this (it will not be covered in this manual).</para>
+ </section>
+
+ <section>
<title>Manual deployment</title>
<para>This section is only needed for advanced users who are integrating
@@ -1471,39 +1695,49 @@
<section>
<title>WebDAV and HTTP</title>
- <para>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.
- </para>
+
+ <para>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.</para>
+
<section>
<title>WebDAV</title>
+
<figure>
<title>Windows webdav</title>
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="WebDAVWindows.png"
- format="PNG" scalefit="1" />
+ <imagedata align="center" fileref="WebDAVWindows.png" format="PNG"
+ scalefit="1" />
</imageobject>
</mediaobject>
</figure>
- <para>
- In windows the "web folders" feature can be used. On OSX - the free cyberduck client can work well.
- To access the repository as webdav, you the url is the same as the web interface, only with /webdav at the end, instead of Guvnor.html.
- Authentication will be required to get access this way.
- This will show a packages and snapshots directory - the snapshots directory is read only (a view of created snapshots of packages). The packages directory will contain a list of packages in the repository, drilling in to them will show the individual assets as files.
- </para>
+
+ <para>In windows the "web folders" feature can be used. On OSX - the
+ free cyberduck client can work well. To access the repository as webdav,
+ you the url is the same as the web interface, only with /webdav at the
+ end, instead of Guvnor.html. Authentication will be required to get
+ access this way. This will show a packages and snapshots directory - the
+ snapshots directory is read only (a view of created snapshots of
+ packages). The packages directory will contain a list of packages in the
+ repository, drilling in to them will show the individual assets as
+ files.</para>
</section>
<section>
<title>URLs</title>
- <para>
- There are a few other URLs which are handy to know exist.
-The package deployment URL mentioned in the section about rule agent deployment also has a few other features:
-By appending .drl to the end of a URL, you will show the generated DRL for that package.
-eg: /package/testPDSGetPackage/LATEST.drl - will show the DRL (not the binary package) for the latest package.
-Further to this, you can append /assetName.drl - and it will show the generated DRL for that item. (even if it isn't a drl file).
-eg /package/testPDSGetPackage/LATEST/SomeFile.drl.
- </para>
+
+ <para>There are a few other URLs which are handy to know exist. The
+ package deployment URL mentioned in the section about rule agent
+ deployment also has a few other features: By appending .drl to the end
+ of a URL, you will show the generated DRL for that package. eg:
+ /package/testPDSGetPackage/LATEST.drl - will show the DRL (not the
+ binary package) for the latest package. Further to this, you can append
+ /assetName.drl - and it will show the generated DRL for that item. (even
+ if it isn't a drl file). eg
+ /package/testPDSGetPackage/LATEST/SomeFile.drl.</para>
</section>
-
</section>
</section>
\ No newline at end of file
Added: labs/jbossrules/trunk/drools-docs/drools-docs-guvnor/en/Chapter-Guvnor/running_execution_server.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-guvnor/en/Chapter-Guvnor/running_execution_server.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
More information about the jboss-svn-commits
mailing list