cleans up ugbtb a little

Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/d9de8873
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/d9de8873
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/d9de8873

Branch: refs/heads/wip
Commit: d9de8873c12db316deb17ec5c1e967dba4c94fd2
Parents: 29d19ff
Author: Dan Haywood <d...@haywood-associates.co.uk>
Authored: Thu Apr 20 06:07:08 2017 +0100
Committer: Dan Haywood <d...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:31 2017 +0100

----------------------------------------------------------------------
 .../_rgfis_spi_ContentNegotiationService.adoc   |  2 +-
 .../guides/ugbtb/_ugbtb_deployment_docker.adoc  |  4 +-
 .../guides/ugbtb/_ugbtb_hints-and-tips.adoc     | 10 ++-
 .../_ugbtb_hints-and-tips_multi-tenancy.adoc    | 13 ++++
 .../_ugbtb_hints-and-tips_persisted-title.adoc  | 82 ++++++++++++++++++++
 ...placing-default-service-implementations.adoc | 64 +++++++++++++++
 ..._hints-and-tips_transactions-and-errors.adoc | 78 +++++++++++++++++++
 .../guides/ugbtb/_ugbtb_other-techniques.adoc   |  5 --
 ...tb_other-techniques_mapping-rdbms-views.adoc |  9 ---
 .../_ugbtb_other-techniques_multi-tenancy.adoc  | 13 ----
 ..._ugbtb_other-techniques_persisted-title.adoc | 82 --------------------
 ...placing-default-service-implementations.adoc | 64 ---------------
 ...ther-techniques_transactions-and-errors.adoc | 78 -------------------
 .../_ugbtb_programming-model_finetuning.adoc    |  2 +-
 .../src/main/asciidoc/guides/ugbtb/ugbtb.adoc   |  1 -
 15 files changed, 250 insertions(+), 257 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/d9de8873/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
index 05c486e..0342d47 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
@@ -18,7 +18,7 @@ Instead you need to create some sort of stable facade over 
your domain entities,
 +
 If the underlying entities change, then care must be taken to ensure that 
structure of the view model nevertheless is unchanged.
 
-* a second option is to solve the problem at the persistence layer, but 
defining a (SQL) view in the database and then 
xref:../ugbtb/ugbtb.adoc#_ugbtb_other-techniques_mapping-rdbms-views[mapping 
this] to a (read-only) entity.  Again this is surfaced by the RO viewer.  +
+* a second option is to solve the problem at the persistence layer, but 
defining a (SQL) view in the database and then 
xref:../ugodn/ugodn.adoc#_ugodn_hints-and-tips_mapping-to-a-view[mapping this] 
to a (read-only) entity.  Again this is surfaced by the RO viewer.  +
 +
 If the underlying tables change (as the result of a change in their 
corresponding domain entities) then once more the view must be refactored so 
that it still presents the same structure.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d9de8873/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_docker.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_docker.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_docker.adoc
index dc84356..ea3b08e 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_docker.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_docker.adoc
@@ -18,7 +18,7 @@ Docker host can be assured.
 ====
 
 
-== Using an `overrides.properties` file
+== Using an `overrides.properties`
 
 In addition to loading the regular configuration properties from `WEB-INF` 
