Setup and Configuration

This section describes how to include the JDO module and set its configuration properties.

Maven pom.xml

Dependency Management

If your application inherits from the Apache Isis starter app (org.apache.isis.app:isis-app-starter-parent) then that will define the version automatically:

pom.xml
<parent>
    <groupId>org.apache.isis.app</groupId>
    <artifactId>isis-app-starter-parent</artifactId>
    <version>2.0.0-M6</version>
    <relativePath/>
</parent>

Alternatively, import the core BOM. This is usually done in the top-level parent pom of your application:

pom.xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.apache.isis.core</groupId>
            <artifactId>isis-core</artifactId>
            <version>2.0.0-M6</version>
            <scope>import</scope>
            <type>pom</type>
        </dependency>
    </dependencies>
</dependencyManagement>

Dependency

For every Maven module that includes JDO entities, add the following dependency:

pom.xml
<dependencies>
    <dependency>
        <groupId>org.apache.isis.persistence</groupId>
        <artifactId>isis-persistence-jdo-datanucleus</artifactId>
        <type>pom</type>
    </dependency>
</dependencies>

Update AppManifest

In your application’s AppManifest (top-level Spring @Configuration used to bootstrap the app), import the

AppManifest.java
@Configuration
@Import({
        ...
        IsisModuleJpaEclipselink.class,
        ...
})
public class AppManifest {
}

DataSource

The JPA object store uses Spring to provide a javax.sql.DataSource. Normally this is done by setting the spring.datasource configuration properties, as described in the Spring Boot documentation.

For example, the SimpleApp starter app defines these:

  • for H2 (in-memory):

    app.properties
    spring.datasource.platform=h2
    spring.datasource.url=jdbc:h2:mem:simple
    spring.datasource.driver-class-name=org.h2.Driver
  • for SQL Server:

    app.properties
    spring.datasource.platform=sqlserver
    spring.datasource.url=jdbc:sqlserver://localhost;databaseName=simpleapp
    spring.datasource.driver-class-name=com.microsoft.sqlserver.jdbc.SQLServerDriver
    spring.datasource.username=simpleapp
    spring.datasource.password=simpleapp

It is also possible to programmatically define a DataSource; see the Spring docs for details.

Create Schema

It’s good practice to use SQL schemas as a way to organise database tables into groups. We recommend all the entities within a module use the same schema, and moreover that the object type also follows the same pattern.

For example:

@javax.persistence.Entity
@javax.persistence.Table(
    schema="SIMPLE",                                (1)
    ...
)
@DomainObject(objectType = "simple.SimpleObject")   (2)
...
public class SimpleObject ... {

}
1 specifies the database schema. The table name will be based on the entity
2 corresponding two-part object type.

When prototyping we rely on the ORM to automatically create the entire database tables, which includes the owning schemas. As EclipseLink does not do this automatically, the framework will do this if requested. The isis.persistence.schema.auto-create-schemas controls if this is done or not.

Different database vendors have different syntaxes to do this, and so this can be configured using the isis.persistence.schema.create-schema-sql-template. The default value is to use SQL-99 syntax ("CREATE SCHEMA IF NOT EXISTS %S"), passed through to String.format().

Auto-create (or validate) tables

When running against the h2 in-memory database (eg for prototype mode or integration tests), you’ll probably want DataNucleus to automatically create the tables.

This can be configured using the:

Conversely, if running in production then you will probably use Flyway to manage database migrations. In this case you’ll just want to validate that the database table structure of the target database is in line with what DataNucleus expectss.

You can do this using the:

This will fail-fast if there is a mismatch.

Other Configuration Properties

Additional configuration properties for DataNucleus itself can be specified directly under the datanucleus. configuration key.

We recommend that some of these should be configured:

See the datanucleus section of the Configuration Guide for further details.

Furthermore, DataNucleus will search for various other XML mapping files, eg mappings.jdo. A full list can be found here.

DataNucleus properties must be specified using camelCase, not kebab-case.

For example, use datanucleus.schema.autoCreateAll not datanucleus.schema.auto-create-all

persistence.xml

DataNucleus will for itself also read the META-INF/persistence.xml. In theory this can hold mappings and even connection strings. However, with Apache Isis we tend to use annotations instead and externalize connection strings. so its definition is extremely simply, specifying just the name of the "persistence unit".

Here’s the one provided by the SimpleApp starter app:

<?xml version="1.0" encoding="UTF-8" ?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd" version="1.0">

    <persistence-unit name="simple">
    </persistence-unit>
</persistence>

Normally all one needs to do is to change the persistence-unit name.

If you use Eclipse IDE on Windows then note the importance of the persistence.xml file to make DataNucleus enhancer work correctly.

See DataNucleus' documentation on persistence.xml to learn more.