You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2021/03/31 12:54:42 UTC
[isis] 17/20: ISIS-2484: adds back in docs
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/isis.git
commit 99f87450eaf32e34c7fb38b8e7aee2c5f946043d
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Wed Mar 31 12:29:10 2021 +0100
ISIS-2484: adds back in docs
(cherry picked from commit 46e10eeb5818853fdefe1e3fd6cc86a0adaad936)
---
.../jpa/adoc/modules/ROOT/pages/applib.adoc | 1 +
.../jpa/adoc/modules/ROOT/pages/mapping-guide.adoc | 2 +-
.../ROOT/pages/setup-and-configuration.adoc | 143 ++++++++++++++++++++-
3 files changed, 140 insertions(+), 6 deletions(-)
diff --git a/persistence/jpa/adoc/modules/ROOT/pages/applib.adoc b/persistence/jpa/adoc/modules/ROOT/pages/applib.adoc
index e69de29..43d4bb56 100644
--- a/persistence/jpa/adoc/modules/ROOT/pages/applib.adoc
+++ b/persistence/jpa/adoc/modules/ROOT/pages/applib.adoc
@@ -0,0 +1 @@
+= JPA Applib
diff --git a/persistence/jpa/adoc/modules/ROOT/pages/mapping-guide.adoc b/persistence/jpa/adoc/modules/ROOT/pages/mapping-guide.adoc
index 22c7ab3..71d14ff 100644
--- a/persistence/jpa/adoc/modules/ROOT/pages/mapping-guide.adoc
+++ b/persistence/jpa/adoc/modules/ROOT/pages/mapping-guide.adoc
@@ -1,4 +1,4 @@
-= Other Resources
+= Mapping Guide
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
:page-aliases: guides:ugvw:ugvw.adoc
diff --git a/persistence/jpa/adoc/modules/ROOT/pages/setup-and-configuration.adoc b/persistence/jpa/adoc/modules/ROOT/pages/setup-and-configuration.adoc
index 4048e64..54f5924 100644
--- a/persistence/jpa/adoc/modules/ROOT/pages/setup-and-configuration.adoc
+++ b/persistence/jpa/adoc/modules/ROOT/pages/setup-and-configuration.adoc
@@ -1,12 +1,145 @@
-= JPA
+= Setup and Configuration
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
-The JPA/EclipseLink object store enables domain objects to be persisted to relational databases.
-The object store is implemented using the link:https://www.eclipse.org/eclipselink/[EclipseLink] ORM, using the link:https://www.jcp.org/en/jsr/detail?id=317[JPA] API.
-EclipseLink is the reference implementation for JPA.
+This section describes how to include the JPA module and setup its configuration properties.
+
+
+== Add dependency to 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:
+
+[source,xml,subs="attributes+"]
+.pom.xml
+----
+<parent>
+ <groupId>org.apache.isis.app</groupId>
+ <artifactId>isis-app-starter-parent</artifactId>
+ <version>{page-isisrel}</version>
+ <relativePath/>
+</parent>
+----
+
+Alternatively, import the core BOM.
+This is usually done in the top-level parent pom of your application:
+
+[source,xml,subs="attributes+"]
+.pom.xml
+----
+<dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.isis.core</groupId>
+ <artifactId>isis-core</artifactId>
+ <version>{page-isisrel}</version>
+ <version>2.0.0-SNAPSHOT</version>
+ <scope>import</scope>
+ <type>pom</type>
+ </dependency>
+ </dependencies>
+</dependencyManagement>
+----
+
+
+=== Dependency
+
+For every Maven module that includes JPA entities, add the following dependency:
+
+[source,xml]
+.pom.xml
+----
+<dependencies>
+ <dependency>
+ <groupId>org.apache.isis.mavendeps</groupId>
+ <artifactId>isis-mavendeps-jpa</artifactId>
+ <type>pom</type>
+ </dependency>
+</dependencies>
+----
+
+
+== Update AppManifest
+
+In your application's `AppManifest` (top-level Spring `@Configuration` used to bootstrap the app), import the
+
+[source,java]
+.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.
+
+For example, the xref:docs:starters:simpleapp.adoc[SimpleApp] starter app defines these:
+
+* for H2 (in-memory):
++
+[source,properties]
+.app.properties
+----
+spring.datasource.platform=h2
+spring.datasource.url=jdbc:h2:mem:simple
+spring.datasource.driver-class-name=org.h2.Driver
+----
+
+* for SQL Server:
++
+[source,properties]
+.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 link:https://docs.spring.io/spring-boot/docs/current/reference/html/howto.html#howto-data-access[Spring docs] for details.
+
+
+== Schemas
+
+In the same way that Java packages act as a namespace for domain objects, it's good practice to map domain entities to their own (database) schemas.
+(For more on database schemas, see for example link:https://crate.io/docs/sql-99/en/latest/chapters/17.html#create-schema-statement[here]).
+
+We recommend all the entities within a module use the same schema, and moreover that the xref:refguide:applib:index/annotation/DomainObject.adoc#objectType[object type] also follows the same pattern.
+
+For example, xref:security:secman:about.adoc[SecMan]' JPA implementation resides in the `IsisModuleExtSecmanPersistenceJpa` module.
+Its `ApplicationUser` entity is defined as:
+
+[source,java]
+.ApplicationUser.java
+----
+@Entity
+@Table(
+ schema = "isisExtensionsSecman",
+ name = "ApplicationUser",
+ ...
+)
+public class ApplicationUser ... { /* ... */ }
+----
+
+which results in a `CREATE TABLE` statement of:
+
+[source,sql]
+----
+CREATE TABLE isisExtensionsSecman."ApplicationUser" (
+ ...
+)
+----
-This component guide discuss how to setup the framework to use the JPA/EclipseLink object store, how to configure the ORM, and also provides some examples on common use cases.