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 Causeway starter app (org.apache.causeway.app:causeway-app-starter-parent) then that will define the version automatically:

pom.xml

<parent>
    <groupId>org.apache.causeway.app</groupId>
    <artifactId>causeway-app-starter-parent</artifactId>
    <version>3.1.0</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.causeway.core</groupId>
            <artifactId>causeway-core</artifactId>
            <version>3.1.0</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.causeway.persistence</groupId>
        <artifactId>causeway-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({
        ...
        CausewayModulePersistenceJdoDatanucleus.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.sql.init.platform=h2
spring.datasource.url=jdbc:h2:mem:simple
spring.datasource.driver-class-name=org.h2.Driver

for SQL Server:

app.properties

spring.sql.init.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 logical type name (as defined using @Named) also follows the same pattern.

For example:

@PersistenceCapable(
    schema="SIMPLE",                        (1)
    ...
)
@Named("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 causeway.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 causeway.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 tables during prototyping/tests

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 done either eagerly or lazily:

to create all tables eagerly, set datanucleus.schema.generate-database.mode to create.
to create all tables lazily (only as objects are read from/written to them), set the datanucleus.schema.auto-create-all to true.

Generally we recommend eager creation; there are certain edge cases — eg inheritance hierarchies using the superclass (roll-up) table mappging — where lazy creation can fail.

If running in an integration test, you can use a preset:

MyIntegrationTest.java

@SpringBootTest
@TestPropertySource({
    CausewayPresets.UseLog4j2Test,
    CausewayPresets.DatanucleusEagerlyCreateTables      (1)
})
class MyIntegrationTest extends CausewayIntegrationTestAbstract {
    //...
}

1	simply sets the `datanucleus.schema.generate-database.mode` to true.

Validating tables in production

When running in production then you may probably want to use Flyway to manage database migrations, rather than have DataNucleus maintain the schema. However, it is useful to validate that the database table structure of the target database is in line with what DataNucleus expects.

You can do this using the datanucleus.schema.validate-all configuration property. 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:

disable persistence by reachability

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 Causeway 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.