svn commit: r943282 - in /websites/staging/isis/trunk: cgi-bin/ content/ content/components/objectstores/jdo/autocreating-schema-objects.html

[bu...@apache.org]

Author: buildbot
Date: Wed Mar 11 07:32:48 2015
New Revision: 943282

Log:
Staging update by buildbot for isis

Modified:
    websites/staging/isis/trunk/cgi-bin/   (props changed)
    websites/staging/isis/trunk/content/   (props changed)
    websites/staging/isis/trunk/content/components/objectstores/jdo/autocreating-schema-objects.html

Propchange: websites/staging/isis/trunk/cgi-bin/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Wed Mar 11 07:32:48 2015
@@ -1 +1 @@
-1665767
+1665768

Propchange: websites/staging/isis/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Wed Mar 11 07:32:48 2015
@@ -1 +1 @@
-1665767
+1665768

Modified: websites/staging/isis/trunk/content/components/objectstores/jdo/autocreating-schema-objects.html
==============================================================================
--- websites/staging/isis/trunk/content/components/objectstores/jdo/autocreating-schema-objects.html (original)
+++ websites/staging/isis/trunk/content/components/objectstores/jdo/autocreating-schema-objects.html Wed Mar 11 07:32:48 2015
@@ -544,31 +544,90 @@
 </h1>
 </div>
 
-<blockquote>
-  <p>this is a stub</p>
-</blockquote>
+<p>We use Java packages as a way to group related domain objects together; the package name forms a namespace.  We can then
+reason about all the classes in that package/namespace as a single unit.  Good examples are the various
+<a href="http://github.com/isisaddons">Isis Addons</a> (not ASF): security, commands, auditing and so on.</p>
+
+<p>In the same way that Java packages act as a namespace for domain objects, it's good practice to map domain entities to
+their own (database) schemas.  As of 1.9.0-SNAPSHOT, all the IsisAddons modules do this, for example:</p>
+
+<pre><code>@javax.jdo.annotations.PersistenceCapable( ...
+        schema = "IsisAddonsSecurity",
+        table = "ApplicationUser")
+public class ApplicationUser ... { ... }
+</code></pre>
+
+<p>and</p>
+
+<pre><code>@javax.jdo.annotations.PersistenceCapable( ...
+        schema = "IsisAddonsAudit",
+        table="AuditEntry")
+public class AuditEntry ... { ... }
+</code></pre>
 
-<pre><code>public static final String CLASS_METADATA_LOADED_LISTENER_KEY = "classMetadataLoadedListener";
-static final String CLASS_METADATA_LOADED_LISTENER_DEFAULT = CreateSchemaFromClassMetadata.class.getName();
+<p>Unfortunately JDO/DataNucleus does not automatically create these schema objects, but it <em>does</em> provide a listener
+on the initialization of each class into the JDO metamodel.  Apache Isis attaches a listener,
+<code>CreateSchemaObjectFromClassMetadata</code>, that checks for the schema's existence, and creates the schema if required.
+The guts of its implementation is:</p>
+
+<pre><code>package org.apache.isis.objectstore.jdo.datanucleus;
+
+public class CreateSchemaObjectFromClassMetadata
+        implements MetaDataListener,
+                   PersistenceManagerFactoryAware,
+                   DataNucleusPropertiesAware {
+
+    @Override
+    public void loaded(final AbstractClassMetaData cmd) { ... }
+
+    protected String buildSqlToCheck(final AbstractClassMetaData cmd) {
+        final String schemaName = schemaNameFor(cmd);
+        return String.format("SELECT count(*) FROM INFORMATION_SCHEMA.SCHEMATA where SCHEMA_NAME = '%s'", schemaName);
+    }
+
+    protected String buildSqlToExec(final AbstractClassMetaData cmd) {
+        final String schemaName = schemaNameFor(cmd);
+        return String.format("CREATE SCHEMA \"%s\"", schemaName);
+    }
+}
 </code></pre>
 
-<p>Implement</p>
+<p>This implementation works for HSQLDB, PostgreSQL and MS SQL Server, but has not been tested on other RDBMS vendors.
+An alternative implementation can be registered and used through the following key in <code>WEB-INF/persistor_datanucleus.properties</code> (you could also put it in <code>isis.properties</code> if you prefer):</p>
+
+<pre><code>#
+# hook to perform additional initialization when JDO class metadata is loaded
+# default implementation will attempt to run 'create schema' for the specified schema.
+#
+#isis.persistor.datanucleus.classMetadataLoadedListener=org.apache.isis.objectstore.jdo.datanucleus.CreateSchemaFromClassMetadata
+</code></pre>
 
-<p>org.datanucleus.metadata.MetaDataListener:</p>
+<p>Although not formal API, the default <code>CreateSchemaFromClassMetadata</code> has been designed to be easily overrideable if you
+need to tweak it to support other RDBMS'.  Any implementation must implement <code>org.datanucleus.metadata.MetaDataListener</code>:</p>
 
 <pre><code>public interface MetaDataListener {
     void loaded(AbstractClassMetaData cmd);
 }
 </code></pre>
 
-<p>Optionally implement <code>org.apache.isis.objectstore.jdo.datanucleus.PersistenceManagerFactoryAware</code></p>
+<p>and can optionally implement <code>org.apache.isis.objectstore.jdo.datanucleus.PersistenceManagerFactoryAware</code>:</p>
+
+<pre><code>public interface PersistenceManagerFactoryAware {
+    public void setPersistenceManagerFactory(final PersistenceManagerFactory persistenceManagerFactory);
+}
+</code></pre>
 
-<p>public interface PersistenceManagerFactoryAware {</p>
+<p>and also <code>org.apache.isis.objectstore.jdo.datanucleus.DataNucleusPropertiesAware</code>:</p>
 
-<pre><code>public void setPersistenceManagerFactory(final PersistenceManagerFactory persistenceManagerFactory);</div>
+<pre><code>public interface DataNucleusPropertiesAware {
+    public void setDataNucleusProperties(final Map&lt;String, String&gt; properties);
+}
 </code></pre>
 
-<p>Default implementation is:</p>
+<p>which provides access to the properties passed through to JDO/DataNucleus.  Often though you should find simply
+overriding <code>buildSqlToCheck(...)</code> and <code>buildSqlToExec(...)</code> should suffice.</p>
+
+<p>And, if you do extend the class, please <a href="https://issues.apache.org/jira/browse/ISIS">contribute back</a> your improvements.</p>