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 2015/04/28 10:07:45 UTC
isis git commit: ISIS-1133: domain services.
Repository: isis
Updated Branches:
refs/heads/ISIS-1133 7dad4d4c0 -> 6718ebf77
ISIS-1133: domain services.
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/6718ebf7
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/6718ebf7
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/6718ebf7
Branch: refs/heads/ISIS-1133
Commit: 6718ebf779299ab0d9948ba4d3ff5265fea220eb
Parents: 7dad4d4
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Tue Apr 28 09:07:40 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Tue Apr 28 09:07:40 2015 +0100
----------------------------------------------------------------------
.../user-guide/_/isisjdosupport-service.adoc | 98 ++++++++++++++
.../_user-guide_reference_domain-services.adoc | 40 +++---
...erence_domain-services_auditing_service.adoc | 3 +-
...ain-services_background-command-service.adoc | 11 ++
...ference_domain-services_command-service.adoc | 11 ++
...rence_domain-services_event-bus-service.adoc | 5 +
...erence_domain-services_isis-jdo-support.adoc | 129 +++++++++++++++++++
...erence_domain-services_isis-support-jdo.adoc | 8 --
adocs/template/document.html.erb | 11 ++
9 files changed, 285 insertions(+), 31 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/6718ebf7/adocs/documentation/src/main/asciidoc/user-guide/_/isisjdosupport-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_/isisjdosupport-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_/isisjdosupport-service.adoc
new file mode 100644
index 0000000..ecdfbe7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_/isisjdosupport-service.adoc
@@ -0,0 +1,98 @@
+Title: Using the IsisJdoSupport service
+
+The `IsisJdoSupport` service provides a number of general purpose methods for working with DataNucleus.
+
+== Executing arbitrary SQL
+
+The `executeSql(...)` method allows arbitrary queries to be submitted:
+
+[source]
+----
+List<Map<String, Object>> executeSql(String sql);
+----
+
+while `executeUpdate(...)` allows arbitrary updates to be performed.
+
+[source]
+----
+Integer executeUpdate(String sql);
+----
+
+A common use of these is to setup fixture data for integration tests.
+
+== Fixture support
+
+The `deleteAll(...)` method is provided pretty much exclusively for tearing down fixture data:
+
+[source]
+----
+void deleteAll(Class<?>... pcClasses);
+----
+
+== Reloading entities
+
+A http://www.datanucleus.org/products/datanucleus/jdo/orm/relationships.html[known limitation] of DataNucleus' implementation of JDO is that persisting a child entity (in a 1:n bidirectional relationship) does not cause the parent's collection to be updated.
+
+The `refresh(T domainObject)` method can be used to reload the parent object (or indeed any object).
+
+For example:
+
+[source]
+----
+public Order newOrder(final Customer customer) {
+ Order order = newTransientInstance(Order.class);
+ order.setCustomer(customer);
+ persist(customer);
+ getContainer().flush(); // to database
+ isisJdoSupport.refresh(customer); // reload parent from database
+ return order;
+}
+----
+
+== Accessing the JDO `PersistenceManager`
+
+Isis currently only supports JDO named queries. If you require more flexibility than this, eg for dynamically constructed queries, then the `IsisJdoSupport` interface can be used to obtain access to the underlying JDO `PersistenceManager`.
+
+For example:
+
+[source]
+----
+public List<Order> findOrders(...) {
+ javax.jdo.PersistenceManager pm = isisJdoSupport.getPersistenceManager();
+
+ // knock yourself out...
+
+ return someListOfOrders;
+}
+----
+
+== Registering the Service
+
+The implementation is `IsisJdoSupportImpl`. It is registered in `isis.properties` as per usual:
+
+[source]
+----
+isis.services = ...\
+ org.apache.isis.objectstore.jdo.datanucleus.service.support.IsisJdoSupportImpl,\
+ ...
+----
+
+In the domain entity or service, add:
+
+[source]
+----
+private IsisJdoSupport isisJdoSupport;
+public void injectIsisJdoSupport(IsisJdoSupport isisJdoSupport) {
+ this.isisJdoSupport = isisJdoSupport;
+}
+----
+
+or simply:
+
+[source]
+----
+@javax.inject.Inject
+private IsisJdoSupport isisJdoSupport;
+----
+
+The service will then be automatically injected as normal.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/6718ebf7/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services.adoc
index 98b9a35..7798c1a 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services.adoc
@@ -6,51 +6,49 @@
IMPORTANT: TODO
-include::_user-guide_reference_domain-services_domain-object-container.adoc[leveloffset=+1]
-include::_user-guide_reference_domain-services_clock-service.adoc[leveloffset=+1]
-include::_user-guide_reference_domain-services_isis-support-jdo.adoc[leveloffset=+1]
+include::_user-guide_reference_domain-services_action-invocation-context.adoc[leveloffset=+1]
-include::_user-guide_reference_domain-services_exception-recognizer.adoc[leveloffset=+1]
+include::_user-guide_reference_domain-services_auditing-service.adoc[leveloffset=+1]
-include::_user-guide_reference_domain-services_wrapper-factory.adoc[leveloffset=+1]
+include::_user-guide_reference_domain-services_background-command-service.adoc[leveloffset=+1]
-include::_user-guide_reference_domain-services_event-bus-service.adoc[leveloffset=+1]
+include::_user-guide_reference_domain-services_background-service.adoc[leveloffset=+1]
+include::_user-guide_reference_domain-services_bookmark-service.adoc[leveloffset=+1]
+include::_user-guide_reference_domain-services_clock-service.adoc[leveloffset=+1]
include::_user-guide_reference_domain-services_command-context.adoc[leveloffset=+1]
-include::_user-guide_reference_domain-services_background-service.adoc[leveloffset=+1]
-
-include::_user-guide_reference_domain-services_auditing-service.adoc[leveloffset=+1]
-
+include::_user-guide_reference_domain-services_command-service.adoc[leveloffset=+1]
+include::_user-guide_reference_domain-services_deep-link-service.adoc[leveloffset=+1]
-include::_user-guide_reference_domain-services_scratch-pad.adoc[leveloffset=+1]
-
-include::_user-guide_reference_domain-services_action-invocation-context.adoc[leveloffset=+1]
+include::_user-guide_reference_domain-services_domain-object-container.adoc[leveloffset=+1]
-include::_user-guide_reference_domain-services_query-results-cache.adoc[leveloffset=+1]
+include::_user-guide_reference_domain-services_email-notification-service.adoc[leveloffset=+1]
include::_user-guide_reference_domain-services_email-service.adoc[leveloffset=+1]
+include::_user-guide_reference_domain-services_event-bus-service.adoc[leveloffset=+1]
+include::_user-guide_reference_domain-services_exception-recognizer.adoc[leveloffset=+1]
-include::_user-guide_reference_domain-services_user-profile-service.adoc[leveloffset=+1]
-
-include::_user-guide_reference_domain-services_user-registration-service.adoc[leveloffset=+1]
+include::_user-guide_reference_domain-services_isis-jdo-support.adoc[leveloffset=+1]
-include::_user-guide_reference_domain-services_email-notification-service.adoc[leveloffset=+1]
+include::_user-guide_reference_domain-services_memento-service.adoc[leveloffset=+1]
+include::_user-guide_reference_domain-services_query-results-cache.adoc[leveloffset=+1]
+include::_user-guide_reference_domain-services_scratch-pad.adoc[leveloffset=+1]
-include::_user-guide_reference_domain-services_bookmark-service.adoc[leveloffset=+1]
+include::_user-guide_reference_domain-services_user-profile-service.adoc[leveloffset=+1]
-include::_user-guide_reference_domain-services_memento-service.adoc[leveloffset=+1]
+include::_user-guide_reference_domain-services_user-registration-service.adoc[leveloffset=+1]
-include::_user-guide_reference_domain-services_deep-link-service.adoc[leveloffset=+1]
+include::_user-guide_reference_domain-services_wrapper-factory.adoc[leveloffset=+1]
include::_user-guide_reference_domain-services_xml-snapshot-service.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/6718ebf7/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_auditing_service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_auditing_service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_auditing_service.adoc
index 0377336..f834649 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_auditing_service.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_auditing_service.adoc
@@ -10,5 +10,4 @@ IMPORTANT: TODO
== Isis Addons Implementation
-
-For 1.7.0+, see the [Isis addon](http://github.com/isisaddons/isis-module-audit) module.
+For 1.7.0+, see the http://github.com/isisaddons/isis-module-audit}[Isis addons' Audit module] (non-ASF).
http://git-wip-us.apache.org/repos/asf/isis/blob/6718ebf7/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_background-command-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_background-command-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_background-command-service.adoc
new file mode 100644
index 0000000..8eaac7f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_background-command-service.adoc
@@ -0,0 +1,11 @@
+= Background Command 1Service
+: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/
+
+IMPORTANT: TODO
+
+
+== Isis Addons Implementation
+
+For 1.7.0+, see the http://github.com/isisaddons/isis-module-command}[Isis addons' Command module] (non-ASF).
http://git-wip-us.apache.org/repos/asf/isis/blob/6718ebf7/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_command-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_command-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_command-service.adoc
new file mode 100644
index 0000000..9ec6079
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_command-service.adoc
@@ -0,0 +1,11 @@
+= Command Service
+: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/
+
+IMPORTANT: TODO
+
+
+== Isis Addons Implementation
+
+For 1.7.0+, see the http://github.com/isisaddons/isis-module-command}[Isis addons' Command module] (non-ASF).
http://git-wip-us.apache.org/repos/asf/isis/blob/6718ebf7/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_event-bus-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_event-bus-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_event-bus-service.adoc
index 12c75db..67cb279 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_event-bus-service.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_event-bus-service.adoc
@@ -6,3 +6,8 @@
IMPORTANT: TODO
+
+## Implementation
+
+The `EventBusServiceJdo` class provides the default implementation and (as of 1.6.0+) is automatically registered using `@DomainService`. No further configuration is necessary.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/6718ebf7/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_isis-jdo-support.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_isis-jdo-support.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_isis-jdo-support.adoc
new file mode 100644
index 0000000..4624841
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_isis-jdo-support.adoc
@@ -0,0 +1,129 @@
+= Isis JDO Support
+: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/
+
+
+The `IsisJdoSupport` service provides a number of general purpose methods for working with the JDO/DataNucleus objectstore.
+
+
+== API
+
+The API provided by `IsisJdoSupport` is:
+
+[source,java]
+----
+public interface IsisJdoSupport {
+ List<Map<String, Object>> executeSql(String sql);
+ Integer executeUpdate(String sql);
+ void deleteAll(Class<?>... pcClasses);
+ <T> T refresh(T domainObject);
+ void ensureLoaded(Collection<?> collectionOfDomainObjects);
+ PersistenceManager getJdoPersistenceManager();
+}
+----
+
+Each of these methods are discussed in more details below.
+
+
+== Executing arbitrary SQL
+
+The `executeSql(...)` method allows arbitrary queries to be submitted:
+
+[source,java]
+----
+List<Map<String, Object>> results = isisJdoSupport.executeSql("select * from custMgmt.customers");
+----
+
+The result set is automatically converted into a list of maps, where the map key is the column name.
+
+
+In a similar manner, the `executeUpdate(...)` allows arbitrary updates to be performed.
+
+[source,java]
+----
+int count = isisJdoSupport.executeUpdate("select count(*) from custMgmt.customers);
+----
+
+The returned value is the number of rows updated.
+
+
+
+== Fixture support
+
+The `deleteAll(...)` method is provided pretty much exclusively for tearing down fixture data:
+
+[source,java]
+----
+deleteAll(Order.class);
+deleteAll(CustomerAddress.class);
+deleteAll(Customer.class);
+----
+
+[NOTE]
+====
+It can occasionally be the case that Isis' internal adapter for the domain object is
+still in memory. JDO/DataNucleus seems to bump up the version of the object prior to its deletion,
+which under normal circumstances would cause Isis to throw a concurrency exception. Therefore
+to prevent this from happening (ie to <i>force</i> the deletion of all instances), concurrency checking
+is temporarily disabled while this method is performed.
+====
+
+
+
+== Reloading entities
+
+A http://www.datanucleus.org/products/datanucleus/jdo/orm/relationships.html[known limitation] of DataNucleus' implementation of JDO is that persisting a child entity (in a 1:n bidirectional relationship) does not cause the parent's collection to be updated.
+
+The `refresh(T domainObject)` method can be used to reload the parent object (or indeed any object).
+
+For example:
+
+[source,java]
+----
+public Order newOrder(final Customer customer) {
+ Order order = newTransientInstance(Order.class);
+ order.setCustomer(customer);
+ persist(customer);
+ getContainer().flush(); // <1>
+ isisJdoSupport.refresh(customer); // <2>
+ return order;
+}
+----
+<1> flush to database
+<2> reload parent from database
+
+
+[NOTE]
+====
+The particular example that led to this method being added was a 1:m bidirectional relationship,
+analogous to `Customer <-> * Order`. Persisting the child `Order` object did not cause
+the parent ``Customer``'s collection of orders to be updated. In fact, JDO does not make any
+such guarantee to do so. Options are therefore either to maintain the collection in code, or to
+refresh the parent.
+
+====
+
+
+
+
+== Using JDO `PersistenceManager` directly
+
+Apache Isis provides a simplified API on top of only supports JDO, and so does not support all of JDO's features. For example, Isis (currently) only supports named queries. If you require more flexibility than this, eg for dynamically constructed queries, then the service provides access to the underlying JDO `PersistenceManager` API:
+
+[source,java]
+----
+public List<Order> findOrders(...) {
+ javax.jdo.PersistenceManager pm = isisJdoSupport.getPersistenceManager();
+
+ // knock yourself out...
+
+ return someListOfOrders;
+}
+----
+
+
+
+== Registering the Service
+
+The `IsisJdoSupportImpl` class provides the default implementation and (as of 1.6.0+) is automatically registered using `@DomainService`. No further configuration is necessary.
http://git-wip-us.apache.org/repos/asf/isis/blob/6718ebf7/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_isis-support-jdo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_isis-support-jdo.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_isis-support-jdo.adoc
deleted file mode 100644
index b4079fe..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_domain-services_isis-support-jdo.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= Isis Support 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 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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/6718ebf7/adocs/template/document.html.erb
----------------------------------------------------------------------
diff --git a/adocs/template/document.html.erb b/adocs/template/document.html.erb
index 6c5d1b3..cb8df42 100644
--- a/adocs/template/document.html.erb
+++ b/adocs/template/document.html.erb
@@ -68,6 +68,11 @@
position: relative;
}
+ *:not(pre) > code {
+ background-color: inherit;
+ border: none;
+ }
+
body div#toc li,
body div#toc2 li {
list-style-type: none;
@@ -133,6 +138,12 @@
.admonitionblock.tip > table td.content {
color: #10B061;
}
+ .admonitionblock.note > table td.content {
+ color: #B509AB;
+ }
+ .admonitionblock.important > table td.content {
+ color: #D5810A;
+ }
.imageblock img {
margin-bottom: 10px;