directory (described
 xref:../rgcfg/rgcfg.adoc#_rgcfg_configuration-files[here]), Apache Isis will 
also load the `overrides.properties` file.
@@ -63,7 +63,7 @@ The Docker's `ENTRYPOINT` therefore just needs to parse the 
Docker container's o
 create this file.
 
 
-== Using the `ISIS_OPTS` environment variable
+== Using `$ISIS_OPTS`
 
 The servlet context initializer will search for an environment variable called 
`$ISIS_OPTS`
  and if present will parse the content as a set of key/value pairs.  Each 
key/value pair is separated by "||".

http://git-wip-us.apache.org/repos/asf/isis/blob/d9de8873/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
index c79c0c4..6286cf7 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
@@ -24,9 +24,17 @@ See also hints-n-tips chapters in the:
 
 
 include::_ugbtb_hints-and-tips_are-you-sure.adoc[leveloffset=+1]
+include::_ugbtb_hints-and-tips_replacing-default-service-implementations.adoc[leveloffset=+1]
 include::_ugbtb_hints-and-tips_vetoing-visibility.adoc[leveloffset=+1]
+include::_ugbtb_hints-and-tips_transactions-and-errors.adoc[leveloffset=+1]
+include::_ugbtb_hints-and-tips_persisted-title.adoc[leveloffset=+1]
+
+include::_ugbtb_hints-and-tips_simulating-collections-of-values.adoc[leveloffset=+1]
+
 
include::_ugbtb_hints-and-tips_how-to-handle-void-and-null-results.adoc[leveloffset=+1]
+include::_ugbtb_hints-and-tips_multi-tenancy.adoc[leveloffset=+1]
+
 
include::_ugbtb_hints-and-tips_subclass-properties-in-tables.adoc[leveloffset=+1]
-include::_ugbtb_hints-and-tips_simulating-collections-of-values.adoc[leveloffset=+1]
 include::_ugbtb_hints-and-tips_pushing-changes.adoc[leveloffset=+1]
 
include::_ugbtb_hints-and-tips_how-to-implement-a-spellchecker.adoc[leveloffset=+1]
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d9de8873/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_multi-tenancy.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_multi-tenancy.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_multi-tenancy.adoc
new file mode 100644
index 0000000..3922514
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_multi-tenancy.adoc
@@ -0,0 +1,13 @@
+[[_ugbtb_hints-and-tips_multi-tenancy]]
+= Multi-tenancy
+: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/
+
+
+Of the various Isis Addons, the 
https://github.com/isisaddons/isis-module-security[security module] has the 
most features. One significant feature is the ability to associate users and 
objects with a "tenancy".
+
+
+For more details, see the 
https://github.com/isisaddons/isis-module-security[security module] README.
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d9de8873/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_persisted-title.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_persisted-title.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_persisted-title.adoc
new file mode 100644
index 0000000..d19b068
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_persisted-title.adoc
@@ -0,0 +1,82 @@
+[[_ugbtb_hints-and-tips_persisted-title]]
+= Persisted Title
+: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/
+
+
+
+Normally the title of an object is not persisted to the database, rather it is 
recomputed automatically from underlying properties.  On occasion though you 
might want the title to also be persisted; either to make things easier for the 
DBA, or for an integration scenario, or some other purpose.
+
+We can implement this feature by leveraging the 
xref:../rgcms/rgcms.adoc#_rgcms_methods_lifecycle_jdo-api[JDO lifecycle].  In 
the design we discuss here we make it a responsibility of the entities to 
persist the title as a property, by implementing a `ObjectWithPersistedTitle` 
interface:
+
+[source,java]
+----
+public interface ObjectWithPersistedTitle {
+    @PropertyLayout(hidden = Where.EVERYWHERE)  // <1>
+    String getTitle();
+    void setTitle(final String title);
+}
+----
+<1> we don't want to expose this in the UI because the title is already 
prominently displayed.
+
+We can then define a subscribing domain service that leverage this.
+
+[source,java]
+----
+@DomainService(nature = NatureOfService.DOMAIN)
+public class TitlingService extends AbstractSubscriber {
+    @Subscribe
+    public void on(final ObjectPersistingEvent ev) {
+        handle(ev.getSource());
+    }
+    @Subscribe
+    public void on(final ObjectUpdatingEvent ev) {
+        handle(ev.getSource());
+    }
+    private void handle(final Object persistentInstance) {
+        if(persistentInstance instanceof ObjectWithPersistedTitle) {
+            final ObjectWithPersistedTitle objectWithPersistedTitle =
+                (ObjectWithPersistedTitle) persistentInstance;
+            
objectWithPersistedTitle.setTitle(container.titleOf(objectWithPersistedTitle));
+        }
+    }
+    @Inject
+    private DomainObjectContainer container;
+}
+----
+
+Prior to 1.10.0 (when lifecycle events were introduced), this could also be be 
done by accessing the JDO API directly:
+
+[source,java]
+----
+@RequestScoped
+@DomainService(nature = NatureOfService.DOMAIN)
+public class TitlingService {
+    @PostConstruct
+    public void init() {
+        isisJdoSupport.getJdoPersistenceManager().addInstanceLifecycleListener(
+            new StoreLifecycleListener() {
+                @Override
+                public void preStore(final InstanceLifecycleEvent event) {
+                    final Object persistentInstance = 
event.getPersistentInstance();
+                    if(persistentInstance instanceof ObjectWithPersistedTitle) 
{
+                        final ObjectWithPersistedTitle 
objectWithPersistedTitle =
+                            (ObjectWithPersistedTitle) persistentInstance;
+                        
objectWithPersistedTitle.setTitle(container.titleOf(objectWithPersistedTitle));
+                    }
+                }
+                @Override
+                public void postStore(final InstanceLifecycleEvent event) {
+                }
+            }, null);
+    }
+    @Inject
+    private IsisJdoSupport isisJdoSupport;
+    @Inject
+    private DomainObjectContainer container;
+}
+----
+
+The above is probably the easiest and most straightforward design. One could 
imagine other designs where the persisted title is stored elsewhere.  It could 
even be stored off into an link:http://lucene.apache.org/[Apache Lucene] (or 
similar) database to allow for free-text searches.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d9de8873/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_replacing-default-service-implementations.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_replacing-default-service-implementations.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_replacing-default-service-implementations.adoc
new file mode 100644
index 0000000..dea5096
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_replacing-default-service-implementations.adoc
@@ -0,0 +1,64 @@
+[[_ugbtb_hints-and-tips_replacing-default-service-implementations]]
+= Overriding Default Service Implns
+: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 framework provides default implementations for many of the 
xref:../rgsvc/rgsvc.adoc#[domain services].  This is convenient, but sometimes 
you will want to replace the default implementation with your own service 
implementation.
+
+The trick is to use the 
xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]
 attribute, specifying a low number (typically `"1"`).
