shared/Commands/API/API.xml

<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0"
         xml:id="CommandsAPISection"
         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>API</title>

  <para>XML marshalling/unmarshalling of the Drools Commands requires the use
  of special classes, which are going to be described in the following
  sections.</para>

  <para>The following urls show sample script examples for jaxb, xstream and
  json marshalling using:</para>

  <itemizedlist>
    <listitem>
      <para>http://fisheye.jboss.org/browse/JBossRules/trunk/drools-camel/src/test/resources/org/drools/camel/component/jaxb.mvt?r=HEAD</para>
    </listitem>

    <listitem>
      <para>http://fisheye.jboss.org/browse/JBossRules/trunk/drools-camel/src/test/resources/org/drools/camel/component/jaxb.mvt?r=HEAD</para>
    </listitem>

    <listitem>
      <para>http://fisheye.jboss.org/browse/JBossRules/trunk/drools-camel/src/test/resources/org/drools/camel/component/xstream.mvt?r=HEAD</para>
    </listitem>
  </itemizedlist>

  <section>
    <title>XStream</title>

    <para>To use the XStream commands marshaller you need to use the
    DroolsHelperProvider to obtain an XStream instance. We need to use this
    because it has the commands converters registered.</para>

    <itemizedlist>
      <listitem>
        <para>Marshalling</para>

        <para>BatchExecutionHelperProviderImpl.newXStreamMarshaller().toXML(command);</para>
      </listitem>

      <listitem>
        <para>Unmarshalling</para>

        <para>BatchExecutionHelperProviderImpl.newXStreamMarshaller().fromXML(xml)</para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>JSON</title>

    <para>JSON API to marshalling/unmarshalling is similar to XStream
    API:</para>

    <itemizedlist>
      <listitem>
        <para>Marshalling</para>

        <para>BatchExecutionHelper.newJSonMarshaller().toXML(command);</para>
      </listitem>

      <listitem>
        <para>Unmarshalling</para>

        <para>BatchExecutionHelper.newJSonMarshaller().fromXML(xml)</para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>JAXB</title>

    <para>There are two options for using JAXB, you can define your model in
    an XSD file or you can have a POJO model. In both cases you have to
    declare your model inside JAXBContext, and in order to do that you need to
    use Drools Helper classes. Once you have the JAXBContext you need to
    create the Unmarshaller/Marshaller as needed.</para>

    <section>
      <title>Using an XSD file to define the model</title>

      <para>With your model defined in a XSD file you need to have a
      KnowledgeBase that has your XSD model added as a resource.</para>

      <para>To do this, the XSD file must be added as a XSD ResourceType into
      the KnowledgeBuilder. Finally you can create the JAXBContext using the
      KnowledgeBase created with the KnowledgeBuilder

</para>

      <programlisting language="java">Options xjcOpts = new Options();
xjcOpts.setSchemaLanguage(Language.XMLSCHEMA);
JaxbConfiguration jaxbConfiguration = KnowledgeBuilderFactory.newJaxbConfiguration( xjcOpts, "xsd" );
kbuilder.add(ResourceFactory.newClassPathResource("person.xsd", getClass()), ResourceType.XSD, jaxbConfiguration);
KnowledgeBase kbase = kbuilder.newKnowledgeBase();

List&lt;String&gt; classesName = new ArrayList&lt;String&gt;();
classesName.add("org.drools.compiler.test.Person");
   
JAXBContext jaxbContext = KnowledgeBuilderHelper.newJAXBContext(classesName.toArray(new String[classesName.size()]), kbase);</programlisting>
    </section>

    <section>
      <title>Using a POJO model</title>

      <para>In this case you need to use DroolsJaxbHelperProviderImpl to create the
      JAXBContext. This class has two parameters:</para>

      <orderedlist>
        <listitem>
          <para>classNames: A List with the canonical name of the classes that
          you want to use in the marshalling/unmarshalling process.</para>
        </listitem>

        <listitem>
          <para>properties: JAXB custom properties</para>
        </listitem>
      </orderedlist>

      <programlisting language="java">List&lt;String&gt; classNames = new ArrayList&lt;String&gt;();
classNames.add("org.drools.compiler.test.Person");
JAXBContext jaxbContext = DroolsJaxbHelperProviderImpl.createDroolsJaxbContext(classNames, null);
Marshaller marshaller = jaxbContext.createMarshaller();</programlisting>

    </section>
  </section>
</section>