You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2013/08/15 19:01:11 UTC
svn commit: r1514375 - in /isis/site/trunk/content: ./
components/objectstores/jdo/
Author: danhaywood
Date: Thu Aug 15 17:01:11 2013
New Revision: 1514375
URL: http://svn.apache.org/r1514375
Log:
more JDO mapping docs
Added:
isis/site/trunk/content/components/objectstores/jdo/lazy-loading.md
isis/site/trunk/content/components/objectstores/jdo/mapping-blobs.md
isis/site/trunk/content/components/objectstores/jdo/mapping-joda-dates.md
- copied, changed from r1485623, isis/site/trunk/content/components/objectstores/jdo/dates-blobs-lazy-loading.md
isis/site/trunk/content/components/objectstores/jdo/mapping-mandatory-and-optional-properties.md
Removed:
isis/site/trunk/content/components/objectstores/jdo/dates-blobs-lazy-loading.md
Modified:
isis/site/trunk/content/components/objectstores/jdo/about.md
isis/site/trunk/content/documentation.md
Modified: isis/site/trunk/content/components/objectstores/jdo/about.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/components/objectstores/jdo/about.md?rev=1514375&r1=1514374&r2=1514375&view=diff
==============================================================================
--- isis/site/trunk/content/components/objectstores/jdo/about.md (original)
+++ isis/site/trunk/content/components/objectstores/jdo/about.md Thu Aug 15 17:01:11 2013
@@ -2,18 +2,25 @@ Title: DataNucleus (JDO) Object Store
The DataNucleus objectstore enables the persistence of domain objects using the JDO API. [DataNucleues](http://datanucleus.org) is the reference implementation for JDO.
-### Hints and tips:
+### Isis Hints and tips:
- [DataNucleus and Eclipse](datanucleus-and-eclipse.html)
- [DataNucleus and Maven](datanucleus-and-maven.html)
- [`persistence.xml` file](persistence_xml.html)
-- [Dates, Blobs and Lazy Loading](dates-blobs-lazy-loading.html)
- [Managed 1:m bidirectional relationships](managed-1-to-m-relationships.html)
- [Using a JNDI Datasource](using-jndi-datasource.html)
- [Using the `IsisJdoSupport` service](isisjdosupport-service.html)
- [Enabling Logging](enabling-logging.html)
- [Deploying on the Google App Engine](deploying-on-the-google-app-engine.html)
+##### JDO Mapping Hints
+- [Mapping Mandatory and Optional Properties](mapping-mandatory-and-optional-properties.html)
+- [Mapping JODA Dates](mapping-joda-dates.html)
+- [Mapping Blobs](components/objectstores/jdo/mapping-blobs.html)
+- [Lazy Loading](lazy-loading.html)
+- [Managed 1:m bidirectional relationships](managed-1-to-m-relationships.html)
+
+
### Applib Service Implementations:
- [Eagerly Registering Entities](eagerly-registering-entities.html)
Added: isis/site/trunk/content/components/objectstores/jdo/lazy-loading.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/components/objectstores/jdo/lazy-loading.md?rev=1514375&view=auto
==============================================================================
--- isis/site/trunk/content/components/objectstores/jdo/lazy-loading.md (added)
+++ isis/site/trunk/content/components/objectstores/jdo/lazy-loading.md Thu Aug 15 17:01:11 2013
@@ -0,0 +1,26 @@
+Title: Lazy Loading
+
+By default, collections all rendered lazily and are thus also loaded lazily from the database.
+
+However, even in the case of collections that have annotated with `@Render(Type.EAGERLY)`, these should probably still be lazily loaded. Otherwise, there will always be an unnecessary cost when rendering the object in a table.
+
+For example, in the `ToDoItem` (in the [wicket/restful/jdo archetype](../../../getting-started/quickstart-archetype.html)) the `dependencies` collection is as follows:
+
+<pre>
+ @javax.jdo.annotations.Persistent(table="TODO_DEPENDENCIES")
+ @javax.jdo.annotations.Join(column="DEPENDING_TODO_ID")
+ @javax.jdo.annotations.Element(column="DEPENDENT_TODO_ID")
+ private SortedSet<ToDoItem> dependencies = new TreeSet<ToDoItem>();
+
+ @Disabled
+ @MemberOrder(sequence = "1")
+ @Render(Type.EAGERLY)
+ public SortedSet<ToDoItem> getDependencies() {
+ return dependencies;
+ }
+ public void setDependencies(final SortedSet<ToDoItem> dependencies) {
+ this.dependencies = dependencies;
+ }
+</pre>
+
+Even though `@Render(Type.EAGERLY)`, the `@javax.jdo.annotations.Persistent` annotation leaves the `defaultFetchGroup` as its default, which for collections is "false".
Added: isis/site/trunk/content/components/objectstores/jdo/mapping-blobs.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/components/objectstores/jdo/mapping-blobs.md?rev=1514375&view=auto
==============================================================================
--- isis/site/trunk/content/components/objectstores/jdo/mapping-blobs.md (added)
+++ isis/site/trunk/content/components/objectstores/jdo/mapping-blobs.md Thu Aug 15 17:01:11 2013
@@ -0,0 +1,26 @@
+Title: Mapping Blobs
+
+
+Isis configures JDO/DataNucleus so that the properties of type `org.apache.isis.applib.value.Blob` and `org.apache.isis.applib.value.Clob` can also be persisted.
+
+As for [Joda dates](mapping-joda-dates.html), this requires the `@javax.jdo.annotations.Persistent` annotation. However, whereas for dates one would always expect this value to be retrieved eagerly, for blobs and clobs it is not so clear cut.
+
+For example, in the `ToDoItem` (in the [wicket/restful/jdo archetype](../../../getting-started/quickstart-archetype.html)) the `attachment` property is as follows:
+
+<pre>
+ @javax.jdo.annotations.Persistent(defaultFetchGroup="false")
+ private Blob attachment;
+
+ @Optional
+ @MemberOrder(name="Detail", sequence = "7")
+ @Hidden(where=Where.STANDALONE_TABLES)
+ public Blob getAttachment() {
+ return attachment;
+ }
+ public void setAttachment(final Blob attachment) {
+ this.attachment = attachment;
+ }
+</pre>
+
+Here we can see that the property is hidden in standalone tables, and so there's no need to retrieve it eagerly. The converse of this the object is rendered by itself, then the attachment property will be retrieved as a one separate query; this seems like a reasonable compromise.
+
Copied: isis/site/trunk/content/components/objectstores/jdo/mapping-joda-dates.md (from r1485623, isis/site/trunk/content/components/objectstores/jdo/dates-blobs-lazy-loading.md)
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/components/objectstores/jdo/mapping-joda-dates.md?p2=isis/site/trunk/content/components/objectstores/jdo/mapping-joda-dates.md&p1=isis/site/trunk/content/components/objectstores/jdo/dates-blobs-lazy-loading.md&r1=1485623&r2=1514375&rev=1514375&view=diff
==============================================================================
--- isis/site/trunk/content/components/objectstores/jdo/dates-blobs-lazy-loading.md (original)
+++ isis/site/trunk/content/components/objectstores/jdo/mapping-joda-dates.md Thu Aug 15 17:01:11 2013
@@ -1,6 +1,4 @@
-Title: Dates, Blobs and Lazy Loading
-
-### Joda Dates
+Title: Joda Dates
Isis' JDO objectstore bundles DataNucleus' [built-in support](http://www.datanucleus.org/plugins/store.types.jodatime.html) for Joda `LocalDate` and `LocalDateTime` datatypes, meaning that entity properties of these types will be persisted as appropriate data types in the database tables.
@@ -11,7 +9,7 @@ Moreover, these datatypes are *not* in t
For example, the `ToDoItem` (in the [wicket/restful/jdo archetype](../../../getting-started/quickstart-archetype.html)) defines the `dueBy` property as follows:
<pre>
- @javax.jdo.annotations.Persistent(defaultFetchGroup="true")
+ @javax.jdo.annotations.Persistent
private LocalDate dueBy;
@MemberOrder(name="Detail", sequence = "3")
@@ -24,58 +22,4 @@ For example, the `ToDoItem` (in the [wic
}
</pre>
-{note
-In DataNucleus 3.2, it will no longer be necessary to specify the "default fetch group" because this flag is [switched on](http://datanucleus.svn.sourceforge.net/viewvc/datanucleus/platform/store.types.jodatime/trunk/plugin.xml?revision=16602&content-type=text%2Fplain). See [ISIS-303](https://issues.apache.org/jira/browse/ISIS-303) as to when this is incorporated into Isis JDO Objectstore.
-}
-
-### Blobs and Clobs
-
-In addition to the support for Joda types, Isis also configures JDO/DataNucleus so that the properties of type `org.apache.isis.applib.value.Blob` and `org.apache.isis.applib.value.Clob` can also be persisted.
-
-Again, this requires the `@javax.jdo.annotations.Persistent` annotation. However, whereas for dates one would always expect this value to be retrieved eagerly, for blobs and clobs it is not so clear cut.
-
-For example, in the `ToDoItem` (in the [wicket/restful/jdo archetype](../../../getting-started/quickstart-archetype.html)) the `attachment` property is as follows:
-
-<pre>
- @javax.jdo.annotations.Persistent(defaultFetchGroup="false")
- private Blob attachment;
-
- @Optional
- @MemberOrder(name="Detail", sequence = "7")
- @Hidden(where=Where.STANDALONE_TABLES)
- public Blob getAttachment() {
- return attachment;
- }
- public void setAttachment(final Blob attachment) {
- this.attachment = attachment;
- }
-</pre>
-
-Here we can see that the property is hidden in standalone tables, and so there's no need to retrieve it eagerly. The converse of this the object is rendered by itself, then the attachment property will be retrieved as a one separate query; this seems like a reasonable compromise.
-
-### Lazy Loading
-
-Lazy loading is a much more important consideration for collections. By default, these are all rendered lazily and are thus also loaded lazily from the database.
-
-However, even in the case of collections that have annotated with `@Render(Type.EAGERLY)`, these should probably still be lazily loaded. Otherwise, there will always be an unnecessary cost when rendering the object in a table.
-
-For example, in the `ToDoItem` (in the [wicket/restful/jdo archetype](../../../getting-started/quickstart-archetype.html)) the `dependencies` collection is as follows:
-
-<pre>
- @javax.jdo.annotations.Persistent(table="TODO_DEPENDENCIES")
- @javax.jdo.annotations.Join(column="DEPENDING_TODO_ID")
- @javax.jdo.annotations.Element(column="DEPENDENT_TODO_ID")
- private SortedSet<ToDoItem> dependencies = new TreeSet<ToDoItem>();
-
- @Disabled
- @MemberOrder(sequence = "1")
- @Render(Type.EAGERLY)
- public SortedSet<ToDoItem> getDependencies() {
- return dependencies;
- }
- public void setDependencies(final SortedSet<ToDoItem> dependencies) {
- this.dependencies = dependencies;
- }
-</pre>
-Even though `@Render(Type.EAGERLY)`, the `@javax.jdo.annotations.Persistent` annotation leaves the `defaultFetchGroup` as its default, which for collections is "false".
Added: isis/site/trunk/content/components/objectstores/jdo/mapping-mandatory-and-optional-properties.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/components/objectstores/jdo/mapping-mandatory-and-optional-properties.md?rev=1514375&view=auto
==============================================================================
--- isis/site/trunk/content/components/objectstores/jdo/mapping-mandatory-and-optional-properties.md (added)
+++ isis/site/trunk/content/components/objectstores/jdo/mapping-mandatory-and-optional-properties.md Thu Aug 15 17:01:11 2013
@@ -0,0 +1,77 @@
+Title: Mapping Optional Properties
+
+### Isis vs JDO Annotations
+
+In the standard Isis programming model, optional properties are specified with the `@Optional` annotation. However, this annotation is not recognized by the JDO Objectstore, optionality is specified using the `javax.jdo.annotations.Column(allowNulls="true")` annotation.
+
+Since these are different annotations, incompatibilities can arise. A property might be annotated as optional to Isis, but mandatory to JDO; or vice versa.
+
+The two frameworks also have different defaults if their respective annotations are missing; this might also lead to incompatibilities. For Isis, if the `@Optional` annotation is missing then the property is assumed to be mandatory. For JDO, if the `@Column` annotation is missing then the property is assumed to mandatory if a primitive type, but optional if a reference type (eg `String`, `BigDecimal` etc).
+
+Isis will flag any incompatibilities between the two frameworks, and refuse to boot (fail fast). To make such conflicts easier to avoid, though, Isis also understands the `@Column` annotation instead of the `@Optional` annotation.
+
+For example, rather than:
+
+ @javax.jdo.annotations.Column(allowNulls="true")
+ private LocalDate date;
+
+ @Optional
+ public LocalDate getDate() { }
+ public void setDate(LocalDate d) { }
+
+you can write:
+
+ private LocalDate date;
+
+ @javax.jdo.annotations.Column(allowNulls="true")
+ public LocalDate getDate() { }
+ public void setDate(LocalDate d) { }
+
+Do note though that the `@Column` annotation must be applied to the getter method, not to the field.
+
+### Handling Mandatory Properties in Subtypes
+
+If you have a hierarchy of classes then you need to decide which inheritance strategy to use.
+
+* "table per hierarchy", or "rollup" (`InheritanceStrategy.SUPERCLASS_TABLE`)
+ * whereby a single table corresponds to the superclass, and also holds the properties of the subtype (or subtypes) being rolled up
+* "table per class" (`InheritanceStrategy.NEW_TABLE`)
+ * whereby is a table for both superclass and subclass, in 1:1 correspondence
+* "rolldown" (`InheritanceStrategy.SUBCLASS_TABLE`)
+ * whereby a single table holds the properties of the subtype, and also holds the properties of its supertype
+
+In the first "rollup" case, we can have a situation where - logically speaking - the property is mandatory in the subtype - but it must be mapped as nullable in the database because it is n/a for any other subtypes that are rolled up.
+
+In this situation we must tell JDO that the column is optional, but to Isis we want to enforce it being mandatory. This can be done using the `@Mandatory` annotation.
+
+For example:
+
+
+ @javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPER_TABLE)
+ public class SomeSubtype extends SomeSuperType {
+
+ private LocalDate date;
+
+ @javax.jdo.annotations.Column(allowNulls="true")
+ @Mandatory
+ public LocalDate getDate() { }
+ public void setDate(LocalDate d) { }
+
+ }
+
+
+An alternative way to achieve this is to leave the JDO annotation on the field (where it is invisible to Isis), and rely on Isis' default, eg:
+
+ @javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPER_TABLE)
+ public class SomeSubtype extends SomeSuperType {
+
+ @javax.jdo.annotations.Column(allowNulls="true")
+ private LocalDate date;
+
+ // mandatory in Isis by default
+ public LocalDate getDate() { }
+ public void setDate(LocalDate d) { }
+
+ }
+
+We recommend the former mapping, though, using `@Mandatory`.
\ No newline at end of file
Modified: isis/site/trunk/content/documentation.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/documentation.md?rev=1514375&r1=1514374&r2=1514375&view=diff
==============================================================================
--- isis/site/trunk/content/documentation.md (original)
+++ isis/site/trunk/content/documentation.md Thu Aug 15 17:01:11 2013
@@ -184,7 +184,7 @@ Note: this viewer is third-party open so
{row-even
-{span-one-third
+{span-one-thirds
### DataNucleus (JDO) [1.1.0](components/objectstores/jdo/release-notes/about.html)
@@ -192,13 +192,19 @@ Note: this viewer is third-party open so
- [DataNucleus and Eclipse](components/objectstores/jdo/datanucleus-and-eclipse.html)
- [DataNucleus and Maven](components/objectstores/jdo/datanucleus-and-maven.html)
- [`persistence.xml` file](components/objectstores/jdo/persistence_xml.html)
-- [Dates, Blobs and Lazy Loading](components/objectstores/jdo/dates-blobs-lazy-loading.html)
-- [Managed 1:m bidirectional relationships](components/objectstores/jdo/managed-1-to-m-relationships.html)
-- [Using a JNDI Datasource](components/objectstores/jdo/using-jndi-datasource.html)
-- [Using the `IsisJdoSupport` service](components/objectstores/jdo/isisjdosupport-service.html)
+- [Using a JNDI Datasource](components/objectstores/jdo/using-jndi-datasource.html)
+- [Using the `IsisJdoSupport` service](components/objectstores/jdo/isisjdosupport-service.html)
- [Enabling Logging](components/objectstores/jdo/enabling-logging.html)
- [Deploying on the Google App Engine](components/objectstores/jdo/deploying-on-the-google-app-engine.html)
+##### JDO Mapping Hints
+- [Mapping Mandatory and Optional Properties](components/objectstores/jdo/mapping-mandatory-and-optional-properties.html)
+- [Mapping JODA Dates](components/objectstores/jdo/mapping-joda-dates.html)
+- [Mapping Blobs](components/objectstores/jdo/mapping-blobs.html)
+- [Lazy Loading](components/objectstores/jdo/lazy-loading.html)
+- [Managed 1:m bidirectional relationships](components/objectstores/jdo/managed-1-to-m-relationships.html)
+
+
}
{span-one-third