+
+For example, suppose you wanted to provide your own implementation of 
xref:../rgsvc/rgsvc.adoc#_rgsvc_api_LocaleProvider[`LocaleProvider`].  Here's 
how:
+
+[source,java]
+----
+@DomainService(
+        nature = NatureOfService.DOMAIN
+)
+@DomainServiceLayout(
+        menuOrder = "1"                             // <1>
+)
+public class MyLocaleProvider implements LocaleProvider {
+    @Override
+    public Locale getLocale() {
+        return ...
+    }
+}
+----
+<1> takes precedence over the default implementation.
+
+
+It's also quite common to want to decorate the existing implementation (ie 
have your own implementation delegate to the default); this is also possible 
and quite easy if using `1.10.0` or later:
+
+[source,java]
+----
+@DomainService(
+        nature = NatureOfService.DOMAIN
+)
+@DomainServiceLayout(
+        menuOrder = "1"                                                        
                     // <1>
+)
+public class MyLocaleProvider implements LocaleProvider {
+    @Override
+    public Locale getLocale() {
+        return getDelegateLocaleProvider().getLocale();                        
                     // <2>
+    }
+    Optional<LocaleProvider> delegateLocaleProvider;                           
                     // <3>
+    private LocaleProvider getDelegateLocaleProvider() {
+        if(delegateLocaleProvider == null) {
+            delegateLocaleProvider = Iterables.tryFind(localeProviders, input 
-> input != this);    // <4>
+        }
+        return delegateLocaleProvider.orNull();
+    }
+    @Inject
+    List<LocaleProvider> localeProviders;                                      
                     // <5>
+}
+----
+<1> takes precedence over the default implementation when injected elsewhere.
+<2> this implementation merely delegates to the default implementation
+<3> lazily populated
+<4> delegate to the first implementation that isn't _this_ implementation 
(else infinite loop!)
+<5> Injects all implementations, including this implemenation
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d9de8873/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_transactions-and-errors.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_transactions-and-errors.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_transactions-and-errors.adoc
new file mode 100644
index 0000000..fa8150f
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_transactions-and-errors.adoc
@@ -0,0 +1,78 @@
+[[_ugbtb_hints-and-tips_transactions-and-errors]]
+= Transactions and Errors
+: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 Apache Isis, every interaction (action invocation or property edit) is 
automatically wrapped in a transaction,
+and any repository query automatically does a flush before hand.
+
+What that means is that there's no need to explicitly start or commit 
transactions in Apache Isis; this will be done
+for you. Indeed, if you do try to manage transactions (eg by reaching into the 
JDO `PersistenceManager` exposed by the
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_IsisJdoSupport[IsisJdoSupport] domain 
service, then you are likely to confuse the
+framework and get a stack trace for your trouble.
+
+However, you can complete a given transaction and start a new one.  This is 
sometimes useful if writing a fixture
+script which is going to perform some sort of bulk migration of data from an 
old system.  For this use case, use the
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_TransactionService[`TransactionService`].
+
+For example:
+
+[source,java]
+----
+public class SomeLongRunningFixtureScript extends FixtureScript
+
+    protected void execute(final ExecutionContext executionContext) {
+        // do some work
+        transactionService.nextTransaction();
+        // do some work
+        transactionService.nextTransaction();
+        // do yet more work
+    }
+
+    @javax.inject.Inject
+    TransactionService transactionService;
+}
+----
+
+You get the idea.
+
+
+== Raise message in the UI
+
+The framework provides the 
xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MessageService[`MessageService`] as a means 
to return an out-of-band
+message to the end-user.  In the xref:../ugvw/ugvw.adoc#[Wicket viewer] these 
are shown as "toast" pop-ups; the
+xref:../ugvro/ugvro.adoc#[Restful Objects viewer] returns an HTTP header.
+
+The `UserService` provides three APIs, for different:
+
+* `informUser()` - an informational message.  In the Wicket viewer these are 
short-lived pop-ups that disappear after a short time.
+* `warnUser()` - a warning.  In the Wicket viewer these do not auto-close; 
they must be acknowledged.
+* `raiseError()` - an error.  In the Wicket viewer these do not auto-close; 
they must be acknowledged.
+
+Each pop-up has a different background colour indicating its severity.
+
+None of these messages/errors has any influence on the transaction; any 
changes to objects will be committed.
+
+
+== Aborting transactions
+
+If you want to abort Apache Isis' transaction, this can be done by throwing an 
exception.  The exception message
+is displayed to the user on the error page (if xref:../ugvw/ugvw.adoc#[Wicket 
viewer]) or a 500 status error code (if the
+xref:../ugvro/ugvro.adoc#[Restful Objects] viewer).
+
+If the exception thrown is because of an unexpected error (eg a 
`NullPointerException` in the domain app itself), then
+the error page will include a stack trace.  If however you want to indicate 
that the exception is in some sense
+"expected", then throw a `RecoverableException` (or any subclass, eg 
`ApplicationException`); the stack trace will then
+be suppressed from the error page.
+
+Another way in which exceptions might be considered "expected" could be as the 
result of attempting to persist an
+object which then violates some type of database constraint.  Even if the 
domain application checks beforehand, it
+could be that another user operating on the object at the same moment of time 
might result in the conflict.
+
+To handle this the 
xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ExceptionRecognizer[`ExceptionRecognizer`] 
SPI can be used.  The
+framework provides a number of implementations out-of-the-box; whenever an 
exception is thrown it is passed to each
+known recognizer implementation to see if it recognizes the exception and can 
return a user-meaningful error message.
+For example, 
`ExceptionRecognizerForSQLIntegrityConstraintViolationUniqueOrIndexException` 
checks if the
+exception inherits from `java.sql.SQLIntegrityConstraintViolationException`, 
and if so, constructs a suitable message.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d9de8873/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques.adoc
index 7cdb1e6..36961ca 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques.adoc
@@ -9,11 +9,6 @@
 This chapter pulls together a number of more advanced techniques that we've 
discovered and developed while building our own Isis applications.
 
 
-include::_ugbtb_other-techniques_mapping-rdbms-views.adoc[leveloffset=+1]
-include::_ugbtb_other-techniques_transactions-and-errors.adoc[leveloffset=+1]
-include::_ugbtb_other-techniques_multi-tenancy.adoc[leveloffset=+1]
-include::_ugbtb_other-techniques_persisted-title.adoc[leveloffset=+1]
-include::_ugbtb_other-techniques_replacing-default-service-implementations.adoc[leveloffset=+1]
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d9de8873/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_mapping-rdbms-views.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_mapping-rdbms-views.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_mapping-rdbms-views.adoc
deleted file mode 100644
index a362148..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_mapping-rdbms-views.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ugbtb_other-techniques_mapping-rdbms-views]]
-= Mapping RDBMS Views
-: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/
-
-
-NOTE: FIXME - as used in link:http://github.com/estatio/estatio[Estatio]
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d9de8873/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_multi-tenancy.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_multi-tenancy.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_multi-tenancy.adoc
deleted file mode 100644
index b6b5ed9..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_multi-tenancy.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-[[_ugbtb_other-techniques_multi-tenancy]]
-= Multi-tenancy
-: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/
-
-
-Of the various Isis Addons, the 
https://github.com/isisaddons/isis-module-security[security module] has the 
most features. One significant feature is the ability to associate users and 
objects with a "tenancy".
-
-
-For more details, see the 
https://github.com/isisaddons/isis-module-security[security module] README.
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d9de8873/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_persisted-title.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_persisted-title.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_persisted-title.adoc
deleted file mode 100644
index d04a082..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_persisted-title.adoc
+++ /dev/null
@@ -1,82 +0,0 @@
-[[_ugbtb_other-techniques_persisted-title]]
-= Persisted Title
-: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/
-
-
-
-Normally the title of an object is not persisted to the database, rather it is 
recomputed automatically from underlying properties.  On occasion though you 
might want the title to also be persisted; either to make things easier for the 
DBA, or for an integration scenario, or some other purpose.
-
-We can implement this feature by leveraging the 
xref:../rgcms/rgcms.adoc#_rgcms_methods_lifecycle_jdo-api[JDO lifecycle].  In 
the design we discuss here we make it a responsibility of the entities to 
persist the title as a property, by implementing a `ObjectWithPersistedTitle` 
interface:
-
-[source,java]
-----
-public interface ObjectWithPersistedTitle {
-    @PropertyLayout(hidden = Where.EVERYWHERE)  // <1>
-    String getTitle();
-    void setTitle(final String title);
-}
-----
-<1> we don't want to expose this in the UI because the title is already 
prominently displayed.
-
-We can then define a subscribing domain service that leverage this.
-
-[source,java]
-----
-@DomainService(nature = NatureOfService.DOMAIN)
-public class TitlingService extends AbstractSubscriber {
-    @Subscribe
-    public void on(final ObjectPersistingEvent ev) {
-        handle(ev.getSource());
-    }
-    @Subscribe
-    public void on(final ObjectUpdatingEvent ev) {
-        handle(ev.getSource());
-    }
-    private void handle(final Object persistentInstance) {
-        if(persistentInstance instanceof ObjectWithPersistedTitle) {
-            final ObjectWithPersistedTitle objectWithPersistedTitle =
-                (ObjectWithPersistedTitle) persistentInstance;
-            
objectWithPersistedTitle.setTitle(container.titleOf(objectWithPersistedTitle));
-        }
-    }
-    @Inject
-    private DomainObjectContainer container;
-}
-----
-
-Prior to 1.10.0 (when lifecycle events were introduced), this could also be be 
done by accessing the JDO API directly:
-
-[source,java]
-----
-@RequestScoped
-@DomainService(nature = NatureOfService.DOMAIN)
-public class TitlingService {
-    @PostConstruct
-    public void init() {
-        isisJdoSupport.getJdoPersistenceManager().addInstanceLifecycleListener(
-            new StoreLifecycleListener() {
-                @Override
-                public void preStore(final InstanceLifecycleEvent event) {
-                    final Object persistentInstance = 
event.getPersistentInstance();
-                    if(persistentInstance instanceof ObjectWithPersistedTitle) 
{
-                        final ObjectWithPersistedTitle 
objectWithPersistedTitle =
-                            (ObjectWithPersistedTitle) persistentInstance;
-                        
objectWithPersistedTitle.setTitle(container.titleOf(objectWithPersistedTitle));
-                    }
-                }
-                @Override
-                public void postStore(final InstanceLifecycleEvent event) {
-                }
-            }, null);
-    }
-    @Inject
-    private IsisJdoSupport isisJdoSupport;
-    @Inject
-    private DomainObjectContainer container;
-}
-----
-
-The above is probably the easiest and most straightforward design. One could 
imagine other designs where the persisted title is stored elsewhere.  It could 
even be stored off into an link:http://lucene.apache.org/[Apache Lucene] (or 
similar) database to allow for free-text searches.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d9de8873/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_replacing-default-service-implementations.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_replacing-default-service-implementations.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_replacing-default-service-implementations.adoc
deleted file mode 100644
index c4abd5d..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_replacing-default-service-implementations.adoc
+++ /dev/null
@@ -1,64 +0,0 @@
-[[_ugbtb_other-techniques_replacing-default-service-implementations]]
-= Overriding Default Service Implns
-: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 framework provides default implementations for many of the 
xref:../rgsvc/rgsvc.adoc#[domain services].  This is convenient, but sometimes 
you will want to replace the default implementation with your own service 
implementation.
-
-The trick is to use the 
xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]
 attribute, specifying a low number (typically `"1"`).
