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 2017/04/20 06:46:40 UTC
[2/5] isis git commit: fixes up references to view models and mixins.
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_contributions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_contributions.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_contributions.adoc
index 107a550..a3126d0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_contributions.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_contributions.adoc
@@ -42,7 +42,7 @@ public class OrderContributions {
<3> Only actions with a single argument can be contributed as associations
More information about contributions can be found xref:../ugfun/ugfun.adoc#_ugfun_how-tos_contributed-members[here]. More information
-about using contributions and mixins to keep your domain application decoupled can be found xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[here] and xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[here].
+about using contributions and mixins to keep your domain application decoupled can be found xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_mixins[here] and xref:../ugfun/ugfun.adoc#_ugfun_programming-model_domain-services_contributions[contributed services]).
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto.adoc
index ad5b8fd..809402b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto.adoc
@@ -47,16 +47,16 @@ public class ToDoItemV1_1 implements Dto { // <5>
protected List<ToDoItem> similarItems = Lists.newArrayList();
}
----
-<1> package name encodes major version; see discussion on xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
+<1> package name encodes major version; see discussion on xref:../ugfun/ugfun.adoc#_ugfun_programming-model_view-models_dto_versioning[versioning]
<2> identifies this class as a view model and defines the root element for JAXB serialization
<3> all properties in the class must be listed; (they can be ignored using `@XmlTransient`)
<4> demonstrating use of UI events for a subscriber to provide the DTO's title; see xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_titleUiEvent[`@DomainObjectLayout#titleUiEvent()`].
-<5> class name encodes (major and) minor version; see discussion on xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
-<6> again, see discussion on xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
-<7> again, see discussion on xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
+<5> class name encodes (major and) minor version; see discussion on xref:../ugfun/ugfun.adoc#_ugfun_programming-model_view-models_dto_versioning[versioning]
+<6> again, see discussion on xref:../ugfun/ugfun.adoc#_ugfun_programming-model_view-models_dto_versioning[versioning]
+<7> again, see discussion on xref:../ugfun/ugfun.adoc#_ugfun_programming-model_view-models_dto_versioning[versioning]
<8> simple scalar properties
-<9> reference to a persistent entity; discussed xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_referencing-domain-entities[below]
-<10> reference to a collection of persistent entities; again discussed xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_referencing-domain-entities[below]
+<9> reference to a persistent entity; discussed xref:../ugfun/ugfun.adoc#_ugfun_programming-model_view-models_jaxb_referencing-domain-entities[here]
+<10> reference to a collection of persistent entities; again discussed xref:../ugfun/ugfun.adoc#_ugfun_programming-model_view-models_jaxb_referencing-domain-entities[here]
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto_versioning.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto_versioning.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto_versioning.adoc
index 2c61f4e..4d1f778 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto_versioning.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto_versioning.adoc
@@ -47,7 +47,7 @@ Although there is no requirement for the namespace URI to correspond to a physic
This usually means including a company domain name within the string.
As noted above, this package will contain multiple DTO classes all with the same namespace; these represent a set of minor versions of the DTO, each subsequent one intended to be backwardly compatible with the previous.
-Since these DTO classes will all be in the same package (as per the xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_using-packages-to-version[advice above]), the class should therefore include the minor version name:
+Since these DTO classes will all be in the same package (as per the advice above), the class should therefore include the minor version name:
[source,java]
----
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_db-schemas.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_db-schemas.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_db-schemas.adoc
new file mode 100644
index 0000000..795c4cf
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_db-schemas.adoc
@@ -0,0 +1,147 @@
+[[_ugodn_db-schemas]]
+= Database Schemas
+: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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+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, all the link:http://www.isisaddons.org[Isis Addons] (non-ASF) modules do this.
+For example:
+
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable( ...
+ schema = "isissecurity",
+ table = "ApplicationUser")
+public class ApplicationUser ... { ... }
+----
+
+results in a `CREATE TABLE` statement of:
+
+[source,sql]
+----
+CREATE TABLE isissecurity."ApplicationUser" (
+ ...
+)
+----
+
+
+while:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable( ...
+ schema = "isisaudit",
+ table="AuditEntry")
+public class AuditEntry ... { ... }
+----
+
+similarly results in:
+
+[source,sql]
+----
+CREATE TABLE isisaudit."AuditEntry" (
+ ...
+)
+----
+
+
+[TIP]
+====
+If for some reason you don't want to use schemas (though we strongly recommend that you do), then note that you can override the `@PersistenceCapable` annotation by providing XML metadata (the `mappings.jdo` file).
+See the section on xref:../ugodn/ugodn.adoc#_ugodn_configuring[configuring DataNucleus Overriding Annotations] for more details.
+====
+
+
+
+
+== Listener to create schema
+
+JDO/DataNucleus does not automatically create these schema objects, but it _does_ provide a listener callback API on the initialization of each class into the JDO metamodel.
+
+[TIP]
+====
+Actually, the above statement isn't quite true.
+In DN 3.2.x (as used by Apache Isis up to v1.8.0) there was no support for schemas.
+As of Apache Isis 1.9.0 and DN 4.0 there is now support.
+But we implemented this feature initially against DN 3.2.x, and it still works, so for now we've decided to leave it in.
+====
+
+Therefore Apache Isis attaches a listener, `CreateSchemaObjectFromClassMetadata`, that checks for the schema's existence, and creates the schema if required.
+
+The guts of its implementation is:
+
+[source,java]
+----
+public class CreateSchemaObjectFromClassMetadata
+ implements MetaDataListener,
+ 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);
+ }
+}
+----
+
+where `MetaDataListener` is the DataNucleus listener API:
+
+[source,java]
+----
+public interface MetaDataListener {
+ void loaded(AbstractClassMetaData cmd);
+}
+----
+
+Although not formal API, the default `CreateSchemaObjectFromClassMetadata` has been designed to be easily overrideable if you need to tweak it to support other RDBMS'.
+Any implementation must implement `org.datanucleus.metadata.MetaDataListener`:
+
+The implementation provided has has been tested for HSQLDB, PostgreSQL and MS SQL Server, and is used automatically unless an alternative implementation is specified (as described in the section below).
+
+
+
+
+
+== Alternative implementation
+
+An alternative implementation can be registered and used through the following configuration property:
+
+[source,ini]
+----
+isis.persistor.datanucleus.classMetadataLoadedListener=\
+ org.apache.isis.objectstore.jdo.datanucleus.CreateSchemaObjectFromClassMetadata
+----
+
+
+Because this pertains to the JDO Objectstore we suggest you put this configuration property in `WEB-INF/persistor_datanucleus.properties`; but putting it in `isis.properties` will also work.
+
+Any implementation must implement `org.datanucleus.metadata.MetaDataListener`.
+In many cases simply subclassing from `CreateSchemaObjectFromClassMetadata` and overriding `buildSqlToCheck(...)` and `buildSqlToExec(...)` should suffice.
+
+If you _do_ need more control, your implementation can also optionally implement `org.apache.isis.objectstore.jdo.datanucleus.DataNucleusPropertiesAware`:
+
+[source,java]
+----
+public interface DataNucleusPropertiesAware {
+ public void setDataNucleusProperties(final Map<String, String> properties);
+}
+----
+
+This provides access to the properties passed through to JDO/DataNucleus.
+
+
+[IMPORTANT]
+====
+If you do extend Apache Isis' `CreateSchemaObjectFromClassMetadata` class for some other database, please https://issues.apache.org/jira/browse/ISIS[contribute back] your improvements.
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_overriding-jdo-annotations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_overriding-jdo-annotations.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_overriding-jdo-annotations.adoc
index 015e8ca..3430709 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_overriding-jdo-annotations.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_overriding-jdo-annotations.adoc
@@ -56,7 +56,7 @@ For example, in writing up the above example we found that writing `schema="
* Forcing the schema to "PUBLIC" (as in the above example) works, but it isn't ideal because the name "PUBLIC" is not vendor-neutral (it works for HSQLDB, but MS SQL Server uses "dbo" as its default).
-* As of 1.9.0 Apache Isis will automatically (attempt) to create the owning schema for a given table if it does not exist. This behaviour can be customized, as described in the section on xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_db-schemas[using modules].
+* As of 1.9.0 Apache Isis will automatically (attempt) to create the owning schema for a given table if it does not exist. This behaviour can be customized, as described in the section on xref:../ugbtb/ugbtb.adoc#_ugodn_db-schemas[using modules].
* You may need to override the entire class metadata rather than individual elements; the mixin mentioned above can help here.
====
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc
index 03887c2..85e3071 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc
@@ -59,5 +59,6 @@ The remaining guides are:
include::_ugodn_configuring.adoc[leveloffset=+1]
include::_ugodn_jdo-mappings.adoc[leveloffset=+1]
+include::_ugodn_db-schemas.adoc[leveloffset=+1]
include::_ugodn_hints-and-tips.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_application-menu.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_application-menu.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_application-menu.adoc
index 3fb3ba5..e377934 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_application-menu.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_application-menu.adoc
@@ -167,5 +167,5 @@ Meanwhile the http://github.com/isisaddons/isis-module-devutils[devutils] module
so forth - on a "Prototyping" top-level menu, on the SECONDARY menu bar.
Currently there is no facility to alter the placement of these services. However, their UI can be suppressed
-using security or using a xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
+using security or using a xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips_vetoing-visibility[vetoing subscriber].
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/pages/powered-by/_powered-by_contactapp.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/pages/powered-by/_powered-by_contactapp.adoc b/adocs/documentation/src/main/asciidoc/pages/powered-by/_powered-by_contactapp.adoc
index a7c76dc..b1cc461 100644
--- a/adocs/documentation/src/main/asciidoc/pages/powered-by/_powered-by_contactapp.adoc
+++ b/adocs/documentation/src/main/asciidoc/pages/powered-by/_powered-by_contactapp.adoc
@@ -34,7 +34,7 @@ image:http://i.imgur.com/qhXhKiu.png[width="32%"]
As our first Apache Isis app making use of mobile technologies it opens the doors for more to follow.
Ionic has proven easy to learn and build apps with, and has a helpful community. Meanwhile we've used
-Apache Isis' support for link://http://isis.apache.org/guides/ugbtb.html#_ugbtb_view-models_jaxb[JAXB view models]
+Apache Isis' support for xref:../../guides/ugfun/ugfun.adoc#_ugfun_programming-model_view-models_jaxb[JAXB view models]
and in particular the http://isis.apache.org/guides/ugvro.html#__ugvro_simplified-representations_apache-isis-profile[simplified REST representations] introduced in v1.12.0. The result is code that is easy to follow and enhance.
We expect that the scope of _Contact App_ will expand and new features added, these will (almost certainly) remain open source.
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/pages/powered-by/_powered-by_gesconsultor-grc.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/pages/powered-by/_powered-by_gesconsultor-grc.adoc b/adocs/documentation/src/main/asciidoc/pages/powered-by/_powered-by_gesconsultor-grc.adoc
index 32f40c8..3ff5647 100644
--- a/adocs/documentation/src/main/asciidoc/pages/powered-by/_powered-by_gesconsultor-grc.adoc
+++ b/adocs/documentation/src/main/asciidoc/pages/powered-by/_powered-by_gesconsultor-grc.adoc
@@ -85,7 +85,7 @@ automatically generated from the underlying domain entities; the GRC viewer is a
xref:../../guides/ugvw/ugvw.adoc#[Wicket viewer]. At the last count more than 400 domain entities, across 6 different
Bounded Contexts, are surfaced in the UI in this this way.
-At the Domain level, we also extensively use the xref:../../guides/ugbtb/ugbtb.adoc#_ugbtb_decoupling_event-bus[domain events]
+At the Domain level, we also extensively use the xref:../../guides/ugfun/ugfun.adoc#_ugfun_building-blocks_events_domain-events[domain events]
functionality available in Apache Isis, along with many of the (non-ASF) link:http://isisaddons.org[Isis Addons] (such
as http://github.com/isisaddons/isis-module-audit[audit], http://github.com/isisaddons/isis-module-security[security]
and the http://github.com/isisaddons/isis-module-excel[excel] modules).
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc b/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc
index b8cb5d5..4dacc27 100644
--- a/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc
+++ b/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc
@@ -60,7 +60,7 @@ Importing the generated app into an xref:guides/dg.adoc#_dg_ide[IDE] +
|link:https://www.youtube.com/watch?v=xVTjtiJM8XM[003^] +
-Walking through the main classes that make up the SimpleApp: `SimpleObject` persistent entity, `HomePageViewModel` xref:guides/ugbtb.adoc#_ugbtb_view-models[view model] and `SimpleObjects` domain service (repository).
+Walking through the main classes that make up the SimpleApp: `SimpleObject` persistent entity, `HomePageViewModel` xref:guides/ugfun/ugfun/_ugfun_building-blocks_types-of-domain-objects_view-models[view model] and `SimpleObjects` domain service (repository).
||||x|||||||
@@ -241,19 +241,19 @@ include::_screencasts-playlists.adoc[]
|link:https://www.youtube.com/watch?v=Wn5215K7_Jg[022^] +
-Shows how to refactor a domain object to move an action implementation out of the domain object itself, and instead implement as a xref:guides/ugbtb.adoc#_ugbtb_decoupling_mixins[mixin] (useful for decoupling).
+Shows how to refactor a domain object to move an action implementation out of the domain object itself, and instead implement as a xref:guides/ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_mixins[mixin] (useful for decoupling).
|x|||||x|||||
|link:https://www.youtube.com/watch?v=m633OEBpWqQ[023^] +
-Shows how to refactor a domain object to move (derived) collections out of the domain object and reimplement as a xref:guides/ugbtb.adoc#_ugbtb_decoupling_mixins[mixin].
+Shows how to refactor a domain object to move (derived) collections out of the domain object and reimplement as a xref:guides/ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_mixins[mixin].
||||||x|||||
|link:https://www.youtube.com/watch?v=-AQJb9GtIqI[024^] +
-Using a domain event xref:guides/rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] to xref:guides/ugbtb.adoc#_ugbtb_decoupling_event-bus[decouple] and abstract business rules ( xref:guides/rgcms.adoc#_rgcms_methods_prefixes_validate[validation]).
+Using a domain event xref:guides/rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] to xref:guides/ugfun/ugfun.adoc#_ugfun_building-blocks_events_domain-events[decouple] and abstract business rules (xref:guides/rgcms.adoc#_rgcms_methods_prefixes_validate[validation]).
||||||x|||||
@@ -517,22 +517,22 @@ include::_screencasts-playlists.adoc[]
|link:https://www.youtube.com/watch?v=puG-pzxRSd0[052^] +
-How to write a xref:guides/ugbtb.adoc#_ugbtb_view-models_jaxb[(JAXB) view model], holding references to two domain objects.
+How to write a xref:guides/ugfun/ugfun.adoc#_ugfun_programming-model_view-models_jaxb[(JAXB) view model], holding references to two domain objects.
|x||||||||x||
|link:https://www.youtube.com/watch?v=tdBkmA2CCZY[053^] +
-Updating the title, icon and layout of a xref:guides/ugbtb.adoc#_ugbtb_view-models_jaxb[(JAXB) view model].
+Updating the title, icon and layout of a xref:guides/ugfun/ugfun.adoc#_ugfun_programming-model_view-models_jaxb[(JAXB) view model].
||||x|||||||
|link:https://www.youtube.com/watch?v=TKF0FB_od00[054^] +
-How to expose information from underlying domain entities referenced by a xref:guides/ugbtb.adoc#_ugbtb_view-models_jaxb[(JAXB) view model] using derived properties
+How to expose information from underlying domain entities referenced by a xref:guides/ugfun/ugfun.adoc#_ugfun_programming-model_view-models_jaxb[(JAXB) view model] using derived properties
||||||||||x|
|link:https://www.youtube.com/watch?v=TMMeVhRNi8A[055^] +
-Adding an action to a xref:guides/ugbtb.adoc#_ugbtb_view-models_jaxb[(JAXB) view model], and adjusting the layout using custom CSS.
+Adding an action to a xref:guides/ugfun/ugfun.adoc#_ugfun_programming-model_view-models_jaxb[(JAXB) view model], and adjusting the layout using custom CSS.
||||x|||||||