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 23b49adaeca35ca1110924ecb10f66d5b9daa3f8 Author: Dan Haywood <[email protected]> AuthorDate: Sun Oct 19 10:33:03 2025 +0100 adds docs for @Table and @Transient --- .../refguide/modules/applib-ant/pages/Column.adoc | 5 +++ .../modules/applib-ant/pages/Embeddable.adoc | 4 ++ .../refguide/modules/applib-ant/pages/Entity.adoc | 4 +- .../refguide/modules/applib-ant/pages/Table.adoc | 25 +++++++++++-- .../modules/applib-ant/pages/Transient.adoc | 43 ++++++++++++++++++++++ .../modules/applib-ant/partials/about/jpa.adoc | 39 ++++++++++---------- 6 files changed, 96 insertions(+), 24 deletions(-) diff --git a/antora/components/refguide/modules/applib-ant/pages/Column.adoc b/antora/components/refguide/modules/applib-ant/pages/Column.adoc index aaf2a9d4761..481142dd2f2 100644 --- a/antora/components/refguide/modules/applib-ant/pages/Column.adoc +++ b/antora/components/refguide/modules/applib-ant/pages/Column.adoc @@ -186,3 +186,8 @@ public void setDoc(final Clob doc) { this.doc = ClobJpaEmbeddable.fromClob(doc); } ---- + + +== See Also + +- link:https://jakarta.ee/specifications/persistence/3.0/apidocs/jakarta.persistence/jakarta/persistence/Column[@Column] (JPA API javadoc) diff --git a/antora/components/refguide/modules/applib-ant/pages/Embeddable.adoc b/antora/components/refguide/modules/applib-ant/pages/Embeddable.adoc index 6c2f0091d38..dec5cbb3e39 100644 --- a/antora/components/refguide/modules/applib-ant/pages/Embeddable.adoc +++ b/antora/components/refguide/modules/applib-ant/pages/Embeddable.adoc @@ -79,3 +79,7 @@ public class Customer { <.> Renders the address using AsciiDoc <.> Allows the state of the embedded object to be updated (or replaced). +== See Also + +- link:https://jakarta.ee/specifications/persistence/3.0/apidocs/jakarta.persistence/jakarta/persistence/Embeddable[@Embeddable] (JPA API javadoc) +- link:https://jakarta.ee/specifications/persistence/3.0/apidocs/jakarta.persistence/jakarta/persistence/Embedded[@Embedded] (JPA API javadoc) diff --git a/antora/components/refguide/modules/applib-ant/pages/Entity.adoc b/antora/components/refguide/modules/applib-ant/pages/Entity.adoc index 36ddf736735..5375ec68c75 100644 --- a/antora/components/refguide/modules/applib-ant/pages/Entity.adoc +++ b/antora/components/refguide/modules/applib-ant/pages/Entity.adoc @@ -38,4 +38,6 @@ Causeway parses the `@Entity` annotation from the Java source code; it does not This means that it the `@Entity` annotation must be used rather than the equivalent XML metadata. ==== -... +== See Also + +- link:https://jakarta.ee/specifications/persistence/3.0/apidocs/jakarta.persistence/jakarta/persistence/Entity[@Entity] (JPA API javadoc) diff --git a/antora/components/refguide/modules/applib-ant/pages/Table.adoc b/antora/components/refguide/modules/applib-ant/pages/Table.adoc index d08b0c5ab99..b935ec6a064 100644 --- a/antora/components/refguide/modules/applib-ant/pages/Table.adoc +++ b/antora/components/refguide/modules/applib-ant/pages/Table.adoc @@ -4,9 +4,28 @@ :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 complete -The JPA `@jakarta.persistence.Table` provides metadata describing how JPA ... +The `@Table` annotation is part of the Jakarta Persistence API (JPA) and is used to specify the primary table for a mapped entity. +By default, the table name is assumed to be the same as the entity name, but `@Table` allows customization of the table name and other table-level details. -Apache Causeway also parses and interprets this annotation in order to ... +Although this annotation is recognised by Causeway, its metadata is currently unused. +== Usage + +Annotate your entity class with `@Table` to define the table mapping: + +[source,java] +---- +import jakarta.persistence.Entity; +import jakarta.persistence.Table; + +@Entity +@Table(name = "customers") +public class Customer { + // ... +} +---- + +== See Also + +- link:https://jakarta.ee/specifications/persistence/3.0/apidocs/jakarta.persistence/jakarta/persistence/Table[@Table] (JPA API javadoc) diff --git a/antora/components/refguide/modules/applib-ant/pages/Transient.adoc b/antora/components/refguide/modules/applib-ant/pages/Transient.adoc new file mode 100644 index 00000000000..79386f6a94a --- /dev/null +++ b/antora/components/refguide/modules/applib-ant/pages/Transient.adoc @@ -0,0 +1,43 @@ +[#jakarta-persistence-Transient] += @Transient (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 [...] + + +The `@Transient` annotation is part of the Jakarta Persistence API (JPA) and is used to indicate that a field or property of an entity should not be persisted to the database. +Fields marked with `@Transient` are ignored by the JPA provider during persistence operations. + +Such fields are useful for temporary, calculated, or helper fields that should not be stored. +In particular, injected services should be annotated with `@Transient` + +Although this annotation is recognised by Causeway, its metadata is currently unused. + +== Usage + +Annotate a field or getter in your entity class with `@Transient` to exclude it from persistence: + +[source,java] +---- +import jakarta.persistence.Entity; +import jakarta.persistence.Transient; + +@Entity +public class Product { + + @Column(length=100) + private String name; + + // ... + + @Transient // <.> + @Inject + private RepositoryService repositoryService; +} +---- +<.> indicates that this injected service should be ignored so far as persistence goes. + + +== See Also + +- link:https://jakarta.ee/specifications/persistence/3.0/apidocs/jakarta.persistence/jakarta/persistence/Transient[@Transient] (JPA API javadoc) + diff --git a/antora/components/refguide/modules/applib-ant/partials/about/jpa.adoc b/antora/components/refguide/modules/applib-ant/partials/about/jpa.adoc index bec4ef2ff53..10810fef007 100644 --- a/antora/components/refguide/modules/applib-ant/partials/about/jpa.adoc +++ b/antora/components/refguide/modules/applib-ant/partials/about/jpa.adoc @@ -15,17 +15,6 @@ The table below lists the xref:pjpa:ROOT:about.adoc[JPA/EclipseLink] annotations |Layer |Applies to -|xref:refguide:applib-ant:Embeddable.adoc[@jakarta. + -persistence. + -Embeddable] -|Indicates that the class is an embeddable (and ideally immutable) value object. -Embeddable objects are stored in-line with a containing entity (which uses the `@Embedded` annotation to do so). - - -|Domain / persistence -|Class - - |xref:refguide:applib-ant:Entity.adoc[@jakarta. + persistence. + Entity] @@ -50,21 +39,31 @@ Causeway also parses the following JPA annotations, but the metadata is currentl |Layer |Applies to - -|`@jakarta. + +|xref:refguide:applib-ant:Embeddable.adoc[@jakarta. + persistence. + -Transient` -|Unused -|Persistence -|Property +Embeddable] +|Indicates that the class is an embeddable object, stored in-line with a containing entity (which uses the `@Embedded` annotation to do so). + + +|Domain / persistence +|Class + -|`@jakarta. + + +|xref:refguide:applib-ant:Embeddable.adoc[@jakarta. + persistence. + -Table` -|Unused +Table] +|Indicates the schema and table to which the entity is mapped. +If not specified, then the default schema is used and the class name is used as the table. |Persistence |Class +|xref:refguide:applib-ant:Embeddable.adoc[@jakarta. + +persistence. + +Transient] +|Indicates that the property should _not_ be persisted as a column in the mapped table. +|Persistence +|Property |===
