JBoss.orgCommunity Documentation

Chapter 16. Integration

16.1. Overview
16.2. Persistent Storage
16.2.1. Database: JPA and Hibernate
16.2.2. XML or JSON: XStream
16.2.3. XML or JSON: JAXB
16.2.4. JSON: Jackson
16.3. SOA and ESB
16.3.1. Camel and Karaf
16.4. Other Environments
16.4.1. JBoss Modules, WildFly and JBoss EAP
16.4.2. OSGi
16.4.3. Android
16.5. Integration with Human Planners (Politics)

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:

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

Add a dependency to the optaplanner-persistence-jpa jar to take advantage of these extra integration features:

When a Score is persisted into a relational database, JPA and Hibernate will default to Java serializing it to a BLOB column. This has several disadvantages:

To avoid these issues, configure it to instead use INTEGER (or other) columns, by using the appropriate *ScoreHibernateType for your Score type, for example for a HardSoftScore:

@PlanningSolution
@Entity
@TypeDef(defaultForType = HardSoftScore.class, typeClass = HardSoftScoreHibernateType.class)
public class CloudBalance {

    @PlanningScore
    @Columns(columns = {@Column(name = "initScore"), @Column(name = "hardScore"), @Column(name = "softScore")})
    protected HardSoftScore score;

    ...
}

In this case, the DDL will look like this:

CREATE TABLE CloudBalance(
    ...
    initScore INTEGER,
    hardScore INTEGER,
    softScore INTEGER
);

When using a BigDecimal based Score, specify the precision and scale of the columns to avoid silent rounding:

@PlanningSolution
@Entity
@TypeDef(defaultForType = HardSoftBigDecimalScore.class, typeClass = HardSoftBigDecimalScoreHibernateType.class)
public class CloudBalance{

    @PlanningScore
    @Columns(columns = {
            @Column(name = "initScore")
            @Column(name = "hardScore", precision = 10, scale = 5),
            @Column(name = "softScore", precision = 10, scale = 5)})
    protected HardSoftBigDecimalScore score;

    ...
}

In this case, the DDL will look like this:

CREATE TABLE CloudBalance(
    ...
    initScore INTEGER,
    hardScore DECIMAL(10, 5),
    softScore DECIMAL(10, 5)
);

When using any type of bendable Score, specify the hard and soft level sizes as parameters:

@PlanningSolution
@Entity
@TypeDef(defaultForType = BendableScore.class, typeClass = BendableScoreHibernateType.class, parameters = {
        @Parameter(name = "hardLevelsSize", value = "3"),
        @Parameter(name = "softLevelsSize", value = "2")})
public class Schedule {

    @PlanningScore
    @Columns(columns = {
            @Column(name = "initScore")
            @Column(name = "hard0Score"),
            @Column(name = "hard1Score"),
            @Column(name = "hard2Score"),
            @Column(name = "soft0Score"),
            @Column(name = "soft1Score")})
    protected BendableScore score;

    ...
}

All this support is Hibernate specific because currently JPA 2.1's converters do not support converting to multiple columns.

In JPA and Hibernate, there is usually a @ManyToOne relationship from most problem fact classes to the planning solution class. Therefore, the problem fact classes reference the planning solution class, which implies that when the solution is planning cloned, they need to be cloned too. Use an @DeepPlanningClone on each such problem fact class to enforce that:

@PlanningSolution // OptaPlanner annotation
@Entity // JPA annotation
public class Conference {

    @OneToMany(mappedBy="conference")
    private List<Room> roomList;

    ...
}
@DeepPlanningClone // OptaPlanner annotation: Force the default planning cloner to planning clone this class too
@Entity // JPA annotation
public class Room {

    @ManyToOne
    private Conference conference; // Because of this reference, this problem fact needs to be planning cloned too

}

Neglecting to do this can lead to persisting duplicate solutions, JPA exceptions or other side effects.

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.

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:

Because of JBoss Modules' ClassLoader magic, you'll likely need to provide the ClassLoader of your classes during the SolverFactory creation, so it can find the classpath resources (such as the solver config, score DRL's and domain classes) in your jars.

Android is not a complete JVM (because some JDK libraries are missing), but Planner works on Android with easy Java or incremental Java score calculation. The Drools rule engine does not work on Android yet, so Drools score calculation doesn't work on Android and its dependencies need to be excluded.

Workaround to use Planner on Android:

  1. Add a dependency to the build.gradle file in your Android project to exclude org.drools and xmlpull dependencies:

    dependencies {
        ...
        compile('org.optaplanner:optaplanner-core:...') {
            exclude group: 'xmlpull'
            exclude group: 'org.drools'
        }
        ...
    }

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, both can benefit if the human planner acts as supervisor to Planner:

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