JBoss.org Community Documentation

- Prev
- Next

## Chapter 16. Integration

## 16.1. Overview

Planner's input and output data (the planning problem and the best solution) are plain old JavaBeans (POJO's), so integration with other Java technologies is straightforward. For example:

- To read a planning problem from the database (and store the best solution in it), annotate the domain POJO's with JPA annotations.

- To read a planning problem from an XML file (and store the best solution in it), annotate the domain POJO's with XStream or JAXB annotations.

- To expose the Solver as a REST Service that reads the planning problem and responds with the best solution, annotate the domain POJO's with XStream or JAXB annotations and hook the `Solver` in Camel or RESTEasy.

## 16.2. Persistent storage

### 16.2.1. Database: JPA and Hibernate

Enrich the domain POJO's (solution, entities and problem facts) with JPA annotations to store them in a database.

## Note

Do not confuse JPA's `@Entity` annotation with Planner's `@PlanningEntity` annotation. They can appear both on the same class.

### 16.2.2. XML: XStream

Enrich the domain POJO's (solution, entities and problem facts) with XStream annotations to serialize them to/from XML.

### 16.2.3. XML: JAXB

Enrich the domain POJO's (solution, entities and problem facts) with JAXB annotations to serialize them to/from XML.

## 16.3. SOA and ESB

### 16.3.1. Camel and Karaf

Camel is an enterprise integration framework which includes support for Planner (starting from Camel 2.13). It can expose a use case as a REST service, a SOAP service, a JMS service, ...

Read the documentation for the camel-optaplanner component. That component works in Karaf too.

## 16.4. Other environments

### 16.4.1. JBoss modules, WildFly and JBoss EAP

To deploy an Planner web application on WildFly, simply include the optaplanner dependency jars in the `war` file's `WEB-INF/lib` directory (just like any other dependency) as shown in the `optaplanner-webexamples-*.war`. However, in this approach the war file can easily grow to several MB in size, which is fine for a one-time deployment, but too heavyweight for frequent redeployments (especially over a slow network connection).

The remedy is to use deliver the optaplanner jars in a JBoss module to WildFly and create a skinny war. Let's create an module called org.optaplanner:

1. Navigate to the directory `${WILDFLY_HOME}/modules/system/layers/base/`. This directory contains the JBoss modules of WildFly. Create directory structure `org/optaplanner/main` for our new module.

   1. Copy `optaplanner-core-${version}.jar` and all its direct and transitive dependency jars into that new directory. Use "mvn dependency:tree" on each optaplanner artifact to discover all dependencies.

   2. Create the file `module.xml` in that new directory. Give it this content:

          <?xml version="1.0" encoding="UTF-8"?>
          <module xmlns="urn:jboss:module:1.3" name="org.optaplanner">
            <resources>
              ...
              <resource-root path="kie-api-${version}.jar"/>
              ...
              <resource-root path="optaplanner-core-${version}.jar"/>
              ...
              <resource-root path="."/>
            </resources>
            <dependencies>
              <module name="javaee.api"/>
            </dependencies>
          </module>

2. Navigate to the deployed `war` file.

   1. Remove `optaplanner-core-${version}.jar` and all its direct and transitive dependency jars from the `WEB-INF/lib` directory in the `war` file.

   2. Create the file `jboss-deployment-structure.xml` in the `WEB-INF/lib` directory. Give it this content:

          <?xml version="1.0" encoding="UTF-8" ?>
          <jboss-deployment-structure>
             <deployment>
                <dependencies>
                   <module name="org.optaplanner" export="true"/>
                </dependencies>
             </deployment>
          </jboss-deployment-structure>

## Important

Because of WildFly's class loading, the method `SolverFactory.createFromXmlResource()` might not find the solver configuration and throw an `IllegalArgumentException`. Instead use:

            SolverFactory solverFactory = SolverFactory.createFromXmlInputStream(
                    getClass().getClassLoader().getResourceAsStream(
                            "org/optaplanner/examples/nqueens/solver/nqueensSolverConfig.xml"));

### 16.4.2. OSGi

The `optaplanner-core` jar includes OSGi metadata to function properly in an OSGi environment too.

## Note

Planner does not require OSGi. It works perfectly fine in a normal Java environment too.

### 16.4.3. Android

Planner does not work out-of-the-box on Android yet, because it is not a complete JVM. For more information and workarounds, see this issue.

## 16.5. Integration with human planners (politics)

A good Planner implementation beats any good human planner for non-trivial datasets. Many human planners fail to accept this, often because they feel threatened by an automated system.

But despite that, Planner can benefit from a human planner as supervisor:

- The human planner defines and validates the score function.

  - Some examples expose a `*Parametrization` object, which defines the weight for each score constraint. The human planner can then tweak those weights at runtime.

  - When the business changes, the score function often needs to change too. The human planner can notify the developers to add, change or remove score constraints.

- The human planner is always in control of Planner.

  - As shown in the course scheduling example, the human planner can lock 1 or more planning variables to a specific planning value and make those immovable. Because they are immovable, Planner does not change them: it optimizes the planning around the enforcements made by the human. If the human planner locks all planning variables, he/she sidelines Planner completely.

  - In a prototype implementation, the human planner might use this occasionally. But as the implementation matures, it must become obsolete. But do keep the feature alive: as a reassurance for the humans. Or in case that one day the business changes dramatically before the score constraints can be adjusted.

Therefore, it's often a good idea to involve the human planner in your project.

- PrevChapter 15. Repeated planning
- Up
- Home
- NextChapter 17. Development