This is an automated email from the ASF dual-hosted git repository. danhaywood pushed a commit to branch CAUSEWAY-3866 in repository https://gitbox.apache.org/repos/asf/causeway.git
commit 71b0af20d093c5c224a98a0da5f6ed36cf9b224d Author: Dan Haywood <[email protected]> AuthorDate: Wed Oct 15 07:09:34 2025 +0100 CAUSEWAY-3866: updating docs, removing references to JDO --- .../comguide/modules/ROOT/pages/starter-apps.adoc | 7 +- .../components/docs/modules/ROOT/pages/about.adoc | 1 - .../ROOT/pages/landing-page/components.adoc | 10 +-- .../what-is-apache-causeway/screencasts-older.txt | 12 --- .../hooks/DomainObject_021-logicalTypeName.adoc | 9 +- .../annotation/hooks/DomainObject_022-nature.adoc | 2 +- .../annotation/hooks/Property_021-optionality.adoc | 14 ++-- .../annotation/hooks/Property_023-maxLength.adoc | 2 +- .../pages/index/value/hooks/Blob_usage-notes.adoc | 30 ++++--- .../pages/index/value/hooks/Clob_usage-notes.adoc | 25 +++--- .../refguide/modules/applib-ant/pages/Column.adoc | 22 +++-- .../refguide/modules/applib-ant/pages/Digits.adoc | 3 +- .../modules/applib-ant/pages/Discriminator.adoc | 68 --------------- .../refguide/modules/applib-ant/pages/Entity.adoc | 94 ++------------------- .../modules/applib-ant/pages/NotPersistent.adoc | 19 ----- .../modules/applib-ant/pages/Nullable.adoc | 6 +- .../refguide/modules/applib-ant/pages/Pattern.adoc | 1 + .../applib-ant/pages/PersistenceCapable.adoc | 93 --------------------- .../modules/applib-ant/pages/PrimaryKey.adoc | 20 ----- .../modules/applib-ant/pages/Table.adoc} | 12 +-- .../modules/applib-ant/partials/module-nav.adoc | 9 +- .../refguide/modules/applib-svc/pages/about.adoc | 2 +- .../2.0.0-M1/mignotes/removed-annotations.adoc | 4 +- .../ROOT/partials/2024/2.0.0/_relnotes.adoc | 7 +- .../ROOT/partials/2024/2.1.0/_relnotes.adoc | 2 +- .../setupguide/modules/eclipse/pages/about.adoc | 2 +- .../setupguide/modules/intellij/pages/about.adoc | 6 +- .../modules/ROOT/partials/_deployment-options.adoc | 7 +- .../ROOT/partials/domain-entities/_intro.adoc | 2 +- .../ROOT/partials/domain-services/crud.adoc | 97 ++++++---------------- .../ROOT/partials/meta-annotations/_intro.adoc | 2 +- .../properties-collections-actions/actions.adoc | 6 +- .../collections.adoc | 10 +-- .../modules/ROOT/partials/view-models/_intro.adoc | 2 +- .../causeway/applib/annotation/Optionality.java | 11 +-- .../applib/services/metrics/package-info.java | 2 +- .../applib/services/repository/package-info.java | 2 +- core/adoc/modules/ROOT/pages/about.adoc | 2 +- .../src/main/adoc/modules/config/pages/about.adoc | 4 +- .../main/adoc/modules/metamodel/pages/events.adoc | 2 +- .../adoc/modules/commandlog/pages/about.adoc | 2 +- .../adoc/modules/executionlog/pages/about.adoc | 2 +- .../adoc/modules/executionoutbox/pages/about.adoc | 2 +- .../flyway/adoc/modules/flyway/pages/about.adoc | 12 +-- .../secman/adoc/modules/secman/pages/about.adoc | 9 +- mavendeps/adoc/modules/mavendeps/pages/about.adoc | 4 +- .../jpa/applib/types/BlobJpaEmbeddable.java | 9 +- .../jpa/applib/types/ClobJpaEmbeddable.java | 9 +- .../adoc/modules/starters/pages/helloworld.adoc | 36 ++++---- .../adoc/modules/integtestsupport/pages/about.adoc | 15 +--- .../adoc/modules/unittestsupport/pages/about.adoc | 10 +-- 51 files changed, 183 insertions(+), 558 deletions(-) diff --git a/antora/components/comguide/modules/ROOT/pages/starter-apps.adoc b/antora/components/comguide/modules/ROOT/pages/starter-apps.adoc index cd2f8366033..8c13c4037d3 100644 --- a/antora/components/comguide/modules/ROOT/pages/starter-apps.adoc +++ b/antora/components/comguide/modules/ROOT/pages/starter-apps.adoc @@ -4,15 +4,12 @@ :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 [...] -== Simpleapp Maintenance (JDO and JPA) +== Simpleapp Maintenance When making updates for simpleapp, to the current snapshot: . make change to `{page-causewaycurrmajorversion}-jpa-SNAPSHOT` -// . forward port from `{page-causewaycurrmajorversion}-jpa-SNAPSHOT` to `{page-causewaynextmajorversion}-jpa-SNAPSHOT` -. merge down from `{page-causewaycurrmajorversion}-jpa-SNAPSHOT` to `{page-causewaycurrmajorversion}-jdo-SNAPSHOT` -// . forward port from `{page-causewaycurrmajorversion}-jdo-SNAPSHOT` to `{page-causewaynextmajorversion}-jdo-SNAPSHOT` -// . merge down from `{page-causewaynextmajorversion}-jpa-SNAPSHOT` to `{page-causewaynextmajorversion}-jdo-SNAPSHOT` (should be a no-op) +. forward port from `{page-causewaycurrmajorversion}-jpa-SNAPSHOT` to `{page-causewaynextmajorversion}-jpa-SNAPSHOT` [NOTE] ==== diff --git a/antora/components/docs/modules/ROOT/pages/about.adoc b/antora/components/docs/modules/ROOT/pages/about.adoc index b21986be327..7655c9d1ff1 100644 --- a/antora/components/docs/modules/ROOT/pages/about.adoc +++ b/antora/components/docs/modules/ROOT/pages/about.adoc @@ -89,7 +89,6 @@ _Viewers_ _Persistence_ * xref:pjpa:ROOT:about.adoc[JPA (EclipseLink)] -* xref:pjdo:ROOT:about.adoc[JDO (DataNucleus)] | diff --git a/antora/components/docs/modules/ROOT/pages/landing-page/components.adoc b/antora/components/docs/modules/ROOT/pages/landing-page/components.adoc index 0d2e81c17c9..bc4b12b079b 100644 --- a/antora/components/docs/modules/ROOT/pages/landing-page/components.adoc +++ b/antora/components/docs/modules/ROOT/pages/landing-page/components.adoc @@ -33,15 +33,7 @@ Presents your domain objects in JSON representations, compliant either with link == Persistence -The framework allows xref:userguide:ROOT:domain-entities.adoc[domain entities] to be persisted using either: - -* the xref:pjpa:ROOT:about.adoc[JPA/Eclipselink] object store -+ -for use with JPA and link:https://spring.io/projects/spring-data-jpa[Spring Data JPA]. - -* the xref:pjdo:ROOT:about.adoc[JDO/DataNucleus object store] -+ -for use with the JDO API. +The framework allows xref:userguide:ROOT:domain-entities.adoc[domain entities] to be persisted using the xref:pjpa:ROOT:about.adoc[JPA/Eclipselink] object store, for use with JPA and link:https://spring.io/projects/spring-data-jpa[Spring Data JPA]. Alternatively, you can "roll your own" (by implementing the xref:refguide:applib:index/ViewModel.adoc[ViewModel] interface) and persist with any data persistence technology that is supported by Spring Boot. diff --git a/antora/components/docs/modules/ROOT/pages/what-is-apache-causeway/screencasts-older.txt b/antora/components/docs/modules/ROOT/pages/what-is-apache-causeway/screencasts-older.txt index 10158e6b4bf..4c9ce1910ca 100644 --- a/antora/components/docs/modules/ROOT/pages/what-is-apache-causeway/screencasts-older.txt +++ b/antora/components/docs/modules/ROOT/pages/what-is-apache-causeway/screencasts-older.txt @@ -46,18 +46,6 @@ _A run-through of the main features of the http://github.com/apache/causeway-app -|Setting up Eclipse + - -_How to import an Apache Causeway maven-based application into Eclipse and configure to use with JDO/DataNucleus_ + - -NB: when configuring DataNucleus for the *dom* project, make sure you are in the 'Java perspective', not the 'Java EE perspective'). + - -Learn more xref:setupguide:eclipse:about.adoc[here] - -|video::RgcYfjQ8yJA[youtube,width="420px",height="315px"] - - - |Setting up IntelliJ + _How to import an Apache Causeway maven-based application into IntelliJ and run the app._ + diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_021-logicalTypeName.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_021-logicalTypeName.adoc index d440e0ae918..ef0e61d176f 100644 --- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_021-logicalTypeName.adoc +++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_021-logicalTypeName.adoc @@ -33,14 +33,7 @@ public class Order { The rules of precedence are: . `@DomainObject#logicalTypeName` -. ORM-specific: - -.. JDO: xref:refguide:applib-ant:PersistenceCapable.adoc[@PersistenceCapable], if at least the `schema` attribute is defined. -+ -If both `schema` and `table` are defined, then the value is "`schema.table`". -If only `schema` is defined, then the value is "`schema.className`". - -.. (JPA) `@Table#schema()`. +. ORM-specific, `@Table#schema()`. . Fully qualified class name of the entity. diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_022-nature.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_022-nature.adoc index 707382aac1c..632f81eb9b5 100644 --- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_022-nature.adoc +++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_022-nature.adoc @@ -24,7 +24,7 @@ Specifically, the nature must be one of: * `ENTITY` + -indicates that the domain object is an entity whose persistence is managed internally by Apache Causeway, using the JDO/DataNucleus objectstore. +indicates that the domain object is an entity whose persistence is managed internally by Apache Causeway, using the xref:pjpa:ROOT:about.adoc[JPA/Eclipselink] objectstore. * `MIXIN` + diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_021-optionality.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_021-optionality.adoc index 94f5f844951..3437b101268 100644 --- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_021-optionality.adoc +++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_021-optionality.adoc @@ -8,11 +8,11 @@ By default, Apache Causeway assumes that all properties of an domain object or v The xref:applib:index/annotation/Property.adoc#optionality[optionality()] attribute allows this to be relaxed. The attribute is also supported for xref:refguide:applib:index/annotation/Parameter.adoc#optionality[parameters]. -That said, properties are most commonly defined on persistent domain objects (entities), in which case the JDO xref:refguide:applib-ant:Column.adoc[@Column] should be specified. +That said, properties are most commonly defined on persistent domain objects (entities), in which case the JPA xref:refguide:applib-ant:Column.adoc[@Column] should be specified. Apache Causeway can infer the maxLength directly from the equivalent @Column#length() annotation. -That said, properties are most commonly defined on persistent domain objects (entities), in which case the JDO xref:refguide:applib-ant:Column.adoc[@Column] will in any case need to be specified. -Apache Causeway can infer the `optionality` semantic directly from the equivalent `@Column#allowsNull()` annotation/attribute. +That said, properties are most commonly defined on persistent domain objects (entities), in which case the JPA xref:refguide:applib-ant:Column.adoc[@Column] will in any case need to be specified. +Apache Causeway can infer the `optionality` semantic directly from the equivalent `@Column#nullable()` annotation/attribute. For example: @@ -35,16 +35,16 @@ In this case there is no need for the `@Property#optionality` attribute. == Mismatched defaults -If the `@Column#allowsNull` attribute is omitted and the `@Property#optionality() attribute is also omitted, then note that Causeway' defaults and JDO's defaults differ. +If the `@Column#nullable` attribute is omitted and the `@Property#optionality() attribute is also omitted, then note that Causeway' defaults and JDO's defaults differ. Specifically, Causeway always assumes properties are mandatory, whereas JDO specifies that primitives are mandatory, but all reference types are optional. When Apache Causeway initializes it checks for these mismatches during its metamodel validation phase, and will fail to boot ("fail-fast") if there is a mismatch. -The fix is usually to add the `@Column#allowsNull()` annotation/attribute. +The fix is usually to add the `@Column#nullable()` annotation/attribute. == Superclass inheritance type -There is one case (at least) it may be necessary to annotate the property with both `@Column#allowsNull` and also `@Property#optionality()`. -If the property is logically mandatory and is in a subclass, but the mapping of the class hierarchy is to store both the superclass and subclass(es) into a single table (ie a "roll-up" mapping using `javax.jdo.annotations.InheritanceStrategy#SUPERCLASS_TABLE`), then JDO requires that the property is annotated as `@Column#allowsNull="true"`: its value will be not defined for other subclasses. +There is one case (at least) it may be necessary to annotate the property with both `@Column#nullable` and also `@Property#optionality()`. +If the property is logically mandatory and is in a subclass, but the mapping of the class hierarchy is to store both the superclass and subclass(es) into a single table (ie a "roll-up" mapping using `javax.jdo.annotations.InheritanceStrategy#SUPERCLASS_TABLE`), then JDO requires that the property is annotated as `@Column#nullable=true`: its value will be not defined for other subclasses. In this case we therefore require both annotations. diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_023-maxLength.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_023-maxLength.adoc index 64d539b6e3f..ae559970b0b 100644 --- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_023-maxLength.adoc +++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/Property_023-maxLength.adoc @@ -8,7 +8,7 @@ The xref:applib:index/annotation/Property.adoc#maxLength[maxLength()] attribute applies only to `String` properties, indicating the maximum number of characters that the user may enter (for example in a text field in the UI). The attribute It is ignored if applied to properties of any other type. -That said, properties are most commonly defined on persistent domain objects (entities), in which case the JDO xref:refguide:applib-ant:Column.adoc[@Column] will in any case need to be specified. +That said, properties are most commonly defined on persistent domain objects (entities), in which case the JPA xref:refguide:applib-ant:Column.adoc[@Column] will in any case need to be specified. Apache Causeway can infer the `maxLength` semantic directly from the equivalent `@Column#length()` annotation/attribute. For example: diff --git a/antora/components/refguide-index/modules/applib/pages/index/value/hooks/Blob_usage-notes.adoc b/antora/components/refguide-index/modules/applib/pages/index/value/hooks/Blob_usage-notes.adoc index 652e75d6267..e6399fc5cc8 100644 --- a/antora/components/refguide-index/modules/applib/pages/index/value/hooks/Blob_usage-notes.adoc +++ b/antora/components/refguide-index/modules/applib/pages/index/value/hooks/Blob_usage-notes.adoc @@ -4,20 +4,24 @@ == Usage Notes -If using xref:pjdo:ROOT:about.adoc[JDO/DataNucleus], `Blob` properties can be mapped using: +If using xref:pjpa:ROOT:about.adoc[JPA/Eclipselink], `Blob` properties can be mapped using the xref:refguide:persistence:index/jpa/applib/types/BlobJpaEmbeddable.adoc[]: [source,java] ---- [email protected](defaultFetchGroup="false") - @javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = { - @javax.jdo.annotations.Column(name = "attachment_name"), - @javax.jdo.annotations.Column(name = "attachment_mimetype"), - @javax.jdo.annotations.Column(name = "attachment_bytes", jdbcType = "BLOB", sqlType = "BLOB") - }) -@Property(optionality = Optionality.OPTIONAL) -@Getter @Setter -private Blob attachment; ----- - -If the property is mandatory, add `allowsNull = "false` for each of the ``@Column``s. +@AttributeOverrides({ + @AttributeOverride(name="name", column=@Column(name="attachment_name")), + @AttributeOverride(name="mimeType",column=@Column(name="attachment_mimeType")), + @AttributeOverride(name="bytes", column=@Column(name="attachment_bytes")) +}) +@Embedded +private BlobJpaEmbeddable attachment; +@Property() +@PropertyLayout() +public Blob getPdf() { + return BlobJpaEmbeddable.toBlob(pdf); +} +public void setPdf(final Blob pdf) { + this.pdf = BlobJpaEmbeddable.fromBlob(pdf); +} +---- diff --git a/antora/components/refguide-index/modules/applib/pages/index/value/hooks/Clob_usage-notes.adoc b/antora/components/refguide-index/modules/applib/pages/index/value/hooks/Clob_usage-notes.adoc index f79a2930be7..f74f612ac59 100644 --- a/antora/components/refguide-index/modules/applib/pages/index/value/hooks/Clob_usage-notes.adoc +++ b/antora/components/refguide-index/modules/applib/pages/index/value/hooks/Clob_usage-notes.adoc @@ -2,21 +2,26 @@ :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-partial: - == Usage Notes -If using xref:pjdo:ROOT:about.adoc[JDO/DataNucleus], `Clob` properties can be mapped using: +If using xref:pjpa:ROOT:about.adoc[JPA/Eclipselink], `Blob` properties can be mapped using the xref:refguide:persistence:index/jpa/applib/types/ClobJpaEmbeddable.adoc[]: [source,java] ---- [email protected](defaultFetchGroup="false", columns = { - @javax.jdo.annotations.Column(name = "doc_name"), - @javax.jdo.annotations.Column(name = "doc_mimetype"), - @javax.jdo.annotations.Column(name = "doc_chars", jdbcType = "CLOB", sqlType = "CLOB") +@AttributeOverrides({ + @AttributeOverride(name="name", column=@Column(name="doc_name")), + @AttributeOverride(name="mimeType",column=@Column(name="doc_mimeType")), + @AttributeOverride(name="bytes", column=@Column(name="doc_bytes")) }) -@Property( optionality = Optionality.OPTIONAL ) @Getter @Setter -private Clob doc; ----- +private ClobJpaEmbeddable doc; -If the property is mandatory, add `allowsNull = "false` for each of the ``@Column``s. +@Property() +@PropertyLayout() +public Clob getDoc() { + return ClobJpaEmbeddable.toClob(doc); +} +public void setDoc(final Clob doc) { + this.doc = ClobJpaEmbeddable.fromClob(doc); +} +---- diff --git a/antora/components/refguide/modules/applib-ant/pages/Column.adoc b/antora/components/refguide/modules/applib-ant/pages/Column.adoc index 65602681f70..f04ab36ad42 100644 --- a/antora/components/refguide/modules/applib-ant/pages/Column.adoc +++ b/antora/components/refguide/modules/applib-ant/pages/Column.adoc @@ -1,27 +1,25 @@ -[#javax-jdo-annotation-Column] -= @Column (jdo) +[#jakarta-persistence-Column] += @Column (jpa) :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 [...] +// TODO: 3866 - to update, this mostly refers to JDO. -The JDO `@javax.jdo.annotation.Column` provides metadata describing how JDO/DataNucleus should persist the property to a database RDBMS table column (or equivalent concept for other persistence stores). +The JPA `@jakarta.persistence.Column` provides metadata describing how JPA should persist the property to a database RDBMS table column (or equivalent concept for other persistence stores). Apache Causeway also parses and interprets this annotation in order to build up aspects of its metamodel. [NOTE] ==== -Apache Causeway parses the `@Column` annotation from the Java source code; it does not query the JDO metamodel. -This means that it the `@Column` annotation must be used rather than the equivalent `<column>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/orm/schema_mapping.html[XML metadata]. - -Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Apache Causeway (currently) only inspects the getter method. -Therefore ensure that the annotation is placed there. +Apache Causeway parses the `@Column` annotation from the Java source code; it does not query the JPA metamodel. +This means that it the `@Column` annotation must be used rather than XML metadata.. ==== This section identifies which attributes of `@Column` are recognized and used by Apache Causeway. [#nullability] == Nullability - +ñ The `allowsNull` attribute is used to specify if a property is mandatory or is optional. For example: @@ -29,7 +27,7 @@ For example: [source,java] ---- public class Customer { - @javax.jdo.annotations.Column(allowsNull="true") + @jakarta.persistence.Column(nullable=true˜) public String getMiddleInitial() { /* ... */ } public void setMiddleInitial(String middleInitial) { /* ... */ } ---- @@ -37,12 +35,12 @@ public class Customer { Causeway also provides xref:refguide:applib:index/annotation/Property.adoc#optionality[@Property#optionality] attribute. If both are specified, Apache Causeway will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are. -You should also be aware that in the lack of either the `@Column#allowsNull` or the `@Property#optionality` attributes, that the JDO and Apache Causeway defaults differ. +You should also be aware that in the lack of either the `@Column#nullable` or the `@Property#optionality` attributes, that the JDO and Apache Causeway defaults differ. Apache Causeway rule is straight-forward: properties are assumed to be required. JDO on the other hand specifies that only primitive types are mandatory; everything else is assumed to be optional. Therefore a lack of either annotation can also trigger the fail-fast validation check. -In the vast majority of cases you should be fine just to add the `@Column#allowsNull` attribute to the getter. +In the vast majority of cases you should be fine just to add the `@Column#nullable` attribute to the getter. But see the documentation for xref:refguide:applib:index/annotation/Property.adoc#optionality[@Property#optionality] attribute for discussion on one or two minor edge cases. [#length-for-strings] diff --git a/antora/components/refguide/modules/applib-ant/pages/Digits.adoc b/antora/components/refguide/modules/applib-ant/pages/Digits.adoc index 7f2bb50fe1f..cfa01d53e1e 100644 --- a/antora/components/refguide/modules/applib-ant/pages/Digits.adoc +++ b/antora/components/refguide/modules/applib-ant/pages/Digits.adoc @@ -4,6 +4,7 @@ :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 [...] +// TODO: 3866 - remove The `@javax.validation.constraints.Digits` annotation is recognized by Apache Causeway as a means to specify the precision for properties and action parameters of type `java.math.BigDecimal`. @@ -27,7 +28,7 @@ public void setCost(final BigDecimal cost) { :null; } ---- -<.> the xref:refguide:applib-ant:Column.adoc[@Column#scale] attribute must be ... +<.> the ˜xref:refguide:applib-ant:Column.adoc[@Column#scale] attribute must be ... <.> ... consistent with `@Digits#fraction()` <.> the correct idiom when setting a new value is to normalized to the correct scale diff --git a/antora/components/refguide/modules/applib-ant/pages/Discriminator.adoc b/antora/components/refguide/modules/applib-ant/pages/Discriminator.adoc deleted file mode 100644 index 4a0af0f4459..00000000000 --- a/antora/components/refguide/modules/applib-ant/pages/Discriminator.adoc +++ /dev/null @@ -1,68 +0,0 @@ -[#javax-jdo-annotation-Discrimnator] -= @Discriminator (`jdo`) - -: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 `@javax.jdo.annotation.Discriminator` is used by JDO/DataNucleus to specify how to discriminate between subclasses of an inheritance hierarchy. - -It is valid to add a `@Discriminator` for any class, even those not part of an explicitly mapped inheritance hierarchy. -Apache Causeway also checks for this annotation, and if present will use the `@Discriminator#value()` as the object type, a unique alias for the object's class name. - -[NOTE] -==== -Causeway parses the `@Discriminator` annotation from the Java source code; it does not query the JDO metamodel. -This means that it the `@Discriminator` annotation must be used rather than the equivalent `<discriminator>` link:https://www.datanucleus.org/products/accessplatform_6_0/jdo/metadata_xml.html[XML metadata]. -==== - -This value is used internally to generate a string representation of an objects identity (the `Oid`). -This can appear in several contexts, including: - -* as the value of `Bookmark#getObjectType()` and in the `toString()` value of `Bookmark` -(see xref:refguide:applib:index/services/bookmark/BookmarkService.adoc[BookmarkService]) -* in the serialization of `OidDto` in the xref:refguide:schema:cmd.adoc[command] and xref:refguide:schema:ixn.adoc[interaction] schemas -* in the URLs of the xref:vro:ROOT:about.adoc[RestfulObjects viewer] -* in the URLs of the xref:vw:ROOT:about.adoc[Web UI (Wicket viewer)] -* in XML snapshots generated by the xref:refguide:applib:index/services/xmlsnapshot/XmlSnapshotService.adoc[XmlSnapshotService] - -== Examples - -For example: - -[source,java] ----- [email protected](value="custmgmt.Customer") -public class Customer { - ... -} ----- - -has an object type of `custmgmt.Customer`. - -== Precedence - -The rules of precedence for determining a domain object's object type are: - -1. xref:refguide:applib-ant:Discriminator.adoc[@Discriminator] -2. `@DomainObject#logicalTypeName` -3. xref:refguide:applib-ant:PersistenceCapable.adoc[@PersistenceCapable], if at least the `schema` attribute is defined. -+ -If both `schema` and `table` are defined, then the value is "`schema.table`". -If only `schema` is defined, then the value is "`schema.className`". - -4. Fully qualified class name of the entity. - -[TIP] -==== -This might be obvious, but to make explicit: we recommend that you always specify an object type for your domain objects. - -Otherwise, if you refactor your code (change class name or move package), then any externally held references to the OID of the object will break. -At best this will require a data migration in the database; at worst it could cause external clients accessing data through the xref:vro:ROOT:about.adoc[Restful Objects] viewer to break. -==== - -[NOTE] -==== -If the object type is not unique across all domain classes then the framework will fail-fast and fail to boot. -An error message will be printed in the log to help you determine which classes have duplicate object tyoes. -==== diff --git a/antora/components/refguide/modules/applib-ant/pages/Entity.adoc b/antora/components/refguide/modules/applib-ant/pages/Entity.adoc index 71c12350ade..b09b856f1e9 100644 --- a/antora/components/refguide/modules/applib-ant/pages/Entity.adoc +++ b/antora/components/refguide/modules/applib-ant/pages/Entity.adoc @@ -1,96 +1,18 @@ -[#javax-jdo-annotation-PersistenceCapable] -= @PersistenceCapable (jdo) +[#jakarta-persistence-Entity] += @Entity (jpa) :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 [...] +// TODO: 3866 - to update +The `@jakarta.persistence.Entity` is used by JPA to indicate that a class is a domain entity to be persisted to the database. -The `@javax.jdo.annotation.PersistenceCapable` is used by JDO/DataNucleus to indicate that a class is a domain entity to be persisted to the database. - -Apache Causeway also checks for this annotation, and if the `@PersistenceCapable#schema` attribute is present will use it to form the object type. +Apache Causeway also checks for this annotation ... [NOTE] ==== -Causeway parses the `@PersistenceCapable` annotation from the Java source code; it does not query the JDO metamodel. -This means that it the `@PersistenceCapable` annotation must be used rather than the equivalent `<class>` link:https://www.datanucleus.org/products/accessplatform_6_0/jdo/metadata_xml.html[XML metadata]. - -Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Apache Causeway (currently) only inspects the getter method. -Therefore ensure that the annotation is placed there. -==== - -This value is used internally to generate a string representation of an objects identity (the `Oid`). -This can appear in several contexts, including: - -* as the value of `Bookmark#getObjectType()` and in the `toString()` value of `Bookmark` -(see xref:refguide:applib:index/services/bookmark/BookmarkService.adoc[BookmarkService]) -* in the serialization of `OidDto` in the xref:refguide:schema:cmd.adoc[command] and xref:refguide:schema:ixn.adoc[interaction] schemas -* in the URLs of the xref:vro:ROOT:about.adoc[RestfulObjects viewer] -* in the URLs of the xref:vw:ROOT:about.adoc[Web UI (Wicket viewer)] -* in XML snapshots generated by the xref:refguide:applib:index/services/xmlsnapshot/XmlSnapshotService.adoc[XmlSnapshotService] - - -The actual format of the object type used by Apache Causeway for the concatenation of `schema()` and `@PersistenceCapable#table()`. -If the `table()` is not present, then the class' simple name is used instead. - -== Examples - -For example: - -[source,java] ----- [email protected](schema="custmgmt") -public class Customer { - ... -} ----- - -has an object type of `custmgmt.Customer`, while: - -[source,java] ----- [email protected](schema="custmgmt", table="Address") -public class AddressImpl { - ... -} ----- - -has an object type of `custmgmt.Address`. - -On the other hand: - -[source,java] ----- [email protected](table="Address") -public class AddressImpl { - ... -} ----- - -does _not_ correspond to an object type, because the `schema` attribute is missing. - -== Precedence - -The rules of precedence for determining a domain object's object type are: - -1. xref:refguide:applib-ant:Discriminator.adoc[@Discriminator] -2. `@DomainObject#logicalTypeName` -3. xref:refguide:applib-ant:PersistenceCapable.adoc[@PersistenceCapable], if at least the `schema` attribute is defined. -+ -If both `schema` and `table` are defined, then the value is "`schema.table`". -If only `schema` is defined, then the value is "`schema.className`". - -4. Fully qualified class name of the entity. - -[TIP] -==== -This might be obvious, but to make explicit: we recommend that you always specify an object type for your domain objects. - -Otherwise, if you refactor your code (change class name or move package), then any externally held references to the OID of the object will break. -At best this will require a data migration in the database; at worst it could cause external clients accessing data through the xref:vro:ROOT:about.adoc[Restful Objects] viewer to break. +Causeway parses the `@Entity` annotation from the Java source code; it does not query the JPA metamodel. +This means that it the `@Entity` annotation must be used rather than the equivalent XML metadata. ==== -[NOTE] -==== -If the object type is not unique across all domain classes then the framework will fail-fast and fail to boot. -An error message will be printed in the log to help you determine which classes have duplicate object tyoes. -==== +... diff --git a/antora/components/refguide/modules/applib-ant/pages/NotPersistent.adoc b/antora/components/refguide/modules/applib-ant/pages/NotPersistent.adoc deleted file mode 100644 index cea9e5d8e92..00000000000 --- a/antora/components/refguide/modules/applib-ant/pages/NotPersistent.adoc +++ /dev/null @@ -1,19 +0,0 @@ -[#javax-jdo-annotation-NotPersistent] -= @NotPersistent (jdo) - -: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 `@javax.jdo.annotation.NotPersistent` annotation is used by JDO/DataNucleus to indicate that a property should not be persisted to the database. - -Apache Causeway also uses this annotation, though (currently) only in the very minimal way to suppress checking of inconsistent metadata between JDO and Causeway annotations (eg `@Column#allowsNull()` vs `@Property#optionality()`, or `@Column#length()` and `@Property#maxLength()`). - -[NOTE] -==== -The framework parses the `@NotPersistent` annotation from the Java source code; it does not query the JDO metamodel. -This means that it the `@NotPersistent` annotation must be used rather than the equivalent `<field>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/fields_properties.html[XML metadata]. - -Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Apache Causeway (currently) only inspects the getter method. -Therefore ensure that the annotation is placed there. -==== - diff --git a/antora/components/refguide/modules/applib-ant/pages/Nullable.adoc b/antora/components/refguide/modules/applib-ant/pages/Nullable.adoc index 746a39b6493..e23ded529ff 100644 --- a/antora/components/refguide/modules/applib-ant/pages/Nullable.adoc +++ b/antora/components/refguide/modules/applib-ant/pages/Nullable.adoc @@ -3,6 +3,8 @@ :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 [...] +// TODO: 3866 - remove + Apache Causeway' defaults for properties and parameters is that they are mandatory unless otherwise stated. The `@javax.annotation.Nullable` annotation is recognized by Apache Causeway for both properties and parameters as means to indicate that the property/parameter is not mandatory. @@ -33,13 +35,13 @@ public Customer updateName(@javax.annotation.Nullable final String name) { Apache Causeway does provide several other ways to specify optionality: using the xref:refguide:applib:index/annotation/Property.adoc#optionality[@Property#optionality()] / xref:refguide:applib:index/annotation/Parameter.adoc#optionality[@Parameter#optionality()] annotation. -For properties, the optionality can also be inferred from the xref:refguide:applib-ant:Column.adoc#nullability[@Column#allowsNull()] attribute. +For properties, the optionality can also be inferred from the JPA xref:refguide:applib-ant:Column.adoc#nullability[@Column#nullable()] attribute. [TIP] ==== See the xref:refguide:applib:index/annotation/Property.adoc#optionality[@Property#optionality()] documentation for a much fuller discussion on the relationship between using the Apache Causeway annotations vs -xref:refguide:applib-ant:Column.adoc#nullability[@Column#allowsNull()]. +xref:refguide:applib-ant:Column.adoc#nullability[@Column#nullable()]. ==== If more than one method is specified then the framework will validate that there are no incompatibilities (and fail to boot otherwise). diff --git a/antora/components/refguide/modules/applib-ant/pages/Pattern.adoc b/antora/components/refguide/modules/applib-ant/pages/Pattern.adoc index 47d61e2b18b..de330fed4ea 100644 --- a/antora/components/refguide/modules/applib-ant/pages/Pattern.adoc +++ b/antora/components/refguide/modules/applib-ant/pages/Pattern.adoc @@ -3,6 +3,7 @@ :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 [...] +// TODO: 3866 - remove The `@javax.validation.constraints.Pattern` annotation is recognized by Apache Causeway as a means to specify a regular expression constraint for properties and action parameters of type `java.lang.String`. diff --git a/antora/components/refguide/modules/applib-ant/pages/PersistenceCapable.adoc b/antora/components/refguide/modules/applib-ant/pages/PersistenceCapable.adoc deleted file mode 100644 index ac815b39825..00000000000 --- a/antora/components/refguide/modules/applib-ant/pages/PersistenceCapable.adoc +++ /dev/null @@ -1,93 +0,0 @@ -[#javax-jdo-annotation-PersistenceCapable] -= @PersistenceCapable (jdo) - -: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 `@javax.jdo.annotation.PersistenceCapable` is used by JDO/DataNucleus to indicate that a class is a domain entity to be persisted to the database. - -Apache Causeway also checks for this annotation, and if the `@PersistenceCapable#schema` attribute is present will use it to form the object type. - -[NOTE] -==== -Causeway parses the `@PersistenceCapable` annotation from the Java source code; it does not query the JDO metamodel. -This means that it the `@PersistenceCapable` annotation must be used rather than the equivalent `<class>` link:https://www.datanucleus.org/products/accessplatform_6_0/jdo/metadata_xml.html[XML metadata]. -==== - -This value is used internally to generate a string representation of an objects identity (the `Oid`). -This can appear in several contexts, including: - -* as the value of `Bookmark#getObjectType()` and in the `toString()` value of `Bookmark` -(see xref:refguide:applib:index/services/bookmark/BookmarkService.adoc[BookmarkService]) -* in the serialization of `OidDto` in the xref:refguide:schema:cmd.adoc[command] and xref:refguide:schema:ixn.adoc[interaction] schemas -* in the URLs of the xref:vro:ROOT:about.adoc[RestfulObjects viewer] -* in the URLs of the xref:vw:ROOT:about.adoc[Web UI (Wicket viewer)] -* in XML snapshots generated by the xref:refguide:applib:index/services/xmlsnapshot/XmlSnapshotService.adoc[XmlSnapshotService] - - -The actual format of the object type used by Apache Causeway for the concatenation of `schema()` and `@PersistenceCapable#table()`. -If the `table()` is not present, then the class' simple name is used instead. - -== Examples - -For example: - -[source,java] ----- [email protected](schema="custmgmt") -public class Customer { - ... -} ----- - -has an object type of `custmgmt.Customer`, while: - -[source,java] ----- [email protected](schema="custmgmt", table="Address") -public class AddressImpl { - ... -} ----- - -has an object type of `custmgmt.Address`. - -On the other hand: - -[source,java] ----- [email protected](table="Address") -public class AddressImpl { - ... -} ----- - -does _not_ correspond to an object type, because the `schema` attribute is missing. - -== Precedence - -The rules of precedence for determining a domain object's object type are: - -1. xref:refguide:applib-ant:Discriminator.adoc[@Discriminator] -2. `@DomainObject#logicalTypeName` -3. xref:refguide:applib-ant:PersistenceCapable.adoc[@PersistenceCapable], if at least the `schema` attribute is defined. -+ -If both `schema` and `table` are defined, then the value is "`schema.table`". -If only `schema` is defined, then the value is "`schema.className`". - -4. Fully qualified class name of the entity. - -[TIP] -==== -This might be obvious, but to make explicit: we recommend that you always specify an object type for your domain objects. - -Otherwise, if you refactor your code (change class name or move package), then any externally held references to the OID of the object will break. -At best this will require a data migration in the database; at worst it could cause external clients accessing data through the xref:vro:ROOT:about.adoc[Restful Objects] viewer to break. -==== - -[NOTE] -==== -If the object type is not unique across all domain classes then the framework will fail-fast and fail to boot. -An error message will be printed in the log to help you determine which classes have duplicate object tyoes. -==== diff --git a/antora/components/refguide/modules/applib-ant/pages/PrimaryKey.adoc b/antora/components/refguide/modules/applib-ant/pages/PrimaryKey.adoc deleted file mode 100644 index 5f0c991c69f..00000000000 --- a/antora/components/refguide/modules/applib-ant/pages/PrimaryKey.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[#javax-jdo-annotation-PrimaryKey] -= @PrimaryKey (jdo) - -: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 `@javax.jdo.annotation.PrimaryKey` annotation is used by JDO/DataNucleus to indicate that a property is used as the primary key for an entity with application-managed identity. - -Apache Causeway also uses this annotation in a very minimal way: to ensure that the framework's own logic to initialize newly instantiated objects (eg using xref:refguide:applib:index/services/factory/FactoryService.adoc[FactoryService#create(...)] does not touch the primary key, and also to ensure that the primary key property is always disabled (read-only). - -[NOTE] -==== -Apache Causeway parses the `@NotPersistent` annotation from the Java source code; it does not query the JDO metamodel. -This means that it the `@NotPersistent` annotation must be used rather than the equivalent `<field>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/application_identity.html[XML metadata]. - -Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Apache Causeway (currently) only inspects the getter method. -Therefore ensure that the annotation is placed there. -==== - diff --git a/antora/components/userguide/modules/ROOT/partials/meta-annotations/_intro.adoc b/antora/components/refguide/modules/applib-ant/pages/Table.adoc similarity index 59% copy from antora/components/userguide/modules/ROOT/partials/meta-annotations/_intro.adoc copy to antora/components/refguide/modules/applib-ant/pages/Table.adoc index 08fffaf8346..d08b0c5ab99 100644 --- a/antora/components/userguide/modules/ROOT/partials/meta-annotations/_intro.adoc +++ b/antora/components/refguide/modules/applib-ant/pages/Table.adoc @@ -1,12 +1,12 @@ -[[introduction]] -= Introduction +[#jakarta-persistence-Table] += @Table (jpa) :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-partial: +// TODO: 3866 - to complete +The JPA `@jakarta.persistence.Table` provides metadata describing how JPA ... + +Apache Causeway also parses and interprets this annotation in order to ... -Apache Causeway supports the use of meta-annotations, as does Spring Boot and the ORM (xref:pjpa:ROOT:about.adoc[JPA/EclipseLink] from Eclipse 2.7 supporting JPA 2.2, xref:pjdo:ROOT:about.adoc[JDO/DataNucleus] for DN 6.x). -This allows you to define custom annotations that are more descriptive of your domain model, and meta-annotate your custom annotations with those of Apache Causeway, Spring or the ORM. -In your domain model, you can just use the custom annotation. diff --git a/antora/components/refguide/modules/applib-ant/partials/module-nav.adoc b/antora/components/refguide/modules/applib-ant/partials/module-nav.adoc index 82033e893b9..fa00e8a2f53 100644 --- a/antora/components/refguide/modules/applib-ant/partials/module-nav.adoc +++ b/antora/components/refguide/modules/applib-ant/partials/module-nav.adoc @@ -50,11 +50,8 @@ ** JPA *** xref:refguide:applib-ant:Entity.adoc[@Entity] - -** JDO +*** xref:refguide:applib-ant:Table.adoc[@Table] +*** xref:refguide:applib-ant:Transient.adoc[@Transient] *** xref:refguide:applib-ant:Column.adoc[@Column] -*** xref:refguide:applib-ant:Discriminator.adoc[@Discriminator] -*** xref:refguide:applib-ant:NotPersistent.adoc[@NotPersistent] -*** xref:refguide:applib-ant:PersistenceCapable.adoc[@PersistenceCapable] -*** xref:refguide:applib-ant:PrimaryKey.adoc[@PrimaryKey] + diff --git a/antora/components/refguide/modules/applib-svc/pages/about.adoc b/antora/components/refguide/modules/applib-svc/pages/about.adoc index 3c562586649..2004d5e61b7 100644 --- a/antora/components/refguide/modules/applib-svc/pages/about.adoc +++ b/antora/components/refguide/modules/applib-svc/pages/about.adoc @@ -87,7 +87,7 @@ public class Customer { You may also need to `@Import` the module that contains the service into your application's `AppManifest` (though all of the services in core will be available automatically). -For objects that are already persisted, the service is automatically injected just after the object is rehydrated by JDO/DataNucleus. +For objects that are already persisted, the service is automatically injected just after the object is rehydrated by JPA/EclipseLink. For transient objects (instantiated programmatically), the xref:refguide:applib:index/services/factory/FactoryService.adoc[FactoryService#viewModel(...)] or the xref:refguide:applib:index/services/repository/RepositoryService.adoc[RepositoryService#detachedEntity(...)]'s will automatically inject the services. diff --git a/antora/components/relnotes/modules/ROOT/partials/2018/2.0.0-M1/mignotes/removed-annotations.adoc b/antora/components/relnotes/modules/ROOT/partials/2018/2.0.0-M1/mignotes/removed-annotations.adoc index f7095d51b2d..10b95aeba54 100644 --- a/antora/components/relnotes/modules/ROOT/partials/2018/2.0.0-M1/mignotes/removed-annotations.adoc +++ b/antora/components/relnotes/modules/ROOT/partials/2018/2.0.0-M1/mignotes/removed-annotations.adoc @@ -139,7 +139,7 @@ Similarly, the `Bulk.InteractionContext` domain service is replaced with the lin | |Either link:https://isis.apache.org/versions/2.0.0-M1/guides/rgant/rgant.html#_rgant_Property_optionality[@Property#optionality()] or link:https://isis.apache.org/versions/2.0.0-M1/guides/rgant/rgant.html#_rgant_Parameter_optionality[@Parameter#optionality()]. -For properties, can also use link:https://isis.apache.org/versions/2.0.0-M1/guides/rgant/rgant.html#_rgant_Column_allowsNull[@Column#allowsNull()] +For properties, can also use link:https://isis.apache.org/versions/2.0.0-M1/guides/rgant/rgant.html#_rgant_Column_allowsNull[@Column#nullable()] Can also use link:https://isis.apache.org/versions/2.0.0-M1/guides/rgant/rgant.html#_rgant_Nullable[@Nullable] for either properties or parameters. |`@Mask` @@ -172,7 +172,7 @@ For properties, can also use link:https://isis.apache.org/versions/2.0.0-M1/guid | |Either link:https://isis.apache.org/versions/2.0.0-M1/guides/rgant/rgant.html#_rgant_Property_optionality[@Property#optionality()] or link:https://isis.apache.org/versions/2.0.0-M1/guides/rgant/rgant.html#_rgant_Parameter_optionality[@Parameter#optionality()]. -For properties, can also use link:https://isis.apache.org/versions/2.0.0-M1/guides/rgant/rgant.html#_rgant_Column_allowsNull[@Column#allowsNull()] +For properties, can also use link:https://isis.apache.org/versions/2.0.0-M1/guides/rgant/rgant.html#_rgant_Column_allowsNull[@Column#nullable()] Can also use link:https://isis.apache.org/versions/2.0.0-M1/guides/rgant/rgant.html#_rgant_Nullable[@Nullable] for either properties or parameters. |`@Named` diff --git a/antora/components/relnotes/modules/ROOT/partials/2024/2.0.0/_relnotes.adoc b/antora/components/relnotes/modules/ROOT/partials/2024/2.0.0/_relnotes.adoc index 1fb9d1718d3..5f195b5a5ea 100644 --- a/antora/components/relnotes/modules/ROOT/partials/2024/2.0.0/_relnotes.adoc +++ b/antora/components/relnotes/modules/ROOT/partials/2024/2.0.0/_relnotes.adoc @@ -50,7 +50,7 @@ | DataNucleus | 6.0.7 | 6.0.7 -| xref:pjdo::about.adoc[] +| JDO |=== @@ -59,12 +59,11 @@ Other highlights * xref:pjpa:ROOT:about.adoc[Persistence using JPA] has been added through an integration of EclipseLink. + -xref:pjdo::about.adoc[Persistence using JDO] continues to be supported through the integration with DataNucleus. +Persistence using JDO continues to be supported through the integration with DataNucleus. + [NOTE] ==== -We use EclipseLink rather than Hibernate because the latter is licensed using LGPL, which is incompatible with ASF licensing. -In addition, EclipseLink is the reference implementation for JPA. +We use EclipseLink rather than Hibernate because historically the latter was licensed using LGPL, which is incompatible with ASF licensing. ==== + diff --git a/antora/components/relnotes/modules/ROOT/partials/2024/2.1.0/_relnotes.adoc b/antora/components/relnotes/modules/ROOT/partials/2024/2.1.0/_relnotes.adoc index 9a592e391b4..90d9133d54f 100644 --- a/antora/components/relnotes/modules/ROOT/partials/2024/2.1.0/_relnotes.adoc +++ b/antora/components/relnotes/modules/ROOT/partials/2024/2.1.0/_relnotes.adoc @@ -51,7 +51,7 @@ | DataNucleus | 6.0.7 | 6.0.7 -| xref:pjdo::about.adoc[] +| JDO | Shiro | 1.13.0 diff --git a/antora/components/setupguide/modules/eclipse/pages/about.adoc b/antora/components/setupguide/modules/eclipse/pages/about.adoc index 7e73ae7916f..1bda73a87e6 100644 --- a/antora/components/setupguide/modules/eclipse/pages/about.adoc +++ b/antora/components/setupguide/modules/eclipse/pages/about.adoc @@ -271,7 +271,7 @@ If you consistently hit problems, then the final recourse is to disable the auto // //In the context of Apache Causeway, this is very useful for contributed actions and mixins and also view models; you should then be able to write these actions and have them be picked up without restarting the application. // -//Changing persisting domain entities is more problematic, for two reasons: the JDO/DataNucleus enhancer needs to run on domain entities, and also at runtime JDO/DataNucleus would need to rebuild its own metamodel. +//Changing persisting domain entities is more problematic becaue at runtime the JPA persistence mechanism would need to rebuild its own metamodel. //You may find that adding actions will work, but adding new properties or collections is much less likely to. // //For details of setting up DCEVM, see the xref:setupguide:intellij:hints-and-tips.adoc#setting-up-dcevm[corresponding section] in the IntelliJ documentation. diff --git a/antora/components/setupguide/modules/intellij/pages/about.adoc b/antora/components/setupguide/modules/intellij/pages/about.adoc index 9a915df14ac..2beb8d211ec 100644 --- a/antora/components/setupguide/modules/intellij/pages/about.adoc +++ b/antora/components/setupguide/modules/intellij/pages/about.adoc @@ -69,7 +69,7 @@ image::040-other-settings-compiler/020-annotation-processor.png[width="1000px"] [TIP] ==== -If using xref:pjdo:ROOT:about.adoc[JDO/DataNucleus], this setting enables the generation of the `Q*` classes for DataNucleus type-safe queries. +If using QueryDSL, this setting enables the generation of the `Q*` classes for type-safe queries. It is also required for frameworks such as link:https://projectlombok.org[Lombok]. ==== @@ -115,9 +115,7 @@ Let's see how to run both the app and the tests. We run the application by creating a Run configuration, using `Run > Edit Configurations`. -There is one complication, which is the ORM. -If the app uses xref:pjpa:ROOT:about.adoc[JPA], then dynamic class weaving should be configured. -If the app uses xref:pjdo:ROOT:about.adoc[JDO], then Datanucleus enhancer should be configured. +We also configure dynamic class weaving for the xref:pjpa:ROOT:about.adoc[JPA/EclipseLink] ORM. === Running the App (JPA) diff --git a/antora/components/userguide/modules/ROOT/partials/_deployment-options.adoc b/antora/components/userguide/modules/ROOT/partials/_deployment-options.adoc index 154109574a9..68353ec6c0e 100644 --- a/antora/components/userguide/modules/ROOT/partials/_deployment-options.adoc +++ b/antora/components/userguide/modules/ROOT/partials/_deployment-options.adoc @@ -23,10 +23,7 @@ The principal implementation is the xref:vw:ROOT:about.adoc[Web UI (Wicket viewe The framework provides a xref:extensions:ROOT:about.adoc[number of these]. Deploying on Apache Causeway means that the framework also manages object persistence. -Again this is pluggable. -There are two implementations, either xref:pjdo:ROOT:about.adoc[JDO (DataNucleus)] or xref:pjpa:ROOT:about.adoc[JPA (EclipseLink)]. -These are normally used with an RDBMS, though in principle could be used with NoSQL databases. -JDO/DataNucleus historically has link:https://www.datanucleus.org/products/accessplatform/datastores/datastores.html[extensive support] for NoSQL, though JPA/EclipseLink also has link:https://wiki.eclipse.org/EclipseLink/FAQ/NoSQL[some support] also. +Again this is pluggable, currently only the xref:pjpa:ROOT:about.adoc[JPA (EclipseLink)] implementation is supported. [#deploy-with-custom-controllers] @@ -67,7 +64,7 @@ At the time of writing there are a couple being developed, link:https://github.c Another framework that implements the RO spec is the link:https://github.com/NakedObjectsGroup/NakedObjectsFramework[Naked Objects Framework] (on .NET). It provides a complete generic UI tested against its own RO implementation. -As for the human-usable generic UI discussed xref:#deploy-with-a-generic-ui[above], the framework manages object persistence, for example using the JDO/DataNucleus objectstore. +As for the human-usable generic UI discussed xref:#deploy-with-a-generic-ui[above], the framework manages object persistence, for example using the JPA/EclipseLink objectstore. It is perfectly possible to deploy the RESTful API alongside an auto-generated webapp; both work from the same domain object model. diff --git a/antora/components/userguide/modules/ROOT/partials/domain-entities/_intro.adoc b/antora/components/userguide/modules/ROOT/partials/domain-entities/_intro.adoc index 908bd7f63b5..b6b0f0c3f0c 100644 --- a/antora/components/userguide/modules/ROOT/partials/domain-entities/_intro.adoc +++ b/antora/components/userguide/modules/ROOT/partials/domain-entities/_intro.adoc @@ -5,7 +5,7 @@ :page-partial: Most domain objects that the end-user interacts with are likely to be _domain entities_, such as `Customer`, `Order`, `Product` and so on. -These are persistent objects and which are mapped to a relational database using either xref:pjpa::about.adoc[JPA/EclipseLink] or xref:pjdo::about.adoc[JDO/DataNucleus] ORM. +These are persistent objects and which are mapped to a relational database using xref:pjpa::about.adoc[JPA/EclipseLink] ORM. Some domain entities are really aggregates, a combination of multiple objects. A commonly cited example of this is an `Order`, which really consists of both a root `Order` entity and a collection of ``OrderItem``s. diff --git a/antora/components/userguide/modules/ROOT/partials/domain-services/crud.adoc b/antora/components/userguide/modules/ROOT/partials/domain-services/crud.adoc index 3924877ea35..862077f3cf7 100644 --- a/antora/components/userguide/modules/ROOT/partials/domain-services/crud.adoc +++ b/antora/components/userguide/modules/ROOT/partials/domain-services/crud.adoc @@ -113,17 +113,32 @@ repositoryService.persistAndFlush(customer); When an object is persisted the framework will emit `ObjectPersistingEvent` and `ObjectPersistedEvent` xref:userguide:ROOT:events.adoc#lifecycle-events[lifecycle events]. -=== Persistence by Reachability (JDO) +=== Persistence by Reachability (JPA) -If using xref:pjdo:ROOT:about.adoc[JDO/DataNucleus], it is possible to configure ORM to automatically persist domain entities if they are associated with other already-persistent entities. -This avoid the need to explicitly call "persist". +If using xref:pjpa:ROOT:about.adoc[JPA/Eclipselink], it is possible to configure ORM to automatically persist domain entities if they are associated with other already-persistent entities. +This avoids the need to explicitly call "persist". -This is done using xref:refguide:config:sections/datanucleus.adoc#datanucleus.persistence-by-reachability-at-commit[persistence-by-reachability] configuration property: +This is done by annotating the relationship with a `CascadeType` of `CascadeType.PERSIST` or `CascadeType.ALL`. +For example: -[source,ini] -.application.properties +[source,java] ---- -datanucleus.persistence-by-reachability-at-commit=true +@Entity +public class Parent { + @OneToMany(cascade = CascadeType.PERSIST) + private List<Child> children = new ArrayList<>(); +} + +@Entity +public class Child { + @ManyToOne + private Parent parent; +} + +// Usage: +Parent p = new Parent(); +p.getChildren().add(new Child()); +em.persist(p); ---- One downside is that the code is arguably less easy to debug, and there may be performance implications. @@ -205,73 +220,9 @@ public class CustomerRepository { <.> The `:name` parameter in the query JPQL string, and its corresponding value -[[finding-jdo]] -=== Finding Objects (JDO) - - -In the case of xref:pjdo:ROOT:about.adoc[JDO/DataNucleus], it typically requires a JDOQL query defined on the domain entity, and a corresponding repository service for that domain entity type. -This repository calls the framework-provided xref:refguide:applib:index/services/repository/RepositoryService.adoc[RepositoryService] to actually submit the query. - -For example: - -[source,java] ----- [email protected] [email protected]({ - @javax.jdo.annotations.Query( // <.> - name = "findByName", // <.> - value = "SELECT " // <.> - + "FROM com.mydomain.myapp.Customer " // <.> - + "WHERE name.indexOf(:name) >= 0 ") // <.> -}) -... -public class Customer { - // ... -} ----- -<.> There may be several `@Query` annotations, nested within a `@Queries` annotation, defining queries using JDOQL. -<.> Defines the name of the query. -<.> The definition of the query, using JDOQL syntax. -<.> The fully-qualified class name. -Must correspond to the class on which the annotation is defined (the framework checks this automatically on bootstrapping). -<.> The predicate, expressed using Java syntax. -In this particular query, is an implementation of a LIKE "name%" query. - -and in the corresponding repository, use xref:refguide:applib:index/services/repository/RepositoryService.adoc[RepositoryService]: - -[source,java] ----- -import org.springframework.stereotype.Repository; -import lombok.RequiredArgsConstructor; - -@Repository -@RequiredArgsConstructor(onConstructor_ = {@Inject} ) -public class CustomerRepository { - - private final RepositoryService repositoryService; - - public List<Customer> findByName(String name) { - return repositoryService.allMatches( // <.> - Query.named(Customer.class, "findByName") // <.> - .withParameter("name", name); // <.> - } - -} ----- -<.> The xref:refguide:applib:index/services/repository/RepositoryService.adoc[RepositoryService] is a generic facade over the ORM API. -<.> Specifies the class that is annotated with @Query, along with the `@Query#name` attribute -<.> The `:name` parameter in the query JDOQL string, and its corresponding value - -Whenever a query is submitted, the framework will automatically "flush" any pending changes. -This ensures that the database query runs against an up-to-date table so that all matching instances (with respect to the current transaction) are correctly retrieved. - -When an object is loaded from the database the framework will emit `ObjectLoadedEvent` xref:userguide:ROOT:events.adoc#lifecycle-events[lifecycle event]. - -=== Type-safe queries +// TODO: QueryDSL usage. -DataNucleus also supports type-safe queries; these can be executed using the xref:refguide:persistence:index/jdo/applib/services/JdoSupportService.adoc[JdoSupportService] (JDO-specific) domain service. -See xref:refguide:persistence:index/jdo/applib/services/JdoSupportService.adoc#type-safe-jdoql-queries[JdoSupportService] for further details. [[updating]] == Updating Objects @@ -283,7 +234,7 @@ That said, it is possible to "flush" pending changes: * xref:refguide:applib:index/services/xactn/TransactionService.adoc[TransactionService] acts at the Apache Causeway layer, and flushes any pending object persistence or object deletions -* (if using xref:pjdo:ROOT:about.adoc[JDO/DataNucleus]), the xref:refguide:persistence:index/jdo/applib/services/JdoSupportService.adoc[JdoSupportService] domain service can be used reach down to the underlying JDO API, and perform a flush of pending object updates also. +* (if using xref:pjpa:ROOT:about.adoc[JPA/Eclipselink]), the xref:refguide:persistence:index/jpa/applib/services/JpaSupportService.adoc[JpaSupportService] domain service can be used reach down to the underlying JPA API (`EntityManager`), and perform a flush of pending object updates also. When an object is updated the framework will emit `ObjectUpdatingEvent` and `ObjectUpdatedEvent` xref:userguide:ROOT:events.adoc#lifecycle-events[lifecycle events]. diff --git a/antora/components/userguide/modules/ROOT/partials/meta-annotations/_intro.adoc b/antora/components/userguide/modules/ROOT/partials/meta-annotations/_intro.adoc index 08fffaf8346..a3a724efa60 100644 --- a/antora/components/userguide/modules/ROOT/partials/meta-annotations/_intro.adoc +++ b/antora/components/userguide/modules/ROOT/partials/meta-annotations/_intro.adoc @@ -6,7 +6,7 @@ -Apache Causeway supports the use of meta-annotations, as does Spring Boot and the ORM (xref:pjpa:ROOT:about.adoc[JPA/EclipseLink] from Eclipse 2.7 supporting JPA 2.2, xref:pjdo:ROOT:about.adoc[JDO/DataNucleus] for DN 6.x). +Apache Causeway supports the use of meta-annotations, as does Spring Boot and the ORM (xref:pjpa:ROOT:about.adoc[JPA/EclipseLink] from Eclipse 2.7 supporting JPA 2.2. This allows you to define custom annotations that are more descriptive of your domain model, and meta-annotate your custom annotations with those of Apache Causeway, Spring or the ORM. In your domain model, you can just use the custom annotation. diff --git a/antora/components/userguide/modules/ROOT/partials/properties-collections-actions/actions.adoc b/antora/components/userguide/modules/ROOT/partials/properties-collections-actions/actions.adoc index 19f672bfae6..b7f00dc298a 100644 --- a/antora/components/userguide/modules/ROOT/partials/properties-collections-actions/actions.adoc +++ b/antora/components/userguide/modules/ROOT/partials/properties-collections-actions/actions.adoc @@ -194,7 +194,7 @@ public Order invoice( return this; } -@Column(allowsNull="true") // <.> +@Column(nullable=true) // <.> @Property @Getter @Setter private LocalDate shipBy; @@ -202,7 +202,7 @@ private LocalDate shipBy; <.> Specifies the parameter is optional. <.> Specifies the corresponding property is optional. + -Note that this uses an ORM-specific mechanism to specify the same semantics (in this case, using JDO/DataNucleus' `@Column#allowsNull()`.) +Note that this uses an ORM-specific mechanism to specify the same semantics (in this case, using xref:pjpa:ROOT:about.adoc[JPA/Eclipselink]' `@Column#nullable()`.) See also xref:userguide:ROOT:meta-annotations.adoc#properties-vs-parameters[properties vs parameters]. @@ -214,7 +214,7 @@ For example: [source,java] ---- -import javax.jdo.annotations.Column; +import jakarta.persistence.Column; import lombok.Getter; import lombok.Setter; diff --git a/antora/components/userguide/modules/ROOT/partials/properties-collections-actions/collections.adoc b/antora/components/userguide/modules/ROOT/partials/properties-collections-actions/collections.adoc index dcc15353011..d4eeb2e1a64 100644 --- a/antora/components/userguide/modules/ROOT/partials/properties-collections-actions/collections.adoc +++ b/antora/components/userguide/modules/ROOT/partials/properties-collections-actions/collections.adoc @@ -18,9 +18,9 @@ And collections properties will also have a number of annotations: * Apache Causeway defines its own xref xref:refguide:applib:index/annotation/Collection.adoc[@Collection] annotation for capturing domain semantics. It also provides a xref:refguide:applib:index/annotation/CollectionLayout.adoc[@CollectionLayout] for UI hints (though the information in this annotation may instead be provided by a supplementary xref:userguide:ROOT:ui-layout-and-hints.adoc#object-layout[.layout.xml] file) -* the collections of domain entities are often annotated with ORM annotation(s). -In the case of JDO/DataNucleus annotations this is most notably `javax.jdo.annotations.Persistent`. -Other annotations can be used to specify if the association is bidirectional, and whether to define a link table or not to hold foreign key columns. +* the collections of domain entities will typically be annotated with ORM annotation(s). +In the case of xref:pjpa:ROOT:about.adoc[JPA/Eclipselink], this is most notably `jakarta.persistence.Entity`. +The collection itself will likely have its own ORM-specific annotations, to specify for example if the association is bidirectional, supports cascading deletes, or whether to define a link table or not to hold foreign key columns. * for the collections of view models, then JAXB annotations such as link:https://docs.oracle.com/javase/7/docs/api/javax/xml/bind/annotation/XmlElementWrapper.html[@javax.xml.bind.annotation.XmlElementWrapper] and link:https://docs.oracle.com/javase/7/docs/api/javax/xml/bind/annotation/XmlElement.html[@javax.xml.bind.annotation.XmlElement] will be present @@ -96,8 +96,8 @@ public class ChildObject <.> mandatory; every child must reference its parent <.> cannot be edited directly -Generally speaking you should use `SortedSet` for collection types (as opposed to `Set`, `List` or `Collection`). -JDO/Datanucleus does support the mapping of these other types, but RDBMS are set-oriented, so using this type introduces the least friction. +Generally speaking you should use `Set` for collection types (as opposed to `List` or `Collection`). + == Maps diff --git a/antora/components/userguide/modules/ROOT/partials/view-models/_intro.adoc b/antora/components/userguide/modules/ROOT/partials/view-models/_intro.adoc index aca24de714f..d5569f88778 100644 --- a/antora/components/userguide/modules/ROOT/partials/view-models/_intro.adoc +++ b/antora/components/userguide/modules/ROOT/partials/view-models/_intro.adoc @@ -75,7 +75,7 @@ Because such entities are responsible for their own state management, they can b === Externally-managed entities Sometimes the entities that make up your application are persisted not in the local database but reside in some other system, for example accessible only through a SOAP web service. -Logically that data might still be considered a domain entity and we might want to associate behaviour with it, however it cannot be modelled as a domain entity if only because JDO/DataNucleus doesn't know about the entity nor how to retrieve or update it. +Logically that data might still be considered a domain entity and we might want to associate behaviour with it, however it cannot be modelled as a domain entity since JPA/EclipseLink doesn't know about the entity nor how to retrieve or update it. There are a couple of ways around this: we could either replicate the data somehow from the external system into the Causeway-managed database (in which case it is once again just another domain entity), or we could set up a stub/proxy for the externally managed entity. This proxy would hold the reference to the externally-managed domain entity (eg an external id), as well as the "smarts" to know how to interact with that entity (by making SOAP web service calls etc). diff --git a/api/applib/src/main/java/org/apache/causeway/applib/annotation/Optionality.java b/api/applib/src/main/java/org/apache/causeway/applib/annotation/Optionality.java index d5e37b0886d..4841a5732d8 100644 --- a/api/applib/src/main/java/org/apache/causeway/applib/annotation/Optionality.java +++ b/api/applib/src/main/java/org/apache/causeway/applib/annotation/Optionality.java @@ -18,6 +18,8 @@ */ package org.apache.causeway.applib.annotation; +import jakarta.persistence.Column; + /** * Whether the property or parameter is optional or is required (aka mandatory). * @since 1.x {@index} @@ -40,15 +42,14 @@ public enum Optionality { OPTIONAL, /** - * Indicates that the property is required (even if the JDO <code>javax.jdo.annotations.Column</code> annotation + * Indicates that the property is required (even if the JPA {@link jakarta.persistence.Column} annotation * says otherwise). * * <p> - * When using the JDO/DataNucleus objectstore, it is sometimes necessary to annotate a property as optional - * (using <code>javax.jdo.annotations.Column#allowsNull()</code> set to <code>true</code>), even if the property is + * When using the JPA/EclipseLink objectstore, it is sometimes necessary to annotate a property as optional + * (using {@link Column#nullable()} set to <code>true</code>), even if the property is * logically mandatory. For example, this can occur when the property is in a subtype class that has been - * "rolled up" to the superclass table using <code>javax.jdo.annotations.Inheritance</code>> with the - * <code>javax.jdo.annotations.InheritanceStrategy#SUPERCLASS_TABLE</code> superclass strategy. + * "rolled up" to the superclass table using {@link jakarta.persistence.Inheritance} strategy of {@link jakarta.persistence.InheritanceType#SINGLE_TABLE} * </p> * * <p> diff --git a/api/applib/src/main/java/org/apache/causeway/applib/services/metrics/package-info.java b/api/applib/src/main/java/org/apache/causeway/applib/services/metrics/package-info.java index 35be9587635..5d8a39daab7 100644 --- a/api/applib/src/main/java/org/apache/causeway/applib/services/metrics/package-info.java +++ b/api/applib/src/main/java/org/apache/causeway/applib/services/metrics/package-info.java @@ -19,7 +19,7 @@ /** * The {@link org.apache.causeway.applib.services.metrics.MetricsService} is a request-scoped domain service that hooks - * into the JDO/DataNucleus ObjectStore to provide a number of counters relating to numbers of object loaded, + * into the underlying objectStore to provide a number of counters relating to numbers of object loaded, * dirtied etc. * * diff --git a/api/applib/src/main/java/org/apache/causeway/applib/services/repository/package-info.java b/api/applib/src/main/java/org/apache/causeway/applib/services/repository/package-info.java index 409054541a0..0ee1db7e537 100644 --- a/api/applib/src/main/java/org/apache/causeway/applib/services/repository/package-info.java +++ b/api/applib/src/main/java/org/apache/causeway/applib/services/repository/package-info.java @@ -20,7 +20,7 @@ /** * The {@link org.apache.causeway.applib.services.repository.RepositoryService} collects together methods for creating, * persisting and searching for entities from the underlying persistence store. It acts as an abstraction over the - * JDO/DataNucleus objectstore. + * underlying objectstore. * * */ diff --git a/core/adoc/modules/ROOT/pages/about.adoc b/core/adoc/modules/ROOT/pages/about.adoc index 60264bf643d..28c75694184 100644 --- a/core/adoc/modules/ROOT/pages/about.adoc +++ b/core/adoc/modules/ROOT/pages/about.adoc @@ -48,7 +48,7 @@ filters and servlets into the web request pipeline. As a simplification, the xref:core:metamodel:about.adoc[] module handles domain types (cf `java.lang.Class`) while the xref:core:runtime:about.adoc[] and xref:core:runtimeservices:about.adoc[] modules handle domain object instances (cf `java.lang.Object`). -That said, Spring Boot is responsible for instantiating domain service instances, while the persistence mechanisms (xref:pjpa:ROOT:about.adoc[JPA] and xref:pjdo:ROOT:about.adoc[JDO]) -- which are not part of the `core` modules -- handle the lifecycle of entity instances. +That said, Spring Boot is responsible for instantiating domain service instances, while the persistence mechanism (xref:pjpa:ROOT:about.adoc[JPA/EclipseLink]) -- not part of the `core` modules -- handle the lifecycle of entity instances. There are also two `core` modules not listed above, because their documentation are both part of the end-user docs: diff --git a/core/config/src/main/adoc/modules/config/pages/about.adoc b/core/config/src/main/adoc/modules/config/pages/about.adoc index f8d330ee18a..53ac05af0f8 100644 --- a/core/config/src/main/adoc/modules/config/pages/about.adoc +++ b/core/config/src/main/adoc/modules/config/pages/about.adoc @@ -148,8 +148,6 @@ public class AppManifest { There are several security implementations, precisely one must be selected <.> Enables xref:pjpa:ROOT:about.adoc[JPA/Eclipselink] for persistence. + -Alternatively, `CausewayModuleJdoDataNucleus5.class` would be specified in order to use xref:pjdo:ROOT:about.adoc[JDO/DataNucleus] instead. -+ Optional (though if omitted then only xref:userguide:ROOT:view-models.adoc[view models] may be used, with hand-rolled persistence). <.> Enables the xref:vro:ROOT:about.adoc[REST API (Restful Objects viewer)]. @@ -173,7 +171,7 @@ The remainder of this guide lists the various configuration properties available === CausewayConfiguration domain service Applications can discover the current configuration properties for the framework (under the `causeway` top-level key) by injecting the `CausewayConfiguration` domain service. -There are similar domain services for xref:pjpa:ROOT:about.adoc[JPA/Eclipselink] (`EclipselinkConfiguration`), xref:pjdo:ROOT:about.adoc[JDO/DataNucleus] (`DatanucleusConfiguration`) and RestEasy (`RestEasyConfiguration`), as used by xref:vro:ROOT:about.adoc[REST API (Restful Objects viewer)]. +There are similar domain services for xref:pjpa:ROOT:about.adoc[JPA/Eclipselink] (`EclipselinkConfiguration`) and RestEasy (`RestEasyConfiguration`), as used by xref:vro:ROOT:about.adoc[REST API (Restful Objects viewer)]. Applications can also create their own configuration properties file; the xref:docs:starters:simpleapp.adoc[simpleapp] starter app provides an example. diff --git a/core/metamodel/src/main/adoc/modules/metamodel/pages/events.adoc b/core/metamodel/src/main/adoc/modules/metamodel/pages/events.adoc index 141fcd58c00..86c5e021f57 100644 --- a/core/metamodel/src/main/adoc/modules/metamodel/pages/events.adoc +++ b/core/metamodel/src/main/adoc/modules/metamodel/pages/events.adoc @@ -186,7 +186,7 @@ RS -u-> UED :emits RS -u-> RNG :emits note top of RNG -JDO/Datanucleus +JPA/Eclipselink does not support something like a "Removed Event". diff --git a/extensions/core/commandlog/adoc/modules/commandlog/pages/about.adoc b/extensions/core/commandlog/adoc/modules/commandlog/pages/about.adoc index f78a075e0be..3e49f2b538b 100644 --- a/extensions/core/commandlog/adoc/modules/commandlog/pages/about.adoc +++ b/extensions/core/commandlog/adoc/modules/commandlog/pages/about.adoc @@ -4,7 +4,7 @@ :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 _Command Log_ module provides an implementation of xref:refguide:applib:index/services/publishing/spi/CommandSubscriber.adoc[] SPI that persists xref:refguide:applib:index/services/command/Command.adoc[Command]s using either the xref:pjpa:ROOT:about.adoc[JPA/EclipseLink] or xref:pjdo:ROOT:about.adoc[JDO/DataNucleus] object store. +The _Command Log_ module provides an implementation of xref:refguide:applib:index/services/publishing/spi/CommandSubscriber.adoc[] SPI that persists xref:refguide:applib:index/services/command/Command.adoc[Command]s using the xref:pjpa:ROOT:about.adoc[JPA/EclipseLink] object store. One use case is to combine with the xref:security:audittrail:about.adoc[] extension. The _Command Log_ module logs the action invocations or property edits that the end-user makes, while the _audit trail_ logs the resultant changes in state to domain objects. diff --git a/extensions/core/executionlog/adoc/modules/executionlog/pages/about.adoc b/extensions/core/executionlog/adoc/modules/executionlog/pages/about.adoc index f21ab456d7b..f1ca9c504a5 100644 --- a/extensions/core/executionlog/adoc/modules/executionlog/pages/about.adoc +++ b/extensions/core/executionlog/adoc/modules/executionlog/pages/about.adoc @@ -4,7 +4,7 @@ :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 _Execution Log_ extension provides an implementation of xref:refguide:applib:index/services/publishing/spi/ExecutionSubscriber.adoc[ExecutionSubscriber] that persists xref:refguide:applib:index/services/iactn/Execution.adoc[Execution]s using either the xref:pjpa:ROOT:about.adoc[JPA/EclipseLink] or xref:pjdo:ROOT:about.adoc[JDO/DataNucleus] object store. +The _Execution Log_ extension provides an implementation of xref:refguide:applib:index/services/publishing/spi/ExecutionSubscriber.adoc[ExecutionSubscriber] that persists xref:refguide:applib:index/services/iactn/Execution.adoc[Execution]s using either the xref:pjpa:ROOT:about.adoc[JPA/EclipseLink] object store. One use case is to combine with the xref:security:audittrail:about.adoc[] extension. diff --git a/extensions/core/executionoutbox/adoc/modules/executionoutbox/pages/about.adoc b/extensions/core/executionoutbox/adoc/modules/executionoutbox/pages/about.adoc index 30b5d79acc3..fb23c8b28a9 100644 --- a/extensions/core/executionoutbox/adoc/modules/executionoutbox/pages/about.adoc +++ b/extensions/core/executionoutbox/adoc/modules/executionoutbox/pages/about.adoc @@ -4,7 +4,7 @@ :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 _Execution Outbox_ module provides an implementation of xref:refguide:applib:index/services/publishing/spi/ExecutionSubscriber.adoc[ExecutionSubscriber] that persists xref:refguide:applib:index/services/iactn/Execution.adoc[Execution]s into an "outbox" (using either the xref:pjpa:ROOT:about.adoc[JPA/EclipseLink] or xref:pjdo:ROOT:about.adoc[JDO/DataNucleus] object store). +The _Execution Outbox_ module provides an implementation of xref:refguide:applib:index/services/publishing/spi/ExecutionSubscriber.adoc[ExecutionSubscriber] that persists xref:refguide:applib:index/services/iactn/Execution.adoc[Execution]s into an "outbox" (using the xref:pjpa:ROOT:about.adoc[JPA/EclipseLink] object store). The purpose of the "outbox" is to act as a temporary store of executions to be propogated to other "downstream" systems. The module also provides a REST API, a rest client and DTOs to represent the payloads between these two services. diff --git a/extensions/core/flyway/adoc/modules/flyway/pages/about.adoc b/extensions/core/flyway/adoc/modules/flyway/pages/about.adoc index 8c3d5981796..988dd780719 100644 --- a/extensions/core/flyway/adoc/modules/flyway/pages/about.adoc +++ b/extensions/core/flyway/adoc/modules/flyway/pages/about.adoc @@ -76,23 +76,15 @@ causeway.persistence.schema.auto-create-schemas= // <.> <.> whether Flyway should automatically create schemas ; see link:https://flywaydb.org/documentation/configuration/parameters/createSchemas[flyway.createSchemas] for more info <.> instruct Apache Causeway to _not_ attempt to create schemas -The ORM should also be configured to _not_ automatically create tables: +The ORM should also be configured to _not_ automatically create tables. +If using xref:pjpa:ROOT:about.adoc[JPA/Eclipselink], then: -* if using xref:pjpa:ROOT:about.adoc[JPA/Eclipselink], then: -+ [source,properties] .application.properties ---- eclipselink.ddl-generation=none ---- -* if using xref:pjdo:ROOT:about.adoc[JDO/DataNucleus], then: -+ -[source,properties] -.application.properties ----- -datanucleus.schema.autoCreateAll=false ----- == Managing different variants diff --git a/extensions/security/secman/adoc/modules/secman/pages/about.adoc b/extensions/security/secman/adoc/modules/secman/pages/about.adoc index 0860a846ab6..b62210e20fe 100644 --- a/extensions/security/secman/adoc/modules/secman/pages/about.adoc +++ b/extensions/security/secman/adoc/modules/secman/pages/about.adoc @@ -199,10 +199,9 @@ If a user is not permitted to view/edit an object, then it is only the viewer co You may therefore wish to implement multi-tenancy at a "deeper" level, at the persistence layer). This would prevent the object from being retrieved into memory in the first place, almost certainly more performant and obviously also secure because the viewer cannot render an object that hasn't been retrieved. -One implementation (for multi-tenancy at the persistence layer) is to use capabilities of the ORM. -* xref:pjdo:ROOT:about.adoc[JDO/DataNucleus] supports link:link:https://www.datanucleus.org/products/accessplatform/jdo/persistence.html#multitenancy[multi-tenancy] through the link:https://www.datanucleus.org/products/accessplatform_5_1/jdo/annotations.html#MultiTenant_Class[@MultiTenant] annotation and `datanucleus.tenantId` or `datanucleus.tenantProvider` configuration properties. -* xref:pjpa:ROOT:about.adoc[JPA/Eclipselink] supports 3 different types of multi-tenancy, described in the documentation for the link https://www.eclipse.org/eclipselink/documentation/2.4/jpa/extensions/a_multitenant.htm[@Multitenant] annotation. +One implementation (for multi-tenancy at the persistence layer) is to use capabilities of the ORM. +xref:pjpa:ROOT:about.adoc[JPA/Eclipselink] supports 3 different types of multi-tenancy, described in the documentation for the link https://www.eclipse.org/eclipselink/documentation/2.4/jpa/extensions/a_multitenant.htm[@Multitenant] annotation. Another alternative is to move the responsibility for managing tenancy into the relational database itself. This will obviously vary by vendor. @@ -234,8 +233,8 @@ SecMan consists of a number of Maven submodules: * the API module (`causeway-extensions-secman-api`) defines a set of interfaces for the xref:refguide:extensions:index/secman/applib/user/dom/ApplicationUser.adoc[ApplicationUser], xref:refguide:extensions:index/secman/applib/role/dom/ApplicationRole.adoc[ApplicationRole], xref:refguide:extensions:index/secman/applib/permission/dom/ApplicationPermission.adoc[ApplicationPermission] and xref:refguide:extensions:index/secman/applib/tenancy/dom/ApplicationTenancy.adoc[ApplicationTenancy] entities. -* the two persistence modules (`causeway-extensions-secman-persistence-jpa` and `causeway-extensions-secman-persistence-jdo`) provide concrete implementations of the APIs for JPA and JDO respectively. -As you might expect, they are intended for use with xref:pjpa:ROOT:about.adoc[JPA/Eclipselink] and xref:pjdo:ROOT:about.adoc[JDO/DataNucleus] persistence mechanisms respectively; use one or the other. +* the persistence module `causeway-extensions-secman-persistence-jpa` provides a concrete implementations of the APIs for JPA. +As you might expect, they are intended for use with xref:pjpa:ROOT:about.adoc[JPA/Eclipselink] persistence mechanism. * the Model module (`causeway-extensions-secman-model`) defines view models to represent the feature application features, and also contains business logic as mixins to the API (and therefore contributed to the appropriate concrete entity). diff --git a/mavendeps/adoc/modules/mavendeps/pages/about.adoc b/mavendeps/adoc/modules/mavendeps/pages/about.adoc index 57fe7fd09df..0327b0489f3 100644 --- a/mavendeps/adoc/modules/mavendeps/pages/about.adoc +++ b/mavendeps/adoc/modules/mavendeps/pages/about.adoc @@ -27,9 +27,9 @@ For convenience, it includes: However, it does _not_ include a security implementation, a viewer implementation or a persistence implementation, which you should add as required: -* security, add _one_ of xref:security:spring:about.adoc[Spring], xref:security:keycloak:about.adoc[Keycloak], xref:security:shiro:about.adoc[Shiro] or xref:security:simple:about.adoc[Simple], xref:security:bypass:about.adoc[Bypass] if prototyping +* security, add _one_ of xref:security:spring:about.adoc[Spring], xref:security:keycloak:about.adoc[Keycloak] or xref:security:simple:about.adoc[Simple]; or xref:security:bypass:about.adoc[Bypass] if prototyping -* for persistence, add _one_ of xref:pjpa:ROOT:about.adoc[JPA/Eclipselink] or xref:pjdo:ROOT:about.adoc[JDO/DataNucleus]. +* for persistence, add xref:pjpa:ROOT:about.adoc[JPA/Eclipselink]. * viewer, you will almost certainly want to add xref:vw:ROOT:about.adoc[Wicket] and you might also add xref:vro:ROOT:about.adoc[Restful Objects]. diff --git a/persistence/jpa/applib/src/main/java/org/apache/causeway/persistence/jpa/applib/types/BlobJpaEmbeddable.java b/persistence/jpa/applib/src/main/java/org/apache/causeway/persistence/jpa/applib/types/BlobJpaEmbeddable.java index be4b335e9a3..7a134fcda23 100644 --- a/persistence/jpa/applib/src/main/java/org/apache/causeway/persistence/jpa/applib/types/BlobJpaEmbeddable.java +++ b/persistence/jpa/applib/src/main/java/org/apache/causeway/persistence/jpa/applib/types/BlobJpaEmbeddable.java @@ -54,6 +54,11 @@ * Example usage: * * <pre> + * @AttributeOverrides({ + * @AttributeOverride(name="name", column=@Column(name="attachment_name")), + * @AttributeOverride(name="mimeType",column=@Column(name="attachment_mimeType")), + * @AttributeOverride(name="bytes", column=@Column(name="attachment_bytes")) + * }) * @Embedded * private BlobJpaEmbeddable pdf; * @@ -69,8 +74,8 @@ * </p> * * <p> - * Lastly; note that {@link jakarta.persistence.AttributeOverrides} and {@link jakarta.persistence.AttributeOverride} - * provide a standardised way of fine-tuning the column definitions. + * The {@link jakarta.persistence.AttributeOverrides} and {@link jakarta.persistence.AttributeOverride} attributes + * allow the column definitions to be fine-tuned. * </p> * @since 2.x {@index} */ diff --git a/persistence/jpa/applib/src/main/java/org/apache/causeway/persistence/jpa/applib/types/ClobJpaEmbeddable.java b/persistence/jpa/applib/src/main/java/org/apache/causeway/persistence/jpa/applib/types/ClobJpaEmbeddable.java index cc45cccebac..0a813e0afa0 100644 --- a/persistence/jpa/applib/src/main/java/org/apache/causeway/persistence/jpa/applib/types/ClobJpaEmbeddable.java +++ b/persistence/jpa/applib/src/main/java/org/apache/causeway/persistence/jpa/applib/types/ClobJpaEmbeddable.java @@ -53,6 +53,11 @@ * <p> * Example usage: * <pre> + * @AttributeOverrides({ + * @AttributeOverride(name="name", column=@Column(name="doc_name")), + * @AttributeOverride(name="mimeType",column=@Column(name="doc_mimeType")), + * @AttributeOverride(name="bytes", column=@Column(name="doc_bytes")) + * }) * @Embedded * private ClobJpaEmbeddable xml; * @@ -68,8 +73,8 @@ * </p> * * <p> - * Lastly; note that {@link jakarta.persistence.AttributeOverrides} and {@link jakarta.persistence.AttributeOverride} - * provide a standardised way of fine-tuning the column definitions. + * The {@link jakarta.persistence.AttributeOverrides} and {@link jakarta.persistence.AttributeOverride} annotations + * allow the column definitions to be fine-tuned.. * </p> * * @since 2.x {@index} diff --git a/starters/adoc/modules/starters/pages/helloworld.adoc b/starters/adoc/modules/starters/pages/helloworld.adoc index aa5d5c02c9d..458213ca3e2 100644 --- a/starters/adoc/modules/starters/pages/helloworld.adoc +++ b/starters/adoc/modules/starters/pages/helloworld.adoc @@ -334,38 +334,45 @@ The helloworld starter app doesn't provide any examples of these. ==== AppManifest The "app manifest" is the top-level Spring `@Configuration`. -In the case of the helloworld starter app *for the `jdo` branch* the `AppManifest` looks like this: +In the case of the helloworld starter app the `AppManifest` looks like this: [source,java] .AppManifest.java ---- @Configuration @Import({ + CausewayModuleApplibMixins.class, // <.> + CausewayModuleApplibChangeAndExecutionLoggers.class, // <1> + CausewayModuleCoreRuntimeServices.class, // <.> - CausewayModuleSecurityShiro.class, // <.> - CausewayModuleJdoDataNucleus5.class, // <.> - CausewayModuleViewerRestfulObjectsJaxrsResteasy4.class, // <.> + CausewayModuleSecuritySimple.class, // <.> + CausewayModulePersistenceJpaEclipselink.class, // <.> + CausewayModuleViewerRestfulObjectsViewer.class, // <.> + CausewayModuleViewerGraphqlViewer.class, // <.> + CausewayModuleViewerWicketApplibMixins.class, // <.> CausewayModuleViewerWicketViewer.class, // <.> CausewayModuleTestingH2ConsoleUi.class, // <.> - - HelloWorldModule.class // <.> + HelloWorldModule.class // <.> }) @PropertySource(CausewayPresets.NoTranslations) // <.> public class AppManifest { } ---- - +<.> Provides various optional framework-provided mixins in the UI, such as the `objectIdentifier` and `logicalTypeName` properties <.> Mandatory - specifies the core of the Apache Causeway framework -<.> Enables the Shiro security mechanism. +<.> Enables the Simple security mechanism. There are several security implementations, precisely one must be selected -<.> Enables JDO/DataNucleus for persistence. +<.> Enables xref:pjpa:ROOT:about.adoc[JPA/Eclipselink] for persistence. Optional (though if omitted then only xref:userguide:ROOT:view-models.adoc[view models] may be used, with hand-rolled persistence). -<.> Enables the xref:vro:ROOT:about.adoc[REST API (Restful Objects viewer)] (ie REST API). +<.> Enables the xref:vro:ROOT:about.adoc[REST API (Restful Objects viewer)] + +<.> Enables the xref:gqlv:ROOT:about.adoc[GraphQL API (GraphQL viewer]) +<.> Enables various optional mixins provided by the xref:vw:ROOT:about.adoc[Wicket viewer], for example the `clearHints()` action. <.> Enables the xref:vw:ROOT:about.adoc[Web UI (Wicket viewer)] <.> Enables the H2 Console (menu from the "Prototyping" menu), applicable only if running against h2 in-memory database. @@ -375,15 +382,6 @@ Optional (though if omitted then only xref:userguide:ROOT:view-models.adoc[view <.> Normally configuration properties are picked up from Spring Boot's `application.properties` or `application.yml` files, but additional properties can be overridden directly. This particular one disables the framework's i18n support using the `CausewayPresets` convenience class. -For the `jpa` branch the `AppManifest` is almost identical, just replacing: - -* `CausewayModuleJdoDataNucleus5.class,` - -with: - -* `CausewayModuleJpaEclipseLink.class,` - -This bootstraps the JPA as the ORM instead of JDO. [#helloworldapp] ==== HelloWorldApp diff --git a/testing/integtestsupport/adoc/modules/integtestsupport/pages/about.adoc b/testing/integtestsupport/adoc/modules/integtestsupport/pages/about.adoc index 4199e66b3de..9583e25310c 100644 --- a/testing/integtestsupport/adoc/modules/integtestsupport/pages/about.adoc +++ b/testing/integtestsupport/adoc/modules/integtestsupport/pages/about.adoc @@ -145,7 +145,7 @@ public abstract class ApplicationIntegTestAbstract extends CausewayIntegrationTe @Configuration @Import({ CausewayModuleCoreRuntimeServices.class, - CausewayModuleJdoDataNucleus5.class, + CausewayModuleJpaEclipseLink.class, CausewayModuleSecurityBypass.class, CausewayModuleTestingFixturesApplib.class, ApplicationModule.class //<1> @@ -158,7 +158,7 @@ public abstract class ApplicationIntegTestAbstract extends CausewayIntegrationTe You can see that these are very similar, what's different is the module referenced. -They both also force an in-memory database, with JDO/DataNucleus ORM configured to autocreate the database schema. +They both also force an in-memory database, with the xref:pjpa:ROOT:about.adoc[JPA/Eclipselink] ORM configured to autocreate the database schema. === Faster bootstrapping @@ -629,14 +629,3 @@ Thus, the setup fixture runs the setup for the "inner-most" "leaf-level" modules -== Hints-n-Tips - -[TIP] -.Using JDO/DataNucleus -==== -When running integration tests through the IDE, and if using the JDO/DataNucleus ORM, then make sure the module(s) with entities have been enhanced first. - -If using IntelliJ, we recommend creating a run Maven configuration that runs `datanucleus:enhance`, and then pinning the configuration once run as a tab in the "Debug" window for easy access. - -image::pin-enhance-run-configuration.png[width="400px"] -==== diff --git a/testing/unittestsupport/adoc/modules/unittestsupport/pages/about.adoc b/testing/unittestsupport/adoc/modules/unittestsupport/pages/about.adoc index 72e41533163..d30cf578a1d 100644 --- a/testing/unittestsupport/adoc/modules/unittestsupport/pages/about.adoc +++ b/testing/unittestsupport/adoc/modules/unittestsupport/pages/about.adoc @@ -180,16 +180,10 @@ public class SortedSetsContractTestAll extends SortedSetsContractTestAbstract { ---- -If using an RDBMS for persistence then we strongly recommend that you implement this test, for several reasons: +If using an RDBMS for persistence that supports `SortedSet` then we strongly recommend that you implement this test. -* first, ``Set``s align more closely to the relational model than do ``List``s. -A ``List`` must have an additional index to specify order. +TIP: The xref:refguide:applib:index/util/ObjectContracts.adoc[ObjectContracts] utility class substantially simplifies the task of implementing `Comparable` in your domain classes. -* second, `SortedSet` is preferable to `Set` because then the order is well-defined and predictable (to an end user, to the programmer). -+ -The xref:refguide:applib:index/util/ObjectContracts.adoc[ObjectContracts] utility class substantially simplifies the task of implementing `Comparable` in your domain classes. - -* third, if the relationship is bidirectional then the ORM (JDO/DataNucleus) will automatically maintain the relationship.