-
-For example, suppose you wanted to provide your own implementation of 
xref:../rgsvc/rgsvc.adoc#_rgsvc_api_LocaleProvider[`LocaleProvider`].  Here's 
how:
-
-[source,java]
-----
-@DomainService(
-        nature = NatureOfService.DOMAIN
-)
-@DomainServiceLayout(
-        menuOrder = "1"                             // <1>
-)
-public class MyLocaleProvider implements LocaleProvider {
-    @Override
-    public Locale getLocale() {
-        return ...
-    }
-}
-----
-<1> takes precedence over the default implementation.
-
-
-It's also quite common to want to decorate the existing implementation (ie 
have your own implementation delegate to the default); this is also possible 
and quite easy if using `1.10.0` or later:
-
-[source,java]
-----
-@DomainService(
-        nature = NatureOfService.DOMAIN
-)
-@DomainServiceLayout(
-        menuOrder = "1"                                                        
                     // <1>
-)
-public class MyLocaleProvider implements LocaleProvider {
-    @Override
-    public Locale getLocale() {
-        return getDelegateLocaleProvider().getLocale();                        
                     // <2>
-    }
-    Optional<LocaleProvider> delegateLocaleProvider;                           
                     // <3>
-    private LocaleProvider getDelegateLocaleProvider() {
-        if(delegateLocaleProvider == null) {
-            delegateLocaleProvider = Iterables.tryFind(localeProviders, input 
-> input != this);    // <4>
-        }
-        return delegateLocaleProvider.orNull();
-    }
-    @Inject
-    List<LocaleProvider> localeProviders;                                      
                     // <5>
-}
-----
-<1> takes precedence over the default implementation when injected elsewhere.
-<2> this implementation merely delegates to the default implementation
-<3> lazily populated
-<4> delegate to the first implementation that isn't _this_ implementation 
(else infinite loop!)
-<5> Injects all implementations, including this implemenation
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d9de8873/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_transactions-and-errors.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_transactions-and-errors.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_transactions-and-errors.adoc
deleted file mode 100644
index 54d068c..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_transactions-and-errors.adoc
+++ /dev/null
@@ -1,78 +0,0 @@
-[[_ugbtb_other-techniques_transactions-and-errors]]
-= Transactions and Errors
-: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 Apache Isis, every interaction (action invocation or property edit) is 
automatically wrapped in a transaction,
-and any repository query automatically does a flush before hand.
-
-What that means is that there's no need to explicitly start or commit 
transactions in Apache Isis; this will be done
-for you. Indeed, if you do try to manage transactions (eg by reaching into the 
JDO `PersistenceManager` exposed by the
-xref:../rgsvc/rgsvc.adoc#_rgsvc_api_IsisJdoSupport[IsisJdoSupport] domain 
service, then you are likely to confuse the
-framework and get a stack trace for your trouble.
-
-However, you can complete a given transaction and start a new one.  This is 
sometimes useful if writing a fixture
-script which is going to perform some sort of bulk migration of data from an 
old system.  For this use case, use the
-xref:../rgsvc/rgsvc.adoc#_rgsvc_api_TransactionService[`TransactionService`].
-
-For example:
-
-[source,java]
-----
-public class SomeLongRunningFixtureScript extends FixtureScript
-
-    protected void execute(final ExecutionContext executionContext) {
-        // do some work
-        transactionService.nextTransaction();
-        // do some work
-        transactionService.nextTransaction();
-        // do yet more work
-    }
-
-    @javax.inject.Inject
-    TransactionService transactionService;
-}
-----
-
-You get the idea.
-
-
-== Raise message/errors to users
-
-The framework provides the 
xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MessageService[`MessageService`] as a means 
to return an out-of-band
-message to the end-user.  In the xref:../ugvw/ugvw.adoc#[Wicket viewer] these 
are shown as "toast" pop-ups; the
-xref:../ugvro/ugvro.adoc#[Restful Objects viewer] returns an HTTP header.
-
-The `UserService` provides three APIs, for different:
-
-* `informUser()` - an informational message.  In the Wicket viewer these are 
short-lived pop-ups that disappear after a short time.
-* `warnUser()` - a warning.  In the Wicket viewer these do not auto-close; 
they must be acknowledged.
-* `raiseError()` - an error.  In the Wicket viewer these do not auto-close; 
they must be acknowledged.
-
-Each pop-up has a different background colour indicating its severity.
-
-None of these messages/errors has any influence on the transaction; any 
changes to objects will be committed.
-
-
-== Aborting transactions
-
-If you want to abort Apache Isis' transaction, this can be done by throwing an 
exception.  The exception message
-is displayed to the user on the error page (if xref:../ugvw/ugvw.adoc#[Wicket 
viewer]) or a 500 status error code (if the
-xref:../ugvro/ugvro.adoc#[Restful Objects] viewer).
-
-If the exception thrown is because of an unexpected error (eg a 
`NullPointerException` in the domain app itself), then
-the error page will include a stack trace.  If however you want to indicate 
that the exception is in some sense
-"expected", then throw a `RecoverableException` (or any subclass, eg 
`ApplicationException`); the stack trace will then
-be suppressed from the error page.
-
-Another way in which exceptions might be considered "expected" could be as the 
result of attempting to persist an
-object which then violates some type of database constraint.  Even if the 
domain application checks beforehand, it
-could be that another user operating on the object at the same moment of time 
might result in the conflict.
-
-To handle this the 
xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ExceptionRecognizer[`ExceptionRecognizer`] 
SPI can be used.  The
-framework provides a number of implementations out-of-the-box; whenever an 
exception is thrown it is passed to each
-known recognizer implementation to see if it recognizes the exception and can 
return a user-meaningful error message.
-For example, 
`ExceptionRecognizerForSQLIntegrityConstraintViolationUniqueOrIndexException` 
checks if the
-exception inherits from `java.sql.SQLIntegrityConstraintViolationException`, 
and if so, constructs a suitable message.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d9de8873/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_finetuning.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_finetuning.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_finetuning.adoc
index 26eb886..cf77b50 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_finetuning.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_finetuning.adoc
@@ -58,7 +58,7 @@ To include/exclude more than one `FacetFactory`, specify as a 
comma-separated li
 
 [TIP]
 ====
-This http://isis.markmail.org/thread/472c3mrvcgnripst[thread] from the users 
mailing list (in Apr 2014) shows a typical customization (to enable 
per-instance security) (though note that 
xref:../ugbtb/ugbtb.adoc#_ugbtb_other-techniques_multi-tenancy[Multi-Tenancy] 
is now a better solution to that particular use-case.
+This http://isis.markmail.org/thread/472c3mrvcgnripst[thread] from the users 
mailing list (in Apr 2014) shows a typical customization (to enable 
per-instance security) (though note that 
xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips_multi-tenancy[Multi-Tenancy] is 
now a better solution to that particular use-case.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d9de8873/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc
index 5f29c15..5e9c576 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc
@@ -46,7 +46,6 @@ The remaining guides are:
 include::_ugbtb_i18n.adoc[leveloffset=+1]
 include::_ugbtb_headless-access.adoc[leveloffset=+1]
 include::_ugbtb_hints-and-tips.adoc[leveloffset=+1]
-include::_ugbtb_other-techniques.adoc[leveloffset=+1]
 include::_ugbtb_programming-model.adoc[leveloffset=+1]
 include::_ugbtb_deployment.adoc[leveloffset=+1]
 include::_ugbtb_web-xml.adoc[leveloffset=+1]

Reply via email to