[jboss-svn-commits] JBL Code SVN: r34232 - in labs/jbossrules/trunk/drools-docs/drools-docs-integration/src/main/docbook/en-US/Chapter-Server: Section-Introduction and 1 other directory.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Tue Jul 27 17:27:22 EDT 2010
Author: lucazamador
Date: 2010-07-27 17:27:21 -0400 (Tue, 27 Jul 2010)
New Revision: 34232
Modified:
labs/jbossrules/trunk/drools-docs/drools-docs-integration/src/main/docbook/en-US/Chapter-Server/Section-Configuration/Section-Configuration.xml
labs/jbossrules/trunk/drools-docs/drools-docs-integration/src/main/docbook/en-US/Chapter-Server/Section-Introduction/Section-Deployment.xml
labs/jbossrules/trunk/drools-docs/drools-docs-integration/src/main/docbook/en-US/Chapter-Server/Section-Introduction/Section-Introduction.xml
Log:
JBRULES-2524 Camel/Spring/OSGi integration documentation
-drools server documentation updated
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-integration/src/main/docbook/en-US/Chapter-Server/Section-Configuration/Section-Configuration.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-integration/src/main/docbook/en-US/Chapter-Server/Section-Configuration/Section-Configuration.xml 2010-07-27 19:59:28 UTC (rev 34231)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-integration/src/main/docbook/en-US/Chapter-Server/Section-Configuration/Section-Configuration.xml 2010-07-27 21:27:21 UTC (rev 34232)
@@ -1,241 +1,158 @@
<?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="../../" 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:ns="http://docbook.org/ns/docbook">
- <title>Configuration</title>
+ 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"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:ns="http://docbook.org/ns/docbook">
+ <title>Configuration</title>
- <para>Inside the war file you will found a few XML configuration files.
- The most importants are session.xml and services.xml that we'll see in
- depth in the next sections. The other two files, configuration.xml and
- core.xml only made the REST and SOAP services configuration.</para>
+ <para>Inside the war file you will found a few XML configuration files. The
+ most importants are knowledge-services.xml and camel-server.xml that we'll
+ see in depth in the next sections. The other file, beans.xml only includes
+ these two files.</para>
- <section>
- <title>Knowledge Sessions configuration</title>
+ <section>
+ <title>REST/Camel Services configuration</title>
- <para>All the drools-server configuration is created using the Spring
- integration. You can check the drools-spring documentation to have more
- information about all the posibles Knowledge Sessions
- configurations.</para>
+ <para>The next step is configure the services that are going to be exposed
+ through drools-server. You can modify this configuration in
+ camel-server.xml file.</para>
- <para>But as an example you can check the next configuration, when we
- created two Knowledge Sessions, one stateless and another stateful,
- using two diferents Knowledge Base.</para>
-
- <programlisting><?xml version="1.0" encoding="UTF-8"?>
+ <programlisting><?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xmlns:context="http://www.springframework.org/schema/context"
- xmlns:drools="http://drools.org/schema/drools-spring"
- xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
- http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-2.5.xsd
- http://drools.org/schema/drools-spring http://drools.org/schema/drools-spring.xsd"
- default-autowire="byName">
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns:cxf="http://camel.apache.org/schema/cxf"
+ xmlns:jaxrs="http://cxf.apache.org/jaxrs"
+ xsi:schemaLocation="
+ http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
+ http://camel.apache.org/schema/cxf http://camel.apache.org/schema/cxf/camel-cxf.xsd
+ http://cxf.apache.org/jaxrs http://cxf.apache.org/schemas/jaxrs.xsd
+ http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd">
- <drools:connection id="connection1" type="local" />
+<import resource="classpath:META-INF/cxf/cxf.xml" />
+<import resource="classpath:META-INF/cxf/cxf-extension-jaxrs-binding.xml"/>
+<import resource="classpath:META-INF/cxf/cxf-servlet.xml" />
- <drools:execution-node id="node1" connection="connection1" />
+ <!--
+ ! Define the server end point.
+ ! Copy and paste this element, changing id and the address, to expose services on different urls.
+ ! Different Camel routes can handle different end point paths.
+ -->
+ <cxf:rsServer id="rsServer"
+ address="/kservice/rest"
+ serviceClass="org.drools.jax.rs.CommandExecutorImpl">
+ <cxf:providers>
+ <bean class="org.drools.jax.rs.CommandMessageBodyReader"/>
+ </cxf:providers>
+ </cxf:rsServer>
- <drools:kbase id="kbase1" node="node1">
- <drools:resource source="classpath:changesets/change-set-1.xml" type="CHANGE_SET" />
- <drools:model source="classpath:model/person.xsd" />
- </drools:kbase>
+ <!-- Leave this, as it's needed to make Camel "drools" aware -->
+ <bean id="droolsPolicy" class="org.drools.camel.component.DroolsPolicy" />
- <drools:kbase id="kbase2" node="node1">
- <drools:resource source="classpath:changesets/change-set-2.xml" type="CHANGE_SET" />
- </drools:kbase>
+ <camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
+ <!--
+ ! Routes incoming messages from end point id="rsServer".
+ ! Example route unmarshals the messages with xstream and executes against ksession1.
+ ! Copy and paste this element, changing marshallers and the 'to' uri, to target different sessions, as needed.
+ !-->
+
+ <route>
+ <from uri="cxfrs://bean://rsServer"/>
+ <policy ref="droolsPolicy">
+ <unmarshal ref="xstream" />
+ <to uri="drools:node1/ksession1" />
+ <marshal ref="xstream" />
+ </policy>
+ </route>
+
+ </camelContext>
+
+</beans> </programlisting>
- <drools:ksession id="ksession1" type="stateful" kbase="kbase1" node="node1"/>
-
- <drools:ksession id="ksession2" type="stateless" kbase="kbase2" node="node1"/>
-
-</beans></programlisting>
-
- <para>For further configuration details, check the Drools Spring
- documentation</para>
- </section>
-
<section>
- <title>Knowledge Service configuration</title>
+ <title>RESTful service endpoint creation</title>
- <para>The next step is configure the services that are going to be
- exposed through drools-server. The first thing that you should notice is
- that there's a new xml namespace for this, named drools-service.</para>
+ <para>In the next xml snippet code we are creating a RESTful (JAX-RS)
+ endpoint binded to /kservice/rest address and using
+ org.drools.jax.rs.CommandExecutorImpl as the service implementor. This
+ class is only used to instantiate the service endpoint because all the
+ internal implementation is managed by Camel, and you can see in the
+ source file that the exposed execute service must be never
+ called.</para>
- <programlisting><?xml version="1.0" encoding="UTF-8"?>
-<beans xmlns="http://www.springframework.org/schema/beans"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xmlns:context="http://www.springframework.org/schema/context"
- xmlns:camel="http://camel.apache.org/schema/spring"
- xmlns:drools-service="http://drools.org/schema/drools-service-spring"
- xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
- http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-2.5.xsd
- http://drools.org/schema/drools-service-spring http://drools.org/schema/drools-service-spring.xsd
- http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd"
- default-autowire="byName">
+ <para>Also a JAX-RS Provider is provided to determine if the message
+ transported can be processed in this service endpoint.</para>
- <!-- Only needed to deploy on JBoss AS 5.X -->
- <bean id="jbossResolver" class="org.apache.camel.jboss.JBossPackageScanClassResolver"/>
+ <programlisting><cxf:rsServer id="rsServer"
+ address="/kservice/rest"
+ serviceClass="org.drools.jax.rs.CommandExecutorImpl">
+ <cxf:providers>
+ <bean class="org.drools.jax.rs.CommandMessageBodyReader"/>
+ </cxf:providers>
+</cxf:rsServer></programlisting>
- <!-- This camel context bean is required -->
- <camelContext id="executionContext" xmlns="http://camel.apache.org/schema/spring" />
+ <para>Ideally this configuration doesn’t need to be modified, at least
+ the Service Class and the JAX-RS Provider, but you can add more
+ endpoints associated to different addresses to use them in anothers
+ Camel Routes.</para>
- <drools-service:configuration id="service-conf-2" marshaller="XSTREAM" session="ksession2" />
+ <para>After all this initial configuration, you can start config your
+ own Knowledge Services.</para>
+ </section>
- <drools-service:definition id="service" smId="sm1" camelContext="executionContext">
- <drools-service:configuration marshaller="JAXB" session="ksession1">
- <drools-service:class>org.drools.model.Person</drools-service:class>
- <drools-service:startup-command>
- <![CDATA[
- <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
- <batch-execution lookup="ksession1" xmlns:ns2="http://drools.org/model">
- <insert out-identifier="santa">
- <object xsi:type="ns2:person" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
- <ns2:name>santa</ns2:name>
- <ns2:age>99</ns2:age>
- </object>
- </insert>
- </batch-execution>
- ]]>
- </drools-service:startup-command>
- </drools-service:configuration>
- <drools-service:configuration-ref id="service-conf-2" />
- </drools-service:definition>
+ <section>
+ <title>Camel Drools Policy & Context creation</title>
-</beans></programlisting>
+ <para>DroolsPolicy is used to add Drools support in Camel, basically
+ what it does is to add interceptors into the camel route to create Camel
+ Processors on the fly and modify the internal navigation route. If you
+ want to have SOAP support you need to create your custom Drools Policy,
+ but it's going to be added in the next release.</para>
- <section>
- <title>Initial Configuration</title>
+ <para>But you don’t need to know more internal details, only instantiate
+ this bean:</para>
- <para>In the previous sections was mentioned that the configuration
- must be changed to allow the deployment of drools-server in a JBoss
- Application Server 5. Bassicly we are adding a Camel
- PackageScanClassResolver that can deal with the new JBoss AS5
- classloader.</para>
+ <programlisting><bean id="droolsPolicy" class="org.drools.camel.component.DroolsPolicy" /></programlisting>
- <para>If you want to deploy in a AS5 you simply must add this bean
- definition line.</para>
- <programlisting><bean id="jbossResolver" class="org.apache.camel.jboss.JBossPackageScanClassResolver"/></programlisting>
- <para>Another important configuration is the Camel Context declaration, as you can
- see below:</para>
+ <para>The next is create the camel route that will have the
+ responsibility to execute the commands sent through JAX-RS. Basically we
+ create a route definition associated with the JAX-RS definition as the
+ data input, the camel policy to be used and inside the “execution route”
+ or ProcessorDefinitions. As you can see, we set XStream as the
+ marshaller/unmarshaller and the drools execution route definition</para>
- <programlisting><camelContext id="executionContext" xmlns="http://camel.apache.org/schema/spring" /></programlisting>
+ <programlisting><camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
+ <route>
+ <from uri="cxfrs://bean://rsServer"/>
+ <policy ref="droolsPolicy">
+ <unmarshal ref="xstream" />
+ <to uri="drools:node1/ksession1" />
+ <marshal ref="xstream" />
+ </policy>
+ </route>
+</camelContext></programlisting>
- <para>After all this initial configuration, you can start config your
- own Knowledge Services.</para>
- </section>
+ <para>The drools endpoint creation has the next arguments</para>
- <section>
- <title>Creating our own knowledge service configuration</title>
+ <para><programlisting><to uri="drools:{1}/{2}" /></programlisting></para>
- <para>The idea of a service configuration is declare how our commands
- are going to interact with the KnowledgeSession and which initial
- configuration is needed to their interpretation.</para>
+ <orderedlist>
+ <listitem>
+ <para>Execution Node identifier that is registered in the
+ CamelContext</para>
+ </listitem>
- <para>In a common declaration we have 3 required attributes:</para>
+ <listitem>
+ <para>Knowledge Session identifier that was registered in the
+ Execution Node with identifier {1}</para>
+ </listitem>
+ </orderedlist>
- <orderedlist>
- <listitem>
- <para>id: to identify the service configuration in the service
- definition, which will see in the next section.</para>
- </listitem>
-
- <listitem>
- <para>marshaller: here we declare wich marshaller are going to be
- used in the commands marshalling/marshaller. At this moment we
- have support for three types of command format: XSTREAM, JAXB and
- JSON.</para>
- </listitem>
-
- <listitem>
- <para>session: the Knowledge Session in which the commands are
- going to be executed.</para>
- </listitem>
- </orderedlist>
-
- <para>Using JAXB we can add a special configuration to declare wich
- classes needs to be included in the JAXBContext. This will allow us to
- copy our JAR model to the servlet container in which the drools-server
- has been deployed and use them in JAXB commands without using a XSD
- file that declare the same model definition.</para>
- <programlisting><drools-service:class>org.drools.model.Person</drools-service:class></programlisting>
-
- <para>Also we can add commands that are going to be executed when
- drools-server got deployed. To use this just add the next tag with the
- XML command inside them</para>
-
- <programlisting><drools-service:startup-command>
-<![CDATA[
- <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
- <batch-execution lookup="ksession1" xmlns:ns2="http://drools.org/model">
- <insert out-identifier="santa">
- <object xsi:type="ns2:person" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
- <ns2:name>santa</ns2:name>
- <ns2:age>99</ns2:age>
- </object>
- </insert>
- </batch-execution>
-]]>
-<drools-service:startup-command/></programlisting>
-
- <note>
- <para>Remember to add the <![CDATA[ ]]> tag to don't break the XML parser.</para>
- </note>
- </section>
-
- <section>
- <title>Creating our own knowledge service definition</title>
-
- <para>The idea of a knowledge service definition is to group different
- knowledge service configurations to be exposed as a service.</para>
-
- <programlisting><drools-service:definition id="service" node="node1" camelContext="executionContext">
- <drools-service:configuration marshaller="JAXB" session="ksession1">
- <drools-service:class>org.drools.model.Person</drools-service:class>
- </drools-service:configuration>
- <drools-service:configuration-ref id="service-conf-2" />
-</drools-service:definition></programlisting>
-
- <para>The service definition has three required attributes:</para>
-
- <orderedlist>
- <listitem>
- <para>id: by default named 'service'. If you want to change this
- name, you should also change the SOAP/Rest configuration in
- core.xml</para>
- </listitem>
-
- <listitem>
- <para>node: the ExecutionNode previously configured in
- sessions.xml file.</para>
- </listitem>
-
- <listitem>
- <para>camelContext: the Camel Context created in sessions.xml
- file.</para>
- </listitem>
- </orderedlist>
-
- <para>Inside the service definition you can declare wich service
- configuration are going to be used. To do this we have two
- approachs:</para>
-
- <itemizedlist>
- <listitem>
- <para>Inline declaration: Declaring the service configuration as
- you see in the previous section. In this case, the ID isn't
- required</para>
- </listitem>
- </itemizedlist>
-
- <itemizedlist>
- <listitem>
- <para>Inline declaration: Declaring the service configuration as
- you see in the previous section. In this case, the ID isn't
- required</para>
- </listitem>
- </itemizedlist>
- </section>
+ <para>Both parameters are configured in knowledge-services.xml
+ file.</para>
</section>
+ </section>
</section>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-integration/src/main/docbook/en-US/Chapter-Server/Section-Introduction/Section-Deployment.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-integration/src/main/docbook/en-US/Chapter-Server/Section-Introduction/Section-Deployment.xml 2010-07-27 19:59:28 UTC (rev 34231)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-integration/src/main/docbook/en-US/Chapter-Server/Section-Introduction/Section-Deployment.xml 2010-07-27 21:27:21 UTC (rev 34232)
@@ -1,16 +1,18 @@
<?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="../../" 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:ns="http://docbook.org/ns/docbook">
- <title>Deployment</title>
+ 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"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:ns="http://docbook.org/ns/docbook">
+ <title>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. Deploy on JBoss AS 4.x / Tomcat 6.x works out-of-the-box,
- instead the configuration must be changed to be deployed in JBoss AS
- 5</para>
-
+ <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. Deploy on JBoss AS 4.x / Tomcat 6.x works out-of-the-box, instead some
+ external dependencies must be added and the configuration must be changed to
+ be deployed in JBoss AS 5</para>
</section>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-integration/src/main/docbook/en-US/Chapter-Server/Section-Introduction/Section-Introduction.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-integration/src/main/docbook/en-US/Chapter-Server/Section-Introduction/Section-Introduction.xml 2010-07-27 19:59:28 UTC (rev 34231)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-integration/src/main/docbook/en-US/Chapter-Server/Section-Introduction/Section-Introduction.xml 2010-07-27 21:27:21 UTC (rev 34232)
@@ -1,16 +1,18 @@
<?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="../../" 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:ns="http://docbook.org/ns/docbook">
- <title>Introduction</title>
+ 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"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:ns="http://docbook.org/ns/docbook">
+ <title>Introduction</title>
- <para>The drools execution server (drools-server) module is a war which
- you can deploy to execute KnowledgeBases remotely for any sort of client
- application. This is not limited to JVM application clients, but any
- technology that can use HTTP, through a REST/SOAP interface. This version
- of the execution server supports stateless and statefull sessions in a
- native way.</para>
-
+ <para>The drools execution server (drools-server) module is a war which you
+ can deploy to execute KnowledgeBases remotely for any sort of client
+ application. This is not limited to JVM application clients, but any
+ technology that can use HTTP, through a REST interface. This version of the
+ execution server supports stateless and statefull sessions in a native
+ way.</para>
</section>
More information about the jboss-svn-commits
mailing list