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/06/16 07:41:55 UTC
[07/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-RepresentationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-RepresentationService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-RepresentationService.adoc
deleted file mode 100644
index 28f4852..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-RepresentationService.adoc
+++ /dev/null
@@ -1,106 +0,0 @@
-[[_ug_reference-services-spi_manpage-RepresentationService]]
-= `RepresentationService`
-: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 `RepresentationService` is the main plug-in point for the xref:_ug_restfulobjects-viewer[RestfulObjects viewer] to generate representations.
-
-The default implementation generates representations according to the link:http://restfulobjects.org[Restful Objects spec] v1.0. However, it also delegates to the xref:_ug_reference-services-spi_manpage-ContentNegotiationService[`ContentNegotiationService`] which provides a mechanism for altering representations according to the HTTP `Accept` header.
-
-The principal motivation is to allow more flexible representations to be generated for REST clients that (perhaps through their use of a certain Javascript library, say) expect, or at least works best with, a certain style of representation.
-
-In all there are three domain services that can influence the representations generated: this service, xref:_ug_reference-services-spi_manpage-ContentNegotiationService[`ContentNegotiationService`]and the xref:_ug_reference-services-spi_manpage-ContentMappingService[`ContentMappingService`]. The diagram below shows how these collaborate:
-
-image::{_imagesdir}reference-services-spi/RepresentationService/service-collaborations.png[width="700px",link="{_imagesdir}reference-services-spi/RepresentationService/service-collaborations.png"]
-
-The `RepresentationServiceForRestfulObjects` is the default implementation of this service; likewise `ContentNegotiationServiceXRoDomainType` is the default implementation of the `ContentNegotiationService`. If you inspect the source code you'll see that the default implementation of this service's primary responsibility is to generate the default Restful Objects representations. Therefore, if you what you want to do is to generate a _different _representation then in many cases replacing either this service _or_ the `ContentNegotiationService` will be equivalent (you'll notice that their SPIs are very similar).
-
-
-== SPI
-
-The SPI defined by this service is:
-
-[source,java]
-----
-public interface RepresentationService {
- @Programmatic
- Response objectRepresentation( // <1>
- Context rendererContext,
- ObjectAdapter objectAdapter);
- @Programmatic
- Response propertyDetails( // <2>
- Context rendererContext,
- ObjectAndProperty objectAndProperty,
- MemberReprMode memberReprMode);
- @Programmatic
- Response collectionDetails( // <3>
- Context rendererContext,
- ObjectAndCollection objectAndCollection,
- MemberReprMode memberReprMode);
- @Programmatic
- Response actionPrompt( // <4>
- Context rendererContext,
- ObjectAndAction objectAndAction);
- @Programmatic
- Response actionResult( // <5>
- Context rendererContext,
- ObjectAndActionInvocation objectAndActionInvocation,
- ActionResultReprRenderer.SelfLink selfLink);
- public static interface Context extends RendererContext {
- ObjectAdapterLinkTo getAdapterLinkTo();
- }
-}
-----
-<1> representation of a single object, as per section 14.4 of the RO spec, v1.0
-<2> representation of a single property of an object, as per section 16.4 of the RO spec v1.0
-<3> representation of a single collection of an object, as per section 17.5 of the RO spec v1.0
-<4> representation of a single action (prompt) of an object, as per section 18.2 of the RO spec v1.0
-<5> representation of the results of a single action invocation, as per section 19.5 of the RO spec v1.0
-
-These methods provide:
-
-* a `RendererContext` which provides access to request-specific context (eg HTTP headers), session-specific context (eg authentication) and global context (eg configuration settings)
-
-* an object representing the information to be rendered +
-+
-eg `ObjectAdapter`, `ObjectAndProperty`, `ObjectAndCollection` etc
-
-* for members, whether the representation is in read/write mode +
-+
-ie `MemberReprMode`
-
-
-
-[WARNING]
-====
-This is an "internal" SPI, meaning that it uses types that are not part of the Isis applib. We do not guarantee that link:http://semver.org[semantic versioning] will be honoured for these APIs.
-====
-
-
-
-== Implementation
-
-As discussed in the introduction, the framework provides a default implementation, `o.a.i.v.ro.rendering.service.RepresentationServiceForRestfulObjects`. This delegates to xref:_ug_reference-services-spi_manpage-ContentNegotiationService[`ContentNegotiationService`] to generate an alternative representation; but if none is provided then it falls back on generating the representations as defined in the link:http://restfulobjects.org[Restful Objects spec] v1.0.
-
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Isis' default implementation of `RepresentationService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
-
-
-
-
-== Related Services
-
-The default implementation delegates to xref:_ug_reference-services-spi_manpage-ContentNegotiationService[`ContentNegotiationService`], whose default implementation may delegate in turn to xref:_ug_reference-services-spi_manpage-ContentMappingService[`ContentMappingService`] (if present).
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-TranslationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-TranslationService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-TranslationService.adoc
deleted file mode 100644
index 8218801..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-TranslationService.adoc
+++ /dev/null
@@ -1,79 +0,0 @@
-[[_ug_reference-services-spi_manpage-TranslationService]]
-= `TranslationService`
-: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 `TranslationService` is the cornerstone of Isis' i18n support. Its role is to be able to provide translated versions of the various elements within the Isis metamodel (service and object classes, properties, collections, actions, action parameters) and also to translate business rule (disable/valid) messages, and exceptions. These translations provide for both singular and plural forms.
-
-
-[NOTE]
-====
-For the "big picture" and further details on Isis' i18n support, see xref:_ug_more-advanced_i18n[here].
-====
-
-
-
-== SPI
-
-The SPI defined by this service is:
-
-[source,java]
-----
-public interface TranslationService {
- @Programmatic
- String translate(String context, String text); // <1>
- @Programmatic
- String translate(String context, // <2>
- String singularText,
- String pluralText, int num);
-
- enum Mode { READ, WRITE;}
- @Programmatic
- Mode getMode(); // <3>
-}
-
-----
-<1> translate the text, in the locale of the "current user".
-<2> return a translation of either the singular or the plural text, dependent on the `num` parameter, in the locale of the "current user"
-<3> whether this implementation is operating in read or in write mode.
-
-If in read mode, then the translations are expected to be present.
-
-If in write mode, then the implementation is saving translation keys, and will always return the untranslated translation.
-
-
-
-
-== Implementation
-
-The Isis framework provides a default implementation (`TranslationServicePo`) that uses the GNU `.pot` and `.po` files for translations. It relies on the `LocaleProvider` service (to return the `Locale` of the current user) and also the `TranslationsResolver` service (to read existing translations).
-
-The framework also provides a supporting `TranslationServicePoMenu` provides menu items under the "Prototyping" secondary menu for controlling this service and downloading `.pot` files for translation.
-
-For more details on the implementation, see xref:_ug_more-advanced_i18n[i18n support].
-
-
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Isis' core implementation of `TranslationService` service (along with the supporting menu service) are automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required. If the menu items are not required then these can be suppressed either using security or by implementing a xref:_ug_more-advanced_decoupling_vetoing-visibility[vetoing subscriber].
-
-
-
-
-
-== Related Services
-
-This service works in conjunction with xref:_ug_reference-services-spi_manpage-LocaleProvider[`LocaleProvider`] and xref:_ug_reference-services-spi_manpage-TranslationsResolver[`TranslationsResolver`] in order to provide i18n support.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-TranslationsResolver.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-TranslationsResolver.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-TranslationsResolver.adoc
deleted file mode 100644
index e93f1f6..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-TranslationsResolver.adoc
+++ /dev/null
@@ -1,67 +0,0 @@
-[[_ug_reference-services-spi_manpage-TranslationsResolver]]
-= `TranslationsResolver`
-: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 `TranslationsResolver` service is one of the services that work together to implement Isis' support for i18n, being used by Isis' default implementation of xref:_ug_reference-services-spi_manpage-TranslationService[`TranslationService`].
-
-The role of the service itself is locate and return translations.
-
-
-[NOTE]
-====
-For the "big picture" and further details on Isis' i18n support, see xref:_ug_more-advanced_i18n[here].
-====
-
-
-
-== SPI
-
-The SPI defined by this service is:
-
-[source,java]
-----
-public interface TranslationsResolver {
- @Programmatic
- List<String> readLines(final String file);
-}
-----
-
-
-== Implementation
-
-Isis' xref:_ug_wicket-viewer[Wicket viewer] provides an implementation of this service (`TranslationsResolverWicket`) which leverages Apache Wicket APIs. This searches for translation files in the standard `WEB-INF/` directory.
-
-[NOTE]
-====
-Currently there is no equivalent implementation for the xref:_ug_restfulobjects-viewer[RestfulObjects viewer].
-====
-
-
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-and that the xref:_ug_wicket-viewer[Wicket viewer] is being used then an implementation of `TranslationsResolver` is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
-
-
-
-
-
-== Related Services
-
-
-This service works in conjunction with xref:_ug_reference-services-spi_manpage-LocaleProvider[`LocaleProvider`] and xref:_ug_reference-services-spi_manpage-TranslationService[`TranslationService`] in order to provide i18n support.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-UserProfileService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-UserProfileService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-UserProfileService.adoc
deleted file mode 100644
index a7134e6..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-UserProfileService.adoc
+++ /dev/null
@@ -1,44 +0,0 @@
-[[_ug_reference-services-spi_manpage-UserProfileService]]
-= `UserProfileService`
-: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 `UserProfileService` provides the ability for the domain application to return supplementary metadata about the current user. This information is used (by the xref:_ug_wicket-viewer[Wicket viewer]) to customize the appearance of the tertiary "Me" menu bar (top right). For example, rather than display the username, instead the user's first and last name could be displayed.
-
-Another use case is to allow the user to switch context in some fashion or other. This might be to emulate a sort of "sudo"-like function, or perhaps to focus on some particular set of data.
-
-
-
-== SPI
-
-The SPI defined by the service is:
-
-[source,java]
-----
-public interface UserProfileService {
- @Programmatic
- String userProfileName(); // <1>
-}
-----
-<1> is used (in the Wicket viewer) as the menu name of the tertiary "Me" menu bar.
-
-If the method returns `null` or throws an exception then the framework will default to using the current user name.
-
-In the future this API may be expanded; one obvious possibility is to return a profile photo or avatar URL.
-
-
-
-== Implementation
-
-The (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] has a simple implementation of this service:
-
-image::{_imagesdir}reference-services-spi/UserProfileService/todoapp.png[width="800px",link="{_imagesdir}reference-services-spi/UserProfileService/todoapp.png"]
-
-
-[NOTE]
-====
-Currently this feature is not integrated with Isis' authentication mechanisms; the information provided is purely metadata provided for presentation purposes only.
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-UserRegistrationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-UserRegistrationService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-UserRegistrationService.adoc
deleted file mode 100644
index a2d647a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-UserRegistrationService.adoc
+++ /dev/null
@@ -1,81 +0,0 @@
-[[_ug_reference-services-spi_manpage-UserRegistrationService]]
-= `UserRegistrationService`
-: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 `UserRegistrationService` provides the ability for users to sign-up to access an application by providing a valid email address, and also provides the capability for users to reset their password if forgotten.
-
-For user sign-up, the xref:_ug_wicket-viewer[Wicket viewer] will check whether an implementation of this service (and also the xref:_ug_reference-services-spi_manpage-EmailNotificationService[`EmailNotificationService`]) is available, and if so will render a sign-up page where the user enters their email address. A verification email is sent (using the aforementioned `EmailNotificationService`) which includes a link back to the running application; this allows the user then to complete their registration process (choose user name, password and so on). When the user has provided the additional details, the Wicket viewer calls _this_ service in order to create an account for them, and then logs the user on.
-
-For the password reset feature, the Wicket viewer will render a password reset page, and use the `EmailNotificationService` to send a "password forgotten" email. This service provides the ability to reset a password based on the user's email address.
-
-It is of course possible for domain objects to use this service; it will be injected into domain object or other domain services in the usual way. That said, we expect that such use cases will be comparatively rare; the primary use case is for the Wicket viewer's sign-up page.
-
-[NOTE]
-====
-For further details on the user registration feature (as supported by the Wicket viewer), see xref:_ug_wicket-viewer_features_user-registration[here].
-====
-
-
-
-== SPI
-
-The SPI defined by the service is:
-
-[source,java]
-----
-public interface UserRegistrationService {
- @Programmatic
- boolean usernameExists(String username); // <1>
- @Programmatic
- boolean emailExists(String emailAddress); // <2>
- @Programmatic
- void registerUser(String username, String password, String emailAddress); // <3>
- @Programmatic
- boolean updatePasswordByEmail(String emailAddress, String password); // <4>
-}
-----
-<1> checks if there is already a user with the specified username
-<2> checks if there is already a user with the specified email address
-<3> creates the user, with specified password and email address. The username and email address must both be unique (not being used by an existing user)
-<4> allows the user to reset their password
-
-
-
-
-== Implementation
-
-The core Isis framework itself defines only an API; there is no default implementation. Rather, the implementation will depend on the security mechanism being used.
-
-That said, if you have configured your app to use the http://github.com/isisaddons/isis-module-security[Isis addons security module], then note that the security module does provide an abstract implementation (`SecurityModuleAppUserRegistrationServiceAbstract`) of the `UserRegistrationService`. You will need to extend that service and provide implementation for the two abstract methods: `getInitialRole()` and `getAdditionalInitialRoles()`.
-
-This is needed so that the self-registered users are assigned automatically to your application role(s) and be able to use the application. Without any role such user will be able only to see/use the logout link of the application.
-
-
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then (if using the (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module) you will need to register your concrete implementation of `SecurityModuleAppUserRegistrationServiceAbstract`.
-
-
-
-
-== Related Services
-
-The most common use case is to allow users to sign-up through Isis' Wicket viewer. Because the process requires email to be sent, the following services must be configured:
-
-* xref:_ug_reference-services-api_manpage-EmailService[`EmailService`]
-* xref:_ug_reference-services-spi_manpage-EmailNotificationService[`EmailNotificationService`]
-* `UserRegistrationService` (this service)
-
-The `EmailService` in particular requires additional xref:_ug_runtime_configuring-core[configuration properties] to specify the external SMTP service.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer.adoc
deleted file mode 100644
index abeecf1..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer.adoc
+++ /dev/null
@@ -1,25 +0,0 @@
-[[_ug_restfulobjects-viewer]]
-= Restful Objects Viewer
-: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/
-
-Apache Isis' Restful Objects viewer is an implementation of the link:http://restfulobjects.org[Restful Objects spec], which defines a generic way to expose a domain model through a REST (or more precisely, hypermedia) API.
-
-The Restful Objects viewer also provides a number of proprietary extensions.
-
-
-
-include::_ug_restfulobjects-viewer_features.adoc[leveloffset=+1]
-
-include::_ug_restfulobjects-viewer_configuration-properties.adoc[leveloffset=+1]
-
-include::_ug_restfulobjects-viewer_hints-and-tips.adoc[leveloffset=+1]
-
-
-== Extending the viewer
-
-... is discussed in xref:_ug_extending_restfulobjects-viewer[Extending the Restful Objects viewer].
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties.adoc
deleted file mode 100644
index 81ff855..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties.adoc
+++ /dev/null
@@ -1,72 +0,0 @@
-[[_ug_restfulobjects-viewer_configuration-properties]]
-= Configuration Properties
-: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 Restful Objects viewer provides a number of configuration option that extend/simplify/alter the representations generated from the Restful Objects specification.
-
-These configuration properties are typically stored in `WEB-INF/viewer_restfulobjects.properties`. However, you can place all configuration properties into `WEB-INF/isis.properties` if you wish (the configuration properties from all config files are merged together).
-
-[WARNING]
-====
-These configuration settings should be considered beta, and may change in the future in response to emerging requirements.
-
-Also, be aware enabling these settings makes the representations with respect to the http://restfulobjects.org[Restful Object spec]. (Based on experience in Isis, in the future the spec may be updated to allow such extensions).
-====
-
-
-.Restful Objects Viewer Configuration Properties
-[cols="2a,1,3", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Description
-
-|`isis.viewer.restfulobjects.` +
-`honorUiHints`
-| `true`,`false` (`_false_`)
-| See xref:_ug_restfulobjects-viewer_configuration-properties_honor-ui-hints[discussion], below.
-
-|`isis.viewer.restfulobjects.` +
-`suppressDescribedByLinks`
-| `true`,`false` (`_false_`)
-.6+| See xref:_ug_restfulobjects-viewer_configuration-properties_suppressing-elements[discussion], below.
-
-|`isis.viewer.restfulobjects.` +
-`suppressUpdateLink`
-| `true`,`false` (`_false_`)
-
-|`isis.viewer.restfulobjects.` +
-`suppressMemberId`
-| `true`,`false` (`_false_`)
-
-|`isis.viewer.restfulobjects.` +
-`suppressMemberLinks`
-| `true`,`false` (`_false_`)
-
-|`isis.viewer.restfulobjects.` +
-`suppressMemberExtensions`
-| `true`,`false` (`_false_`)
-
-|`isis.viewer.restfulobjects.` +
-`suppressMemberDisabledReason`
-| `true`,`false` (`_false_`)
-
-|`isis.viewer.restfulobjects.` +
-`objectPropertyValuesOnly`
-| `true`,`false` (`_false_`)
-| See xref:_ug_restfulobjects-viewer_configuration-properties_simplified-object[discussion], below.
-
-|===
-
-
-
-
-include::_ug_restfulobjects-viewer_configuration-properties_honor-ui-hints.adoc[leveloffset=+1]
-include::_ug_restfulobjects-viewer_configuration-properties_suppressing-elements.adoc[leveloffset=+1]
-include::_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation.adoc[leveloffset=+1]
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_honor-ui-hints.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_honor-ui-hints.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_honor-ui-hints.adoc
deleted file mode 100644
index c9122cc..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_honor-ui-hints.adoc
+++ /dev/null
@@ -1,27 +0,0 @@
-[[_ug_restfulobjects-viewer_configuration-properties_honor-ui-hints]]
-= Honor UI hints
-: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/
-
-
-
-
-By default the representations generated by Restful Objects ignore any Isis metamodel hints referring to the UI.
-In particular, if a collection is annotated then `Render(EAGERLY)` then the contents of the collection are _not_
-eagerly embedded in the object representation.
-
-However, this behaviour can be overridden globally using following property (typically added to `WEB-INF/viewer_restfulobjects.properties`):
-
-[source,ini]
-----
-isis.viewer.restfulobjects.honorUiHints=true
-----
-
-[NOTE]
-====
-In the future we might extend this per-request. Raise/vote on a JIRA ticket if you require this feature.
-====
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation.adoc
deleted file mode 100644
index e0b23d8..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation.adoc
+++ /dev/null
@@ -1,68 +0,0 @@
-[[_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation]]
-= Simplified object representation
-: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 representations specified by the http://restfulobjects.org[Restful Object spec] are very rich in hypermedia
-controls and metadata, intended to support a wide variety of possible REST clients.
-
-As described xref:_ug_restfulobjects-viewer_configuration-properties_suppressing-elements[above], it is possible to suppress various elements of these representations. Even then, though, the representations may be too complex for some bespoke REST clients that require a very "flat" object representation.
-
-The Restful Objects viewer therefore supports generating a much simpler representation of objects using the following configuration property (typically added to `WEB-INF/viewer_restfulobjects.properties`):
-
-[source,ini]
-----
-isis.viewer.restfulobjects.objectPropertyValuesOnly=true
-----
-
-This generates a representation such as:
-
-[source,javascript]
-----
-{
- "title" : "Buy milk due by 2014-10-27",
- "domainType" : "TODO",
- "instanceId" : "0",
- "members" : {
- "description" : "Buy milk",
- "category" : "Domestic",
- "subcategory" : "Shopping",
- "complete" : false,
- "versionSequence" : 1,
- "relativePriority" : 2,
- "dueBy" : "2014-10-27",
- "cost" : "0.75",
- "notes" : null,
- "attachment" : null,
- "doc" : null
- },
- "links" : [
- {
- "rel" : "self",
- "href" : "http://localhost:8080/restful/objects/TODO/0",
- "method" : "GET",
- "type" : "application/json;profile=\"urn:org.restfulobjects:repr-types/object\"",
- "title" : "Buy milk due by 2014-10-27"
- },
- {
- "rel" : "describedby",
- "href" : "http://localhost:8080/restful/domain-types/TODO",
- "method" : "GET",
- "type" : "application/json;profile=\"urn:org.restfulobjects:repr-types/domain-type\""
- }
- ],
- "extensions" : {
- "oid" : "TODO:0"
- },
-}
-----
-
-[NOTE]
-====
-In the future we might extend this per-request. Raise/vote on a JIRA ticket if you require this feature.
-====
-
-If the above isn't flexible and you need complete control over all representations see the section on xref:_ug_extending_restfulobjects-viewer[Extending the Restful Objects viewer].
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_suppressing-elements.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_suppressing-elements.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_suppressing-elements.adoc
deleted file mode 100644
index ff35c6b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_suppressing-elements.adoc
+++ /dev/null
@@ -1,39 +0,0 @@
-[[_ug_restfulobjects-viewer_configuration-properties_suppressing-elements]]
-= Suppressing elements of the representation
-: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 representations specified by the http://restfulobjects.org[Restful Object spec] are very rich in hypermedia controls and metadata, intended to support a wide variety of possible REST clients. However, if an application is providing its REST API only for a small well-defined set of REST clients, then it is possible to suppress (remove) various elements of these representations.
-
-This is done by globally using the following properties (typically added to `WEB-INF/viewer_restfulobjects.properties`):
-
-[source,ini]
-----
-isis.viewer.restfulobjects.suppressDescribedByLinks=true # <1>
-isis.viewer.restfulobjects.suppressUpdateLink=true # <2>
-isis.viewer.restfulobjects.suppressMemberId=true # <3>
-isis.viewer.restfulobjects.suppressMemberLinks=true # <4>
-isis.viewer.restfulobjects.suppressMemberExtensions=true # <5>
-isis.viewer.restfulobjects.suppressMemberDisabledReason=true # <6>
-----
-<1> suppresses the "describedby" links (on all representations)
-<2> suppresses the "update" link (on object representation)
-<3> suppresses the "id" json-prop for object members (on object representation and member detail representations)
-<4> suppresses the "links" json-prop for object members (on the object representation and member detail representations)
-<5> suppresses the "extensions" json-prop for object members (on the object representation and member detail representations)
-<6> suppresses the "disabledReason" json-prop for object members (on the object representation and member detail representations)
-
-The defaults for all of these is false, meaning that the hypermedia/metadata is NOT suppressed.
-
-[NOTE]
-====
-In the future we might extend this per-request. Raise/vote on a JIRA ticket if you require this feature.
-====
-
-If an even simpler representations (of objects) are required, see xref:_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation[simplified object representation], immediately below. And if the above isn't flexible and you need complete control over all representations see the section on xref:_ug_extending_restfulobjects-viewer[Extending the Restful Objects viewer] in the <<Extending>> chapter.
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_features.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_features.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_features.adoc
deleted file mode 100644
index 5043db5..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_features.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-[[_ug_restfulobjects-viewer_features]]
-= Features
-: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 REST API opens up an Isis domain model to a huge variety of applications, from bespoke single-page apps, through integration scenarious, through providing an API for bulk-upload/migration from an existing system.
-
-== Restful Objects Specification
-
-IMPORTANT: TODO - a brief summary here
-
-The Restful Objects spec can be downloaded link:http://restfulobjects.org[here].
-
-== Pretty printing
-
-The JSON representations generated by the Restful Objects viewer are in compact form if the xref:_ug_runtime_deployment-types[deployment type] is SERVER (ie production), but will automatically be "pretty printed" (in other words indented) if the deployment type is PROTOTYPE.
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_hints-and-tips.adoc
deleted file mode 100644
index b42c58a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_hints-and-tips.adoc
+++ /dev/null
@@ -1,81 +0,0 @@
-[[_ug_restfulobjects-viewer_hints-and-tips]]
-= Hints and Tips
-: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/
-
-
-
-Since the Restful Objects viewer is designed for computer programs to interact with (rather than human beings), it can be a little difficult to explore and generally "grok" how it works.
-
-This section provides a few hints-and-tips to help you on your way.
-
-
-== Using Chrome Tools
-
-The screencast below shows how to explore the Restful API using Chrome plugins/extensions, and how we use them to write end-2-end (TCK) tests for the Restful Objects viewer.
-
-video::_-TOvVYWCHc[youtube,width="840px",height="472px"]
-
-
-
-
-== AngularJS Tips
-
-The hypermedia API exposed by Isis' Restful Objects viewer is intended be support both bespoke custom-written viewers as well as generic viewers. Indeed, we expect most clients consuming the API will be bespoke, not generic.
-
-This page captures one or two tips on using AngularJS to write such a bespoke client.
-
-
-=== Invoking a GET link (eg invoking a query action)
-
-Suppose you have a `CustomerService` providing a `findCustomer` action:
-
-[source,java]
-----
-public class CustomerService {
- public String id() { return "customers"; }
- @ActionSemantics(Of.SAFE)
- public Customer findCustomer(@Named("customerName") String customerName) { ... }
-}
-----
-
-Restful Objects will expose this as action with the following link that looks something like:
-
-[source,javascript]
-----
-{
- "rel" : "urn:org.restfulobjects:rels/invoke",
- "href" : "http://localhost:8080/restful/services/customers/actions/findCustomer/invoke",
- "method" : "GET",
- "type" : "application/json;profile=\"urn:org.restfulobjects:repr-types/action-result\"",
- "arguments" : {
- "customerName" : {
- "value" : null
- }
- }
-}
-----
-
-You can then invoke this using AngularJs' `$resource` service as follows.
-
-[source,javascript]
-----
-var findCustomer = $resource("http://localhost:8080/restful/services/customers/actions/findCustomer/invoke?:queryString");
-var findCustomerArgs = {
- "customerName": {
- "value": "Fred"
- }
-};
-findCustomer.get({queryString: JSON.stringify(findCustomerArgs)}, function(data) { ... } )
-----
-
-Here the `:queryString` placeholder in the initial `$resource` constructor is expanded with a stringified version of the JSON object representing the args. Note how the `findCustomerArgs` is the same as the `"arguments"` attribute in the original link (with a value provided instead of `null`).
-
-
-=== Invoking a PUT or POST link
-
-If the method is a PUT or a POST, then no `:queryString` placeholder is required in the URL, and the args are instead part of the body.
-
-Use `$resource.put(...)` or `$resource.post(...)` instead.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime.adoc
deleted file mode 100644
index fb62b57..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime.adoc
+++ /dev/null
@@ -1,29 +0,0 @@
-[[_ug_runtime]]
-= Runtime
-: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/
-
-
-Isis' own configuration properties are simple key-value pairs, typically held in the `WEBINF/isis.properties` file and other related files. This chapter describes how to configure an Apache Isis application.
-
-[NOTE]
-====
-Configuration properties for the viewers can be found in the xref:_ug_wicket-viewer[Wicket Viewer] chapter and the <<Restful Objects Viewer>> chapter. Likewise[details of configuring security (Apache Shiro) can be found in the xref:_ug_security[Security] chapter.
-
-Also, note that by default the configuration values are part of the built WAR file. Details on how to override these configuration properties externally for different environments can be found in the <<Deployment>> chapter.
-====
-
-
-include::_ug_runtime_deployment-types.adoc[leveloffset=+1]
-include::_ug_runtime_configuration-files.adoc[leveloffset=+1]
-include::_ug_runtime_specifying-components.adoc[leveloffset=+1]
-include::_ug_runtime_configuring-core.adoc[leveloffset=+1]
-include::_ug_runtime_configuring-datanucleus.adoc[leveloffset=+1]
-include::_ug_runtime_web-xml.adoc[leveloffset=+1]
-include::_ug_runtime_application-specific.adoc[leveloffset=+1]
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_application-specific.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_application-specific.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_application-specific.adoc
deleted file mode 100644
index 156fad5..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_application-specific.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-[[_ug_runtime_application-specific]]
-= Application-specific CSS and JS
-: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
-
-
-include::_ug_runtime_application-specific_application-css.adoc[leveloffset=+1]
-include::_ug_runtime_application-specific_application-js.adoc[leveloffset=+1]
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_application-specific_application-css.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_application-specific_application-css.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_application-specific_application-css.adoc
deleted file mode 100644
index 59fdc5a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_application-specific_application-css.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_ug_runtime_application-specific_application-css]]
-= `application.css`
-: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 - `WEB-INF/css/application.css`
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_application-specific_application-js.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_application-specific_application-js.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_application-specific_application-js.adoc
deleted file mode 100644
index 4b97f1b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_application-specific_application-js.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ug_runtime_application-specific_application-js]]
-= `application.js`
-: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 - `WEB-INF/scripts/application.js`
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuration-files.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuration-files.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuration-files.adoc
deleted file mode 100644
index d3dcd6c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuration-files.adoc
+++ /dev/null
@@ -1,36 +0,0 @@
-[[_ug_runtime_configuration-files]]
-= Configuration Files
-: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/
-
-
-When running an Isis webapp, configuration properties are read from configuration files held in the `WEB-INF` directory.
-
-The `WEBINF/isis.properties` file is always read and must exist.
-
-In addition, the following other properties are searched for and if present also read:
-
-* `viewer_wicket.properties` - if the xref:_ug_wicket-viewer[Wicket UI (viewer)] is in use
-
-* `viewer_restfulobjects.properties` - if the xref:_ug_restfulobjects-viewer[Restful Objects REST API (viewer)] is in use
-
-* `viewer.properties` - for any shared UI configuration
-
-* `persistor_datanucleus.properties` - assuming the JDO/DataNucleus objectstore is in use
-
-* `persistor.properties` - for any other objectstore configuration. This typically is used to hold `JDBC` ``URL``s
-
-* `authentication_shiro.properties`, `authorization_shiro.properties`
-+
-assuming the Shiro Security is in use (but there are no security-related config properties currently; use shiro.ini for Shiro config)
-
-* `authentication.properties`, `authorization.properties` +
-+
-for any other security-related config properties (but there are none currently).
-
-You can if you wish simply store all properties in the `isis.properties` file; but we think that breaking properties out into sections is preferable.
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-core.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-core.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-core.adoc
deleted file mode 100644
index cef424f..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-core.adoc
+++ /dev/null
@@ -1,239 +0,0 @@
-[[_ug_runtime_configuring-core]]
-= Configuring Core
-: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/
-
-This section lists the core/runtime configuration properties recognized by Apache Isis.
-
-[NOTE]
-====
-Configuration properties for the JDO/DataNucleus objectstore can be found in the xref:_ug_runtime_configuring-datanucleus[Configuring DataNucleus] section later in this chapter, while configuration properties for the viewers can be found in the their respective chapters, xref:_ug_wicket-viewer_configuration-properties[here for Wicket viewer], and xref:_ug_restfulobjects-viewer_configuration-properties[here for the Restful Objects viewer].
-====
-
-
-
-.Core Configuration Properties
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value +
-(default value)
-|Description
-
-|`isis.object.` +
-`editing`
-| `true`,`false` (`true`)
-|Whether objects' properties and collections can be edited directly (for objects annotated with xref:_ug_reference-annotations_manpage-DomainObject_editing[`@DomainObject#editing()`]); see xref:_ug_runtime_configuring-core_isis-objects-editing[below] for further discussion.
-
-
-|`isis.persistor.` +
-`disableConcurrencyChecking`
-| `true`,`false` (`false`)
-| Disables concurrency checking globally. +
-
-Only intended for "emergency use" as a workaround while pending fix/patch to Isis itself. (Note that there is no "datanucleus" in the property).
-
-|`isis.reflector.facet.` +
-`cssClass.patterns`
-|regex:css1,regex2:css2,...
-|Comma separated list of key:value pairs, where the key is a regex matching action names (eg `delete.*`) and the value is a link:http://getbootstrap.com/css/[Bootstrap] CSS button class (eg `btn-warning) to be applied (as per `@CssClass()`) to all action members matching the regex. +
-
-See xref:_user-guide_how-tos_ui-hints_action-icons-and-css[UI hints] for more details.
-
-|`isis.reflector.facet.` +
-`cssClassFa.patterns`
-|regex:fa-icon,regex2:fa-icon2,...
-|Comma separated list of key:value pairs, where the key is a regex matching action names (eg `create.*`) and the value is a link:http://fortawesome.github.io/Font-Awesome/icons/[font-awesome] icon name (eg `fa-plus`) to be applied (as per `@CssClassFa()`) to all action members matching the regex. +
-
-See xref:_user-guide_how-tos_ui-hints_action-icons-and-css[UI hints] for more details.
-
-|`isis.reflector.facets`
-|`FQCN`
-|Fully qualified class names of a custom implementation of `ProgrammingModel` interface. +
-
-See xref:_ug_extending_programming-model_finetuning[finetuning the programming model] for more details.
-
-|`isis.reflector.facets.` +
-`exclude`
-|`FQCN`,`FQCN2`,...
-|Fully qualified class names of (existing, built-in) facet factory classes to be included to the programming model. +
-
-See xref:_ug_extending_programming-model_finetuning[finetuning the programming model] for more details.
-
-|`isis.reflector.facets.` +
-`include`
-|`FQCN`,`FQCN2`,...
-|Fully qualified class names of (new, custom) facet factory classes to be included to the programming model. +
-See xref:_ug_extending_programming-model_finetuning[finetuning the programming model] for more details.
-
-
-|`isis.reflector.` +
-`layoutMetadataReaders`
-|`FQCN`,`FQCN2`,...
-|Fully qualified class names of classes to be instantiated to read layout metadata, as used in for xref:_ug_reference-object-layout_dynamic[dynamic layout]s. +
-
-See xref:_ug_extending_programming-model_layout-metadata-reader[Layout Metadata Reader] for more information.
-
-
-
-|`isis.reflector.validator`
-|`FQCN`
-|Custom implementation of `MetaModelValidator` (in the `org.apache.isis.core.metamodel.specloader.validator` package) +
-
-See xref:_ug_extending_programming-model_custom-validator[Custom Validator] to learn more.
-
-|`isis.reflector.validator.` +
-`allowDeprecated`
-| `true`,`false` (`true`)
-| Whether deprecated annotations or naming conventions are tolerated or not. If not, then a metamodel validation error will be triggered, meaning the app won't boot (fail-fast).
-
-|`isis.services`
-|`FQCN`,`FQCN2`,...
-|Fully qualified class names of classes to be instantiated as domain services. +
-
-Each entry can be optionally prefixed by "n:" specifying the relative order on the menu (corresponds to xref:_ug_reference-annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]).
-
-
-|`isis.services.` +
-`audit.objects`
-| `all`, `none` (`all`)
-|Whether the changed properties of objects should be automatically audited (for objects annotated with xref:_ug_reference-annotations_manpage-DomainObject_auditing[`@DomainObject(auditing=Auditing.AS_CONFIGURED)`].
-
-|`isis.services.` +
-`command.actions`
-| `all`, `ignoreSafe`, `none` (`all`)
-|Whether actions should be automatically reified into commands (for actions annotated with xref:_ug_reference-annotations_manpage-Action_command[`@Action(command=CommandReification.AS_CONFIGURED)`]. +
-
-`ignoreQueryOnly` is an alias for `ignoreSafe`.
-
-|`isis.services.` +
-`container.disableAutoFlush`
-| `true`,`false` (`_false_`)
-|Whether the `DomainObjectContainer` should automatically flush pending changes prior to querying (via `allMatches()`, `firstMatch()` and so on).
-
-
-| `isis.service.` +
-`email.tls.enabled` +
-| `true`,`false` (`_true_`)
-|Whether to enable TLS for the email SMTP connection (used by xref:_ug_reference-services-api_manpage-EmailService[`EmailService`]). +
-
-NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.services.email`)
-
-| `isis.service.` +
-`email.sender.hostname` +
-| host (`_smtp.gmail.com_`)
-|The hostname of the external SMTP provider (used by xref:_ug_reference-services-api_manpage-EmailService[`EmailService`]). +
-
-NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.services.email`)
-
-| `isis.service.` +
-`email.port` +
-| port number (`_587_`)
-|The port number for the SMTP service on the the external SMTP host (used by xref:_ug_reference-services-api_manpage-EmailService[`EmailService`]). +
-
-NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.services.email`)
-
-
-| `isis.service.` +
-`email.sender.address` +
-| email address
-|The email address to use for sending out email (used by xref:_ug_reference-services-api_manpage-EmailService[`EmailService`]). *Mandatory*. +
-
-NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.services.email`)
-
-| `isis.service.` +
-`email.sender.password` +
-| email password
-|The corresponding password for the email address to use for sending out email (used by xref:_ug_reference-services-api_manpage-EmailService[`EmailService`]). *Mandatory*. +
-
-NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.services.email`)
-
-
-| `isis.services.` +
-`eventbus.implementation` +
-| `guava`, `axon`, FQCN (`_guava_`)
-|which implementation to use by the xref:_ug_reference-services-api_manpage-EventBusService[`EventBusService`] as the underlying event bus.
-
-| `isis.services.` +
-`eventbus.allowLateRegistration` +
-| `true`, `false`, (`_false_`)
-|whether a domain service can register with the xref:_ug_reference-services-api_manpage-EventBusService[`EventBusService`] after any events have posted. +
-
-Since this almost certainly constitutes a bug in application code, by default this is disallowed.
-
-
-|`isis.services.` +
-`publish.objects`
-| `all`, `none` (`all`)
-|Whether changed objects should be automatically published (for objects annotated with xref:_ug_reference-annotations_manpage-DomainObject_publishing[`@DomainObject(publishing=Publishing.AS_CONFIGURED)`].
-
-|`isis.services.` +
-`publish.actions`
-| `all`, `ignoreSafe`, `none` (`all`)
-|Whether actions should be automatically published (for actions annotated with xref:_ug_reference-annotations_manpage-Action_publishing[`@Action(publishing=Publishing.AS_CONFIGURED)`]. +
-
-|`isis.services.` +
-`translation.po.mode`
-| `read`,`write`
-|Whether to force the `TranslationService` into either read or write mode. +
-
-See xref:_ug_more-advanced_i18n[i18n support] to learn more about the translation service.
-
-|`isis.viewers.` +
-`paged.parented`
-|positive integer (12)
-|Default page size for parented collections (as owned by an object, eg `Customer#getOrders()`)
-
-|`isis.viewers.` +
-`paged.standalone`
-|positive integer (25)
-|Default page size for standalone collections (as returned from an action invocation)
-
-
-|`isis.viewers.` +
-`propertyLayout.labelPosition`
-|`TOP`, `LEFT` +
-(`LEFT`)
-|Default for label position for all properties if not explicitly specified using xref:_ug_reference-annotations_manpage-PropertyLayout_labelPosition[`@PropertyLayout#labelPosition()`]
-
-|===
-
-
-
-
-[[_ug_runtime_configuring-core_isis-objects-editing]]
-== `objects.editing`
-
-This configuration property in effect allows editing to be disabled globally for an application:
-
-[source,ini]
-----
-isis.objects.editing=false
-----
-
-We recommend enabling this feature; it will help drive out the underlying business operations (processes and procedures) that require objects to change; these can then be captured as business actions.
-
-
-
-[[_ug_runtime_configuring-core_isis-viewers-propertyLayout-labelPosition]]
-== `propertyLayout.labelPosition`
-
-If you want a consistent look-n-feel throughout the app, eg all property labels to the top, then it'd be rather
-frustrating to have to annotate every property.
-
-Instead, a default can be specified in `isis.properties`:
-
-[source,ini]
-----
-isis.viewers.propertyLayout.labelPosition=TOP
-----
-
-or
-
-[source,ini]
-----
-isis.viewers.propertyLayout.labelPosition=LEFT
-----
-
-If these are not present then Isis will render according to internal defaults. At the time of writing, this means labels are to the left for all datatypes except multiline strings.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus.adoc
deleted file mode 100644
index dd94c59..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-[[_ug_runtime_configuring-datanucleus]]
-= Configuring DataNucleus
-: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/
-
-Apache Isis programmatically configures DataNucleus; any Isis properties with the prefix `isis.persistor.datanucleus.impl` are passed through directly to the JDO/DataNucleus objectstore (with the prefix stripped off, of course).
-
-DataNucleus will for itself also and read the `META-INF/persistence.xml`; at a minimum this defines the name of the "persistence unit". n theory it could also hold mappings, though in Isis we tend to use annotations instead.
-
-Furthermore, DataNucleus will search for various other XML mapping files, eg `mappings.jdo`. A full list can be found http://www.datanucleus.org/products/datanucleus/jdo/metadata.html[here]. The metadata in these XML can be used to override the annotations of annotated entities; see xref:_ug_more-advanced_overriding-jdo-annotations[Overriding JDO Annotatons] for further discussion.
-
-
-include::_ug_runtime_configuring-datanucleus_properties.adoc[leveloffset=+1]
-include::_ug_runtime_configuring-datanucleus_persistence-xml.adoc[leveloffset=+1]
-include::_ug_runtime_configuring-datanucleus_eagerly-registering-entities.adoc[leveloffset=+1]
-include::_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc[leveloffset=+1]
-include::_ug_runtime_configuring-datanucleus_using-jndi-data-source.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc
deleted file mode 100644
index 25ad73a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc
+++ /dev/null
@@ -1,88 +0,0 @@
-[[_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability]]
-= Persistence by Reachability
-: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/
-
-By default, JDO/DataNucleus supports the concept of http://www.datanucleus.org/products/datanucleus/jdo/orm/cascading.html[persistence-by-reachability]. That is, if
-a non-persistent entity is associated with an already-persistent entity, then DataNucleus will detect this and will automatically persist the associated object. Put another way: there is no need to call Isis' `DomainObjectContainer#persist(.)` or `DomainObjectContainer#persistIfNotAlready(.)` methods.
-
-However, convenient though this feature is, you may find that it causes performance issues.
-
-[WARNING]
-====
-DataNucleus' persistence-by-reachability may cause performance issues. We strongly recommend that you disable it.
-====
-
-One scenario in particular where this performance issues can arise is if your entities implement the `java.lang.Comparable` interface, and you have used Isis' xref:_ug_reference-classes_utility_manpage-ObjectContracts[`ObjectContracts`] utility class. The issue here is that `ObjectContracts` implementation can cause DataNucleus to recursively rehydrate a larger number of associated entities. (More detail below).
-
-We therefore recommend that you disable persistence-by-reachability by adding the following to `persistor_datanucleus.properties`:
-
-[source,ini]
-----
-isis.persistor.datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=false
-----
-
-This change has been made to the xref:_ug_getting-started_simpleapp-archetype[SimpleApp archetype]
-
-If you do disable this feature, then you will (of course) need to ensure that you explicitly persist all entities using the `DomainObjectContainer#persist(.)` or `DomainObjectContainer#persistIfNotAlready(.)` methods.
-
-
-
-
-
-== The issue in more detail
-
-Consider these entities (http://yuml.me/edit/b8681268[yuml.me/b8681268]):
-
-image::{_imagesdir}runtime/configuring-datanucleus/disabling-persistence-by-reachability/party-agreementrole-agreement.png[width="750px"]
-
-
-
-In the course of a transaction, the `Agreement` entity is loaded into memory (not necessarily modified), and then new ``AgreementRole``s are associated to it.
-
-All these entities implement `Comparable` using `ObjectContracts`, and the implementation of ``AgreementRole``'s (simplified) is:
-
-[source,java]
-----
-public class AgreementRole {
- ...
- public int compareTo(AgreementRole other) {
- return ObjectContracts.compareTo(this, other, "agreement","startDate","party");
- }
-}
-----
-
-while ``Agreement``'s is implemented as:
-
-[source,java]
-----
-public class Agreement {
- ...
- public int compareTo(Agreement other) {
- return ObjectContracts.compareTo(this, other, "reference");
- }
-}
-----
-
-and ``Party``'s is similarly implemented as:
-
-[source,java]
-----
-public class Party {
- ...
- public int compareTo(Party other) {
- return ObjectContracts.compareTo(this, other, "reference");
- }
-}
-----
-
-DataNucleus's persistence-by-reachability algorithm adds the `AgreementRole` instances into a `SortedSet`, which causes `AgreementRole#compareTo()` to fire:
-
-* the evaluation of the "agreement" property delegates back to the `Agreement`, whose own `Agreement#compareTo()` uses the scalar `reference` property. As the `Agreement` is already in-memory, this does not trigger any further database queries
-
-* the evaluation of the "startDate" property is just a scalar property of the `AgreementRole`, so will already in-memory
-
-* the evaluation of the "party" property delegates back to the `Party`, whose own `Party#compareTo()` requires the uses the scalar `reference` property. However, since the `Party` is not yet in-memory, using the `reference` property triggers a database query to "rehydrate" the `Party` instance.
-
-In other words, in figuring out whether `AgreementRole` requires the persistence-by-reachability algorithm to run, it causes the adjacent associated entity `Party` to also be retrieved.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_eagerly-registering-entities.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_eagerly-registering-entities.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_eagerly-registering-entities.adoc
deleted file mode 100644
index 5d99d25..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_eagerly-registering-entities.adoc
+++ /dev/null
@@ -1,44 +0,0 @@
-[[_ug_runtime_configuring-datanucleus_eagerly-registering-entities]]
-= Eagerly Registering Entities
-: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/
-
-Both Apache Isis and DataNucleus have their own metamodels of the domain entities. Isis builds its metamodel by walking the graph of types from the services registered using `@DomainService` or explicitly registered in `isis.properties`. The JDO objectstore then takes these types and registers them with DataNucleus.
-
-In some cases, though, not every entity type is discoverable from the API of the service actions. This is especially the case if you have lots of subtypes (where the action method specifies only the supertype). In such cases the Isis and JDO metamodels is built lazily, when an instance of that (sub)type is first encountered.
-
-Isis is quite happy for the metamodel to be lazily created, and - to be fair - DataNucleus also works well in most cases. In some cases, though, we have found that the JDBC driver (eg HSQLDB) will deadlock if DataNucleus tries to submit some DDL (for a lazily discovered type) intermingled with DML (for updating).
-
-In any case, it's probably not good practice to have DataNucleus work this way. The `RegisterEntities` service can therefore be registered in order to do the eager registration. It searches for all `@PersistenceCapable` entities under specified package(s), and registers them all.
-
-[WARNING]
-====
-There's a chance that (from 1.6.0+) feature may be (partly?) broken; see https://issues.apache.org/jira/browse/ISIS-847[ISIS-847].
-====
-
-
-== Specify the Package Prefix(es)
-
-In the `persistor_datanucleus.properties`, specify the package prefix(es) of your application, to provide a hint for finding the `@PersistenceCapable` classes.
-
-The value of this property can be a comma-separated list (if there is more than one package or Maven module that holds persistable entities).
-
-
-== Integration Testing
-
-The `IsisConfigurationForJdoIntegTests`, recommended for use in xref:_ug_testing_integ-test-support[Integration Testing] provides the `#addRegisterEntitiesPackagePrefix()` method to set up this configuration property:
-
-[source,java]
-.Integration test bootstrapping
-----
-private static class SimpleAppSystemBuilder extends IsisSystemForTest.Builder {
- ...
- private static IsisConfiguration testConfiguration() {
- final IsisConfigurationForJdoIntegTests testConfiguration = new IsisConfigurationForJdoIntegTests();
- testConfiguration.addRegisterEntitiesPackagePrefix("domainapp.dom.modules"); // <1>
- return testConfiguration;
- }
-}
-----
-<1> specify the package prefix(es) for integration testing.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_persistence-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_persistence-xml.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_persistence-xml.adoc
deleted file mode 100644
index cf8b777..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_persistence-xml.adoc
+++ /dev/null
@@ -1,10 +0,0 @@
-[[_ug_runtime_configuring-datanucleus_persistence-xml]]
-= `persistence.xml`
-: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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_properties.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_properties.adoc
deleted file mode 100644
index b740bab..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_properties.adoc
+++ /dev/null
@@ -1,64 +0,0 @@
-[[_ug_runtime_configuring-datanucleus_properties]]
-= Configuration Properties
-: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/
-
-
-These configuration properties are typically stored in `WEB-INF/persistor_datanucleus.properties`. However, you can place all configuration properties into `WEB-INF/isis.properties` if you wish (the configuration properties from all config files are merged together).
-
-== Configuration Properties for Apache Isis itself
-
-
-.JDO/DataNucleus Objectstore Configuration Properties
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Description
-
-|`isis.persistor.` +
-`datanucleus.` +
-`classMetadataLoadedListener`
-|`FQCN`
-|The default (`o.a.i.os.jdo.dn.CreateSchemaObjectFromClassMetadata`) creates a DB schema object
-
-
-|`isis.persistor.datanucleus.` +
-`RegisterEntities.packagePrefix`
-| fully qualified package names (CSV)
-| of class names; specifies the entities early rather than allow DataNucleus to find the entities lazily. Strongly recommended (subtle issues can sometimes arise if lazy discovery is used).
-Further xref:_ug_runtime_configuring-datanucleus_eagerly-registering-entities[discussion below].
-
-|`isis.persistor.datanucleus.` +
-`PublishingService.serializedForm`
-| zipped
-|
-
-|===
-
-
-
-== Configuration Properties passed through directly to DataNucleus.
-
-.JDO/DataNucleus Objectstore Configuration Properties
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Description
-
-|`isis.persistor.datanucleus.impl.*`
-|
-| Passed through directly to Datanucleus (with `isis.persistor.datanucleus.impl` prefix stripped)
-
-|`isis.persistor.datanucleus.impl.` +
-`datanucleus.persistenceByReachabilityAtCommit`
-|`false`
-|We recommend this setting is disabled. +
-Further xref:_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability[discussion below].
-
-|===
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_using-jndi-data-source.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_using-jndi-data-source.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_using-jndi-data-source.adoc
deleted file mode 100644
index 25649c0..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_using-jndi-data-source.adoc
+++ /dev/null
@@ -1,75 +0,0 @@
-[[_ug_runtime_configuring-datanucleus_using-jndi-data-source]]
-= Using JNDI DataSource
-: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/
-
-Isis' JDO objectstore can be configured either to connect to the database using its own connection pool, or by using a container-managed datasource.
-
-
-
-== Application managed
-
-Using a connection pool managed directly by the application (that is, by Isis' JDO objectstore and ultimately by DataNucleus) requires a single set of configuration properties to be specified.
-
-In the `WEB-INF\persistor_datanucleus.properties` file, specify the connection driver, url, username and password.
-
-For example:
-
-[source,ini]
-----
-isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionDriverName=net.sf.log4jdbc.DriverSpy
-isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionURL=jdbc:log4jdbc:hsqldb:mem:test
-isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionUserName=sa
-isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionPassword=
-----
-
-Those configuration properties that start with the prefix `isis.persistor.datanucleus.impl.` are passed through directly to DataNucleus (with the prefix removed).
-
-
-
-
-
-== Container managed (JNDI)
-
-Using a datasource managed by the servlet container requires three separate bits of configuration.
-
-Firstly, specify the name of the datasource in the `WEB-INF\persistor_datanucleus.properties` file. For example:
-
-If connection pool settings are also present in this file, they will simply be ignored. Any other configuration properties that start with the prefix `isis.persistor.datanucleus.impl.` are passed through directly to DataNucleus (with the prefix removed).
-
-Secondly, in the `WEB-INF/web.xml`, declare the resource reference:
-
-[source,xml]
-----
-<resource-ref>
- <description>db</description>
- <res-ref-name>jdbc/simpleapp</res-ref-name>
- <res-type>javax.sql.DataSource</res-type>
- <res-auth>Container</res-auth>
-</resource-ref>
-----
-
-Finally, declare the datasource as required by the servlet container. For example, if using Tomcat 7, the datasource can be specified by adding the following to `$TOMCAT_HOME/conf/context.xml`:
-
-[source,xml]
-----
-<Resource name="jdbc/simpleapp"
- auth="Container"
- type="javax.sql.DataSource"
- maxActive="100"
- maxIdle="30"
- maxWait="10000"
- username="sa"
- password="p4ssword"
- driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"
- url="jdbc:sqlserver://127.0.0.1:1433;instance=.;databaseName=simpleapp"/>
-----
-
-You will also need to make sure that the JDBC driver is on the servlet container's classpath. For Tomcat, this means copying the driver to `$TOMCAT_HOME/lib`.
-
-[NOTE]
-====
-According to Tomcat's documentation, it is supposedly possible to copy the `conf/context.xml` to the name of the webapp, eg `conf/mywebapp.xml`, and scope the connection to that webapp only. I was unable to get this working, however.
-====
-