You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2017/03/31 07:10:54 UTC
[18/51] [partial] isis git commit: ISIS-1521: reorganizes asciidoc
documentation, moves into subdirs (both guides and other pages)
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugsec_api-for-applications.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugsec_api-for-applications.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugsec_api-for-applications.adoc
deleted file mode 100644
index 0193b38..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugsec_api-for-applications.adoc
+++ /dev/null
@@ -1,63 +0,0 @@
-[[_ugsec_api-for-applications]]
-= API for Applications
-: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/
-
-
-
-Generally speaking your domain objects (or more generally your application) should be agnostic of the user/roles that are interacting with them; applying security permissions is the responsibility of the framework.
-
-Still, on very rare occasion you may have a need, in which case you can either use Apache Isis' `DomainObjectContainer` API or you can reach further down the stack and use the JEE Servlet API.
-
-
-== `DomainObjectContainer` API
-
-The xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`] service exposes the following API:
-
-[source,java]
-----
-final UserMemento user = container.getUser();
-final List<RoleMemento> roles = user.getRoles();
-for (RoleMemento role : roles) {
- String roleName = role.getName();
- ...
-}
-----
-
-Each role's `name` property encodes both the realm that provided the role, and the role identity itself.
-
-For example, in the simpleapp, if logging in as `dick` with the following entries for `realm1`:
-
-[source,ini]
-----
-dick = pass, user_role, analysis_role, self-install_role
-----
-
-then this corresponds to the roles "realm1:user_role", "realm1:self-install_role" and "realm1:analysis_role".
-
-If using the Wicket viewer, then note there will also be another role which is used internally (namely "org.apache.isis.viewer.wicket.roles.USER").
-
-
-
-
-
-== Servlet API
-
-On occasion you may find it necessary to reach below Isis and to the underlying servlet API. For example, the http://github.com/isisaddons/isis-module-togglz[Isis addons' togglz] module (non-ASF) has a requirement to do this in order to expose its embedded togglz web console. (
-
-[TIP]
-====
-If you do need to access the servlet API and are running within the context of Wicket viewer, the http://github.com/isisaddons/isis-module-servletapi[Isis addons' servletapi] module can provide access to the `HttpServletRequest`, `HttpServletResponse` and `ServletContext`.
-====
-
-In this situation, you can still obtain some information about the user and its roles:
-
-[source,java]
-----
-Principal principal = httpServletRequest.getPrincipal();
-String username = principal.getName();
-boolean analyst = httpServletRequest.isUserInRole("analysis_role");
-----
-
-However, it isn't possible to obtain any role permissions for the user.
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugsec_configuring-isis-to-use-bypass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugsec_configuring-isis-to-use-bypass.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugsec_configuring-isis-to-use-bypass.adoc
deleted file mode 100644
index 59ae68a..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugsec_configuring-isis-to-use-bypass.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-[[_ugsec_configuring-isis-to-use-bypass]]
-= Bypassing security
-: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 bypass security component consists of an implementation of both the `AuthenticationManager` and `AuthorizationManager` APIs, and are intended for prototyping use only.
-
-The authentication manager allows access with any credentials (in a sense, "bypassing" authentication), while the authorization manager provides access to all class members (in a sense, "bypassing" authorization).
-
-
-To tell Apache Isis to bypass security, just update the `WEB-INF/isis.properties` file:
-
-[source,ini]
-----
-isis.authentication=bypass
-isis.authorization=bypass
-----
-
-This installs the appropriate no-op implementations for both authentication and authorization:
-
-image::{_imagesdir}security/security-apis-impl/configure-isis-to-use-bypass.PNG[width="600px"]
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugsec_configuring-isis-to-use-shiro.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugsec_configuring-isis-to-use-shiro.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugsec_configuring-isis-to-use-shiro.adoc
deleted file mode 100644
index 9604eaf..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugsec_configuring-isis-to-use-shiro.adoc
+++ /dev/null
@@ -1,98 +0,0 @@
-[[_ugsec_configuring-isis-to-use-shiro]]
-= Configuring Apache Isis to use Shiro
-: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' security mechanism is configurable, specifying an `Authenticator` and an `Authorizor` (non-public) APIs. The Shiro security mechanism is an integration wih Apache Shiro that implements both interfaces.
-
-[TIP]
-====
-The xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] is pre-configured to use Apache Shiro, so much of what follows is set up already.
-====
-
-== Telling Apache Isis to use Shiro
-
-To tell Apache Isis to use Shiro, update the `WEB-INF/isis.properties` file:
-
-[source,ini]
-----
-isis.authentication=shiro
-isis.authorization=shiro
-----
-
-This installs the appropriate implementation (the `ShiroAuthenticatorOrAuthorizor` class) that use Shiro's APIs to perform authentication and authorization:
-
-image::{_imagesdir}security/security-apis-impl/configure-isis-to-use-shiro.png[width="600px"]
-
-The figure above doesn't tell the whole story; we haven't yet seen how Shiro itself is configured to use realms. The `ShiroAuthenticatorOrAuthorizor` is in essence the glue between the Apache Isis runtime and Shiro.
-
-== Configuring Isis' Shiro Authenticator
-
-The `ShiroAuthenticatorOrAuthorizor` class itself supports a single optional property. This can
-be configured in `authentication_shiro.properties` file:
-
-[source,ini]
-----
-isis.authentication.shiro.autoLogoutIfAlreadyAuthenticated=false
-----
-
-This configuration property only comes into effect for the xref:ugvro.adoc#[Restful Objects viewer]; if set then
-the Shiro subject - if found to be still authenticated - will be logged out anyway and then re-authenticated.
-
-[WARNING]
-====
-This auto-logout behaviour was the default prior to `1.13.0`, but is believed to be the root cause of some
-exceptions caused by a possible race condition. There should generally be no need to change this property from its
-default (`false`).
-====
-
-
-
-== Bootstrapping Shiro
-
-The Shiro environment (in essence, thread-locals holding the security credentials) needs to be bootstrapped using the following settings in the `WEB-INF/web.xml` file:
-
-[source,xml]
-----
-<listener>
- <listener-class>org.apache.shiro.web.env.EnvironmentLoaderListener</listener-class>
-</listener>
-<filter>
- <filter-name>ShiroFilter</filter-name>
- <filter-class>org.apache.shiro.web.servlet.ShiroFilter</filter-class>
-</filter>
-<filter-mapping>
- <filter-name>ShiroFilter</filter-name>
- <url-pattern>/*</url-pattern>
-</filter-mapping>
-----
-
-Based on this Shiro will then read `WEB-INF/shiro.ini` file to configure its Realm definitions for authentication and authorization.
-
-
-
-== `WEB-INF/shiro.ini`
-
-The `shiro.ini` file is used to specify the realm(s) that Shiro will delegate to:
-
-[source,ini]
-----
-securityManager.realms = $realmName
-----
-
-Shiro's ini file supports a "poor-man's" dependency injection (link:https://shiro.apache.org/configuration.html[their words]), and so `$realmName` in the above example is a reference to a realm defined elsewhere in `shiro.ini`. The subsequent sections describe the specifics for thevarious realm implementations available to you.
-
-
-It's also possible to configure Shiro to support multiple realms.
-
-[source,ini]
-----
-securityManager.realms = $realm1,$realm2
-----
-
-You can learn more about Shiro realms in the link:http://shiro.apache.org/realm.html[Shiro documentation].
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-caching.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-caching.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-caching.adoc
deleted file mode 100644
index da39857..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-caching.adoc
+++ /dev/null
@@ -1,41 +0,0 @@
-[[_ugsec_shiro-caching]]
-= Caching and other Shiro 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/
-
-
-We don't want to repeat the entire link:http://shiro.apache.org/documentation.html[Shiro documentation set] here, but we should flag a number of otherof other features that are worth checking out.
-
-
-
-
-== Caching
-
-To ensure that security operations does not impede performance, Shiro supports caching. For example, this sets up a simple memory-based cache manager:
-
-[source,ini]
-----
-memoryCacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager
-securityManager.cacheManager = $memoryCacheManager
-----
-
-Other implementations can be plugged in; see the Shiro link:http://shiro.apache.org/caching.html[documentation] for further details.
-
-
-
-
-== Further Reading
-
-
-* Shiro's documentation page can be found link:http://shiro.apache.org/documentation.html[here].
-
-* community-contributed articles can be found link:http://shiro.apache.org/articles.html[here]. +
-+
-These include for instance link:http://meri-stuff.blogspot.co.uk/2011/04/apache-shiro-part-2-realms-database-and.html[this interesting article] describing how to perform certificate-based authentication (ie login using Google or Facebook credentials).
-
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-ini-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-ini-realm.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-ini-realm.adoc
deleted file mode 100644
index ec14f68..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-ini-realm.adoc
+++ /dev/null
@@ -1,133 +0,0 @@
-[[_ugsec_shiro-ini-realm]]
-= Shiro Ini Realm
-: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/
-
-
-Probably the simplest realm to use is Shiro's built-in `IniRealm`, which reads from the (same) `WEB-INF/shiro.ini` file.
-
-This is suitable for prototyping, but isn't intended for production use, if only because user/password credentials are stored in plain text. Nevertheless, it's a good starting point. The app generated by the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] is configured to use this realm.
-
-The diagram below shows the Isis and components involved:
-
-image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-ini-realm.PNG[width="600px"]
-
-The realm is responsible for validating the user credentials, and then creates a Shiro link:http://shiro.apache.org/static/latest/apidocs/org/apache/shiro/subject/Subject.html[`Subject`] which represents the user (for the current request). Apache Isis `Authenticator` component then interacts with the `Subject` in order to check permissions.
-
-
-
-
-== Shiro Configuration
-
-To use the built-in `IniRealm`, we add the following to `WEB-INF/shiro.ini`:
-
-[source,ini]
-----
-securityManager.realms = $iniRealm
-----
-
-(Unlike other realms) there is no need to "define" `$iniRealm`; it is automatically available to us.
-
-Specifying `$iniRealm` means that the usernames/passwords, roles and permissions are read from the `shiro.ini` file itself. Specifically:
-
-* the users/passwords and their roles from the `[users]` sections;
-* the roles are mapped to permissions in the `[roles]` section.
-
-The format of these is described below.
-
-=== `[users]` section
-
-This section lists users, passwords and their roles.
-
-For example:
-
-[source,ini]
-----
-sven = pass, admin_role
-dick = pass, user_role, analysis_role, self-install_role
-bob = pass, user_role, self-install_role
-----
-The first value is the password (eg "pass", the remaining values are the role(s).
-
-
-=== `[roles]` section
-
-This section lists roles and their corresponding permissions.
-
-For example:
-
-[source,ini]
-----
-user_role = *:ToDoItems:*:*,\
- *:ToDoItem:*:*,\
- *:ToDoAppDashboard:*:*
-analysis_role = *:ToDoItemAnalysis:*:*,\
- *:ToDoItemsByCategoryViewModel:*:*,\
- *:ToDoItemsByDateRangeViewModel:*:*
-self-install_role = *:ToDoItemsFixturesService:install:*
-admin_role = *
-----
-
-The value is a comma-separated list of permissions for the role. The format is:
-
-[source,ini]
-----
-packageName:className:memberName:r,w
-----
-
-where:
-
-* `memberName` is the property, collection or action name.
-* `r` indicates that the member is visible
-* `w` indicates that the member is usable (editable or invokable)
-
-and where each of the parts of the permission string can be wildcarded using `*`.
-
-Because these are wildcards, a '*' can be used at any level. Additionally, missing levels assume wildcards.
-
-Thus:
-
-[source,ini]
-----
-com.mycompany.myapp:Customer:firstName:r,w # view or edit customer's firstName
-com.mycompany.myapp:Customer:lastName:r # view customer's lastName only
-com.mycompany.myapp:Customer:placeOrder:* # view and invoke placeOrder action
-com.mycompany.myapp:Customer:placeOrder # ditto
-com.mycompany.myapp:Customer:*:r # view all customer class members
-com.mycompany.myapp:*:*:r # view-only access for all classes in myapp package
-com.mycompany.myapp:*:*:* # view/edit for all classes in myapp package
-com.mycompany.myapp:*:* # ditto
-com.mycompany.myapp:* # ditto
-com.mycompany.myapp # ditto
-* # view/edit access to everything
-----
-
-[TIP]
-====
-The format of the permissions string is configurable in Shiro, and Apache Isis uses this to provide an extended wildcard format, described xref:ugsec.adoc#_ugsec_shiro-isis-enhanced-wildcard-permission[here].
-====
-
-
-
-
-== Externalized IniRealm
-
-There's no requirement for all users/roles to be defined in the `shiro.ini` file. Instead, a realm can be defined that loads its users/roles from some other resource.
-
-For example:
-
-[source,ini]
-----
-$realm1=org.apache.shiro.realm.text.IniRealm # <1>
-realm1.resourcePath=classpath:webapp/realm1.ini # <2>
-----
-<1> happens to (coincidentally) be the link:http://shiro.apache.org/static/latest/apidocs/org/apache/shiro/realm/text/IniRealm.html[same implementation] as Shiro's built-in $iniRealm
-<2> in this case load the users/roles from the `src/main/resources/webapp/realm1.ini` file.
-
-Note that a URL could be provided as the `resourcePath`, so a centralized config file could be used. Even so, the
-
-[NOTE]
-====
-If configured this way then the `[users]` and `[roles]` sections of `shiro.ini` become unused. Instead, the corresponding sections from for `realm1.ini` are used instead.
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-isis-enhanced-wildcard-permission.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-isis-enhanced-wildcard-permission.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-isis-enhanced-wildcard-permission.adoc
deleted file mode 100644
index 7bb22c5..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-isis-enhanced-wildcard-permission.adoc
+++ /dev/null
@@ -1,61 +0,0 @@
-[[_ugsec_shiro-isis-enhanced-wildcard-permission]]
-= Enhanced Wildcard Permission
-: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/
-
-
-If using the text-based xref:ugsec.adoc#_ugsec_shiro-ini-realm[`IniRealm`] or xref:ugsec.adoc#_ugsec_shiro-isis-ldap-realm[Isis' LDAP realm], then note that Shiro also allows the string representation of the permissions to be mapped (resolved) to alternative `Permission` instances. Apache Isis provides its own `IsisPermission` which introduces the concept of a "veto".
-
-A vetoing permission is one that prevents access to a feature, rather than grants it. This is useful in some situations where most users have access to most features, and only a small number of features are particularly sensitive. The configuration can therefore be set up to grant fairly broad-brush permissions and then veto permission for the sensitive features for those users that do not have access.
-
-The string representation of the `IsisPermission` uses the following format:
-
-[source,ini]
-----
-([!]?)([^/]+)[/](.+)
-----
-
-where:
-
-* the optional `!` prefix indicates this permission is a vetoing permission
-* the optional `xxx/` prefix is a permission group that scopes any vetoing permissions
-* the remainder of the string is the permission (possibly wildcarded, with :rw as optional suffix)
-
-
-For example:
-
-[source,ini]
-----
-user_role = !reg/org.estatio.api,\
- !reg/org.estatio.webapp.services.admin,\
- reg/* ; \
-api_role = org.estatio.api ;\
-admin_role = adm/*
-----
-
-sets up:
-
-* the `user_role` with access to all permissions except those in `org.estatio.api` and `org.estatio.webapp.services.admin`
-* the `api_role` with access to all permissions in `org.estatio.api`
-* the `admin_role` with access to everything.
-
-The permission group concept is required to scope the applicability of any veto permission. This is probably best explained by an example. Suppose that a user has both `admin_role` and `user_role`; we would want the `admin_role` to trump the vetos of the `user_role`, in other words to give the user access to everything.
-
-
-Because of the permission groups, the two "+++!reg/...+""" vetos in user_role only veto out selected permissions granted by the "+++reg/*+++" permissions, but they do not veto the permissions granted by a different scope, namely "+++adm/*+++".
-
-The net effect is therefore what we would want: that a user with both `admin_role` and `user_role` would have access to everything, irrespective of those two veto permissions of the `user_role`.
-
-
-
-Finally, the Apache Isis permission resolver is specified in `WEB-INF/shiro.ini` file:
-
-[source,ini]
-----
-permissionResolver = org.apache.isis.security.shiro.authorization.IsisPermissionResolver
-myRealm.permissionResolver = $permissionResolver # <1>
-----
-<1> `myRealm` is the handle to the configured realm, eg `$iniRealm` or `$isisLdapRealm` etc.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-isis-ldap-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-isis-ldap-realm.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-isis-ldap-realm.adoc
deleted file mode 100644
index 20ac868..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-isis-ldap-realm.adoc
+++ /dev/null
@@ -1,146 +0,0 @@
-[[_ugsec_shiro-isis-ldap-realm]]
-= Isis Ldap Realm
-: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 ships with an implementation of http://shiro.apache.org[Apache Shiro]'s `Realm` class that allows user authentication and authorization to be performed against an LDAP server.
-
-image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-isis-ldap-realm.PNG[width="600px"]
-
-The LDAP database stores the user/passwords and user groups, while the `shiro.ini` file is used to map the LDAP groups to roles, and to map the roles to permissions.
-
-== Shiro Configuration
-
-To use LDAP involves telling Shiro how to instantiate the realm. This bootstrapping info lives in the `WEB-INF/shiro.ini`:
-
-[source,ini]
-----
-contextFactory = org.apache.isis.security.shiro.IsisLdapContextFactory
-contextFactory.url = ldap://localhost:10389
-contextFactory.systemUsername = uid=admin,ou=system # <1>
-contextFactory.systemPassword = secret
-contextFactory.authenticationMechanism = CRAM-MD5 # <2>
-contextFactory.systemAuthenticationMechanism = simple
-
-ldapRealm = org.apache.isis.security.shiro.IsisLdapRealm # <3>
-ldapRealm.contextFactory = $contextFactory
-
-ldapRealm.searchBase = ou=groups,o=mojo # <4>
-ldapRealm.groupObjectClass = groupOfUniqueNames # <5>
-ldapRealm.uniqueMemberAttribute = uniqueMember # <6>
-ldapRealm.uniqueMemberAttributeValueTemplate = uid={0}
-
-# optional mapping from physical groups to logical application roles
-ldapRealm.rolesByGroup = \ # <7>
- LDN_USERS: user_role,\
- NYK_USERS: user_role,\
- HKG_USERS: user_role,\
- GLOBAL_ADMIN: admin_role,\
- DEMOS: self-install_role
-
-ldapRealm.permissionsByRole=\ # <8>
- user_role = *:ToDoItemsJdo:*:*,\
- *:ToDoItem:*:*; \
- self-install_role = *:ToDoItemsFixturesService:install:* ; \
- admin_role = *
-
-securityManager.realms = $ldapRealm
-----
-<1> user accounts are searched using a dedicated service account
-<2> SASL (CRAM-MD5) authentication is used for this authentication
-<3> Apache Isis' implementation of the LDAP realm.
-<4> groups are searched under `ou=groups,o=mojo` (where `mojo` is the company name)
-<5> each group has an LDAP objectClass of `groupOfUniqueNames`
-<6> each group has a vector attribute of `uniqueMember`
-<7> groups looked up from LDAP can optionally be mapped to logical roles; otherwise groups are used as role names directly
-<8> roles are mapped in turn to permissions
-
-The value of `uniqueMember` is in the form `uid=xxx`, with `xxx` being the uid of the user
-* users searched under `ou=system`
-* users have, at minimum, a `uid` attribute and a password
-* the users credentials are used to verify their user/password
-
-The above configuration has been tested against http://directory.apache.org/apacheds/[ApacheDS], v1.5.7. This can be administered using http://directory.apache.org/studio/[Apache Directory Studio], v1.5.3.
-
-
-[TIP]
-.Shiro Realm Mappings
-====
-When configuring role based permission mapping, there can only be one of these entries per realm:
-
-[source,ini]
-----
-realm.groupToRolesMappings = ...
-----
-
-and
-
-[source,ini]
-----
-realm.roleToPermissionsMappings = ...
-----
-
-This forces you to put everything on one line for each of the above. This is, unfortunately, a Shiro "feature". And if you repeat the entries above then it's "last one wins".)
-
-To make the configuration maintainable, use "\" to separate the mappings onto separate lines in the file. Use this technique for both group to roles mapping and role to permission mapping. If you use the '' after the "," that separates the key:value pairs it is more readable.
-====
-
-
-
-
-
-
-== Externalizing role perms
-
-As an alternative to injecting the `permissionsByRole` property, the role/permission mapping can alternatively be specified by injecting a resource path:
-
-[source,ini]
-----
-ldapRealm.resourcePath=classpath:webapp/myroles.ini
-----
-
-where `myroles.ini` is in `src/main/resources/webapp`, and takes the form:
-
-[source,ini]
-----
-[roles]
-user_role = *:ToDoItemsJdo:*:*,\
- *:ToDoItem:*:*
-self-install_role = *:ToDoItemsFixturesService:install:*
-admin_role = *
-----
-
-This separation of the role/mapping can be useful if Shiro is configured to support multiple realms (eg an LdapRealm based one and also an TextRealm)
-
-
-
-
-== Active DS LDAP tutorial
-
-The screenshots below show how to setup LDAP accounts in ApacheDS using the Apache Directory Studio.
-
-The setup here was initially based on http://krams915.blogspot.co.uk/2011/01/ldap-apache-directory-studio-basic.html[this tutorial], however we have moved the user accounts so that they are defined in a separate LDAP node.
-
-To start, create a partition in order to hold the mojo node (holding the groups):
-
-image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-mojo-partition.png[ActiveDS LDAP Users]
-
-Create the `ou=groups,o=mojo` hierarchy:
-
-image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-mojo-root-dse.png[ActiveDS LDAP Users]
-
-Configure SASL authentication. This means that the checking of user/password is done implicitly by virtue of Apache Isis connecting to LDAP using these credentials:
-
-image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-sasl-authentication.png[ActiveDS LDAP Users]
-
-In order for SASL to work, it seems to be necessary to put users under `o=system`. (This is why the setup is slightly different than the tutorial mentioned above):
-
-image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-users.png[ActiveDS LDAP Users]
-
-Configure the users into the groups:
-
-image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-groups.png[ActiveDS LDAP Users]
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-isisaddons-security-module-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-isisaddons-security-module-realm.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-isisaddons-security-module-realm.adoc
deleted file mode 100644
index 5406b97..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-isisaddons-security-module-realm.adoc
+++ /dev/null
@@ -1,36 +0,0 @@
-[[_ugsec_shiro-isisaddons-security-module-realm]]
-= Security Module Realm
-: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 https://github.com/isisaddons/isis-module-security[Isis Addons' security module] (not ASF) provides a complete
-security subdomain for users, roles, permissions; all are persisted as domain entities.
-
-What that means, of course, that they can also be administered through your Isis application. Moreover, the set of permissions (to features) is derived completely from your application's metamodel; in essence the permissions are "type-safe".
-
-
-In order to play along, the module includes a Shiro realm, which fits in as follows:
-
-The general configuration is as follows:
-
-image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm.PNG[width="600px"]
-
-where the `IsisModuleSecurityRealm` realm is the implementation provided by the module.
-
-In the configuration above user passwords are stored in the database. The module uses link:http://www.mindrot.org/projects/jBCrypt/[jBCrypt] so that passwords are only stored in a (one-way) encrypted form in the database.
-
-
-
-The security module also supports a slightly more sophisticated configuration. Most organizations use LDAP for user credentials, and maintaining two separate user accounts would be less than ideal. The `IsisModuleSecurityRealm` can therefore be configured with a subsidiary "delegate" realm that is responsible for performing the primary authentication of the user; if that passes then a user is created (as a domain entity) automatically.
-In most cases this delegate realm will be the LDAP realm, and so the architecture becomes:
-
-image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm-with-delegate-realm.PNG[width="600px"]
-
-
-The security module has many more features than are described here, all of which are described in the module's link:https://github.com/isisaddons/isis-module-security[README]. The README also explains in detail how to configure an existing app to use this module.
-
-You can also look at the Isisaddons https://github.com/isisaddons/isis-app-todoapp[todoapp example] (not ASF), which is preconfigured to use the security module.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-jdbc-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-jdbc-realm.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-jdbc-realm.adoc
deleted file mode 100644
index 9ca4107..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-jdbc-realm.adoc
+++ /dev/null
@@ -1,113 +0,0 @@
-[[_ugsec_shiro-jdbc-realm]]
-= Shiro JDBC Realm
-: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/
-
-
-
-There is nothing to stop you from using some other `Realm` implementation (or indeed writing one yourself). For example, you could use Shiro's own JDBC realm that loads user/password details from a database.
-
-[WARNING]
-====
-If you are happy to use a database then we strongly recommend you use the http://github.com/isisaddons/isis-module-security[Isis addons' security] module instead of a vanilla JDBC; it is far more sophisticated and moreover gives you the ability to administer the system from within your Isis application.
-====
-
-If you go down this route, then the architecture is as follows:
-
-image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-custom-jdbc-realm.png[width="600px"]
-
-
-
-
-There's quite a lot of configuration required (in `WEB-INF/shiro.ini`) to set up a JDBC realm, so we'll break it out into sections.
-
-First, we need to set up the connection to JDBC:
-
-[source,ini]
-----
-jdbcRealm=org.apache.shiro.realm.jdbc.JdbcRealm # <1>
-
-jof = org.apache.shiro.jndi.JndiObjectFactory # <2>
-jof.resourceName = jdbc/postgres # <3>
-jof.requiredType = javax.sql.DataSource
-jof.resourceRef = true
-
-jdbcRealm.dataSource = $jof # <4>
-----
-<1> instantiate the JDBC realm
-<2> instantiate factory object to lookup DataSource from servlet container
-<3> name of the datasource (as configured in `web.xml`)
-<4> instruct JDBC realm to obtain datasource from the JNDI
-
-
-We next need to tell the realm how to query the database. Shiro supports any schema; what matters is the input search argument and the output results.
-
-[source,ini]
-----
-
-jdbcRealm.authenticationQuery = \ # <1>
- select password \
- from users \
- where username = ?
-
-jdbcRealm.userRolesQuery = \ # <2>
- select r.label \
- from users_roles ur \
- inner join roles r \
- on ur.role_id = r.id \
- where user_id = ( \
- select id \
- from users \
- where username = ?); \
-
-jdbcRealm.permissionsQuery= \ # <3>
- select p.permission \
- from roles_permissions rp \
- inner join permissions p \
- on rp.permission_id = p.id \
- where rp.role_id = ( \
- select id \
- from roles \
- where label = ?);
-
-jdbcRealm.permissionsLookupEnabled=true # <4>
-----
-<1> query to find password for user
-<2> query to find roles for user
-<3> query to find permissions for role
-<4> enable permissions lookup
-
-[WARNING]
-====
-The `permissionsLookupEnabled` is very important, otherwise Shiro just returns an empty list of permissions and your users will have no access to any features(!).
-====
-
-We also should ensure that the passwords are not stored as plain-text:
-
-[source,ini]
-----
-dps = org.apache.shiro.authc.credential.DefaultPasswordService # <1>
-pm = org.apache.shiro.authc.credential.PasswordMatcher # <2>
-pm.passwordService = $dps
-jdbcRealm.credentialsMatcher = $pm # <3>
-----
-<1> mechanism to encrypts password
-<2> service to match passwords
-<3> instruct JDBC realm to use password matching service when authenticating
-
-
-And finally we need to tell Shiro to use the realm, in the usual fashion:
-
-[source,ini]
-----
-securityManager.realms = $jdbcRealm
-----
-
-Using the above configuration you will also need to setup a `DataSource`. The details vary by servlet container, for example this is link:https://tomcat.apache.org/tomcat-8.0-doc/jndi-datasource-examples-howto.html[how to do the setup on Tomcat 8.0].
-
-[WARNING]
-====
-The name of the `DataSource` can also vary by servlet container; see for example link:http://stackoverflow.com/questions/17441019/how-to-configure-jdbcrealm-to-obtain-its-datasource-from-jndi/23784702#23784702[this StackOverflow answer].
-====
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugsec_usage-by-isis-viewers.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugsec_usage-by-isis-viewers.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugsec_usage-by-isis-viewers.adoc
deleted file mode 100644
index ed0f10a..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugsec_usage-by-isis-viewers.adoc
+++ /dev/null
@@ -1,212 +0,0 @@
-[[_ugsec_usage-by-isis-viewers]]
-= Usage by Apache Isis' Viewers
-: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 and large the security mechanisms within Isis are transparent to the rest of the framework (the xref:ugvw.adoc#[Wicket Viewer] and xref:ugvro.adoc#[Restful Objects viewer], and the overall xref:rgcfg.adoc#_rgcfg[runtime]).
-
-That said, it is the responsibility of the viewers to ensure that there is a viewers to ensure that for each request there is a valid user session present. The sections below explain how this works.
-
-
-
-
-== Wicket Viewer
-
-The xref:ugvw.adoc#[Wicket viewer] defines a relatively small number of pages (by which we mean subclasses of link:http://ci.apache.org/projects/wicket/apidocs/6.0.x/org/apache/wicket/markup/html/WebPage.html[`org.apache.wicket.markup.html.WebPage`]):
-
-* about page
-* action prompt page
-* entity page
-* error page
-* home page
-* standalone collection page
-* value page
-* void return page
-
-All of these (except about page) are annotated with the Wicket annotation:
-
-[source,java]
-----
-@AuthorizeInstantiation("org.apache.isis.viewer.wicket.roles.USER")
-----
-
-which means that they can only be accessed by a user with an authenticated session that has this special, reserved role. If not, Wicket will automatically redirect the user to the sign-in page.
-
-[TIP]
-====
-The sign-in page to render is pluggable; see xref:ugvw.adoc#_ugvw_extending_custom-pages[extensions chapter] for details.
-====
-
-In the sign-in page the viewer calls to the Isis Authenticator API, and obtains back a user/role. It also adds in its special reserved role (per the annotation above) and then continues on to whichever page the user was attempting to access (usually the home page).
-
-And that's really all there is to it. When the viewer renders a domain object it queries the Apache Isis metamodel, and suppresses from the view any object members (properties, actions etc) that are invisible. These may be invisible because the user has no (read ) permission, or they may be invisible because of domain object logic (eg a `hideXxx()` method). The viewer neither knows nor cares.
-
-Similarly, for those object members that _are_ visible, the viewer also checks if they are enabled or disabled. Again, an object member will be disabled if the user does not have (write) permission, or it could be disabled because of domain object logic (eg a `disableXxx()` method).
-
-
-=== User-registration
-
-As well as providing a sign-in screen, the Wicket viewer also provides the ability for xref:_user_registration[users to self-register]. By and large this operates outside of Apache Isis' security mechanisms; indeed the various pages (sign-up, sign-up verification, password reset) are all rendered _without_ there being any current user session. These pages all "reach inside" Apache Isis framework using a mechanism similar to xref:ugbtb.adoc#_ugbtb_headless-access[Headless access] in order to actually do their stuff.
-
-[TIP]
-====
-The sign-in verification page to render is pluggable; see xref:ugvw.adoc#_ugvw_extending_custom-pages[extensions chapter] for details.
-====
-
-User registration is only available if the xref:rgsvc.adoc#_rgsvc_spi_UserRegistrationService[`UserRegistrationService`] is configured; this is used by the framework to actually create new instances of the user as accessed by the corresponding (Shiro) realm.
-
-Because Shiro realms are pluggable, the Apache Isis framework does not provide default implementations of this service. However, if you are using the http://github.com/isisaddons/isis-module-security[Isis addons' security] module (non-ASF), then this module _does_ provide an implementation (that, as you might expect, creates new "user" domain entities).
-
-If you are using an LDAP realm and want to enable user-self registration then you'll need to write your own implementation of this service.
-
-
-
-== Restful Objects Viewer
-
-Unlike the Wicket viewer, the xref:ugvro.adoc#[Restful Objects viewer] does *not* provide any sort of login page; rather it provides a pluggable authentication strategy, delegated to by the `IsisSessionFilter` filter defined in `web.xml`. The authentication strategy is responsible for ensuring that a session is available for the REST resource.
-
-The API of `AuthenticationSessionStrategy` is simply:
-
-[source,java]
-----
-package org.apache.isis.core.webapp.auth;
-...
-public interface AuthenticationSessionStrategy {
- AuthenticationSession lookupValid( // <1>
- ServletRequest servletRequest,
- ServletResponse servletResponse);
- void bind( // <2>
- ServletRequest servletRequest,
- ServletResponse servletResponse,
- AuthenticationSession authSession);
-}
-
-----
-<1> returns a valid `AuthenticationSession` for the specified request, response
-<2> binds (associates the provided `AuthenticationSession`) to the request and response
-
-Here `AuthenticationSession` is Apache Isis' internal API that represents a signed-on user.
-
-The framework provides a number of simple strategies:
-
-* `AuthenticationSessionStrategyBasicAuth` implements the HTTP basic auth protocol (the pop-up dialog box shown by the web browser)
-* `AuthenticationSessionStrategyHeader` that simply reads the user identity from an HTTP header
-* `AuthenticationSessionStrategyTrusted` that always logs in with a special "exploration" user
-
-As you can see, none of these should be considered production-quality.
-
-The strategy is configured in `web.xml`; for example:
-
-[source,xml]
-----
-<filter>
- <filter-name>IsisSessionFilterForRestfulObjects</filter-name>
- <filter-class>org.apache.isis.core.webapp.IsisSessionFilter</filter-class>
- <init-param>
- <param-name>authenticationSessionStrategy</param-name>
- <param-value> <!--1-->
- org.apache.isis.viewer.restfulobjects.server.authentication.AuthenticationSessionStrategyBasicAuth
- </param-value>
- </init-param>
- <init-param>
- <param-name>whenNoSession</param-name>
- <param-value>auto</param-value> <!--2-->
- </init-param>
- <init-param>
- <param-name>passThru</param-name>
- <param-value>/restful/swagger</param-value> <!--3-->
- </init-param>
-</filter>
-----
-<1> configure basic auth strategy
-<2> what to do if no session was found; we use `auto` so as to issue a 401 status code with basic authentication challenge if the request originated from a web browser. (Prior to `1.11.0` this parameter was set either to `basicAuthChallenge` (which works when requested from web browser) or to `unauthorized` (which works when requested from a suitably coded custom Javascript app).
-<3> which paths are allowed to be accessed directly, without a session. The `/restful/swagger` path provides access to the SwaggerResource that dynamically generates swagger spec files from the Apache Isis metamodel.
-
-
-The above filter must then be chained before the servlet that actually handles the REST requests:
-
-[source,xml]
-----
-<filter-mapping>
- <filter-name>IsisSessionFilterForRestfulObjects</filter-name>
- <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
-</filter-mapping>
-...
-<servlet>
- <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
- <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
-</servlet>
-----
-
-[NOTE]
-====
-The above `web.xml` fragments do _not_ constitute the full configuration for the Restful Objects viewer, just those parts that pertain to security.
-====
-
-
-
-=== User-registration
-
-Isis currently does not have any out-of-the-box support for user-registration for applications using only the Restful viewer. However, in principal the pieces do exist to put together a solution.
-
-The general idea is similar to the design of the Wicket viewer; define some subsidiary resources that can operate _without_ a user session in place, and which "reach into" the framework using headless access in order to setup the user.
-
-[TIP]
-====
-An alternative approach, possibly less work and overall of more value, would be to implement `AuthenticationSessionStrategy` for oAuth, in other words allow users to use their existing Google or Facebook account.
-====
-
-The following steps sketch out the solution in a little more detail:
-
-* Define some new Restful resources (cf link:https://github.com/apache/isis/blob/master/core/viewer-restfulobjects-server/src/main/java/org/apache/isis/viewer/restfulobjects/server/resources/DomainObjectResourceServerside.java[`DomainServiceResourceServerside`] that correspond to sign-up/register page, eg `SignupResource` +
-+
-[source,java]
-----
-@Path("/signup")
-public class SignupResource {
- ...
-}
-----
-
-* Create a new subclass of `RestfulObjectsApplication`, eg "CustomRestfulObjectsApplication" and register your resources +
-+
-[source,java]
-----
-public class CustomRestfulObjectsApplication extends RestfulObjectsApplication {
- public CustomRestfulObjectsApplication() {
- addClass(SignupResource.class);
- }
-}
-----
-
-* Register your application class in `web.xml` instead of the default: +
-+
-[source,xml]
-----
-<context-param>
- <param-name>javax.ws.rs.Application</param-name>
- <param-value>com.mycompany.myapp.CustomRestfulObjectsApplication</param-value>
-</context-param>
-----
-
-So far this is just standard javax.rs stuff.
-
-Next, we need to ensure that a client can hit your new resource *with* the Apache Isis runtime in place, but without there being an Apache Isis session. For that....
-
-* create a subclass of the `AuthenticationSessionStrategy` that automatically returns a dummy session if the resource being accessed is "/restful/signup", say. +
-+
-You could do this by subclassing `AuthenticationSessionStrategyBasicAuth`, but then using code from `AuthenticationSessionStrategyBasicAuth` to return an "exploration" (or better, "signup") session if accessing the "/restful/signup" resource.
-
-* in the `SignUpResource` resource, you can then do a lookup of the `UserRegistrationService` in order to allow the user to be created: +
-+
-[source,java]
-----
-final UserRegistrationService userRegistrationService =
- IsisContext.getPersistenceSession().getServicesInjector().lookupService(UserRegistrationService.class);
-userRegistrationService.registerUser(userDetails);
-----
-
-Obviously the methods exposed by the `SignupResource` are up to you; ultimately they need to be able to gather information to populate the `UserDetails` object as passed to the `UserRegistrationService`.
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugtst_aaa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_aaa.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_aaa.adoc
deleted file mode 100644
index 4aa46d4..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_aaa.adoc
+++ /dev/null
@@ -1,166 +0,0 @@
-[[_ugtst_aaa]]
-= Overview
-: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/
-
-
-== Unit tests vs Integ tests
-
-We divide automated tests into two broad categories:
-
-- unit tests exercise a single unit (usually a method) of a domain object, in isolation. +
-+
-Dependencies of that object are mocked out. These are written by a developer and for a developer; they are to ensure that a particular "cog in the machine" works correctly
-
-- integration tests exercise the application as a whole, usually focusing on one particular business operation (action). +
-+
-These are tests that represent the acceptance criteria of some business story; their intent should make sense to the domain expert (even if the domain expert is "non-technical")
-
-To put it another way:
-
-[TIP]
-====
-Integration tests help ensure that you are *_building the right system_*
-
-Unit tests help ensure that you are *_building the system right_*.
-====
-
-
-
-== Integ tests vs BDD Specs
-
-We further sub-divide integration tests into:
-
-* those that are implemented in Java and JUnit (we call these simply _"integration tests"_) +
-+
-Even if a domain expert understands the intent of these tests, the actual implementation will be opaque to them. Also, the only output from the tests is a (hopefully) green CI job
-
-* tests (or rather, specifications) that are implemented in a _behaviour-driven design_ (BDD) language such as link:https://cucumber.io/[Cucumber] (we call these _"BDD specs"_) +
-+
-The natural language specification then maps down onto some glue code that is used to drive the application. But the benefits of taking a BDD approach include the fact that your domain expert will be able to read the tests/specifications, and that when you run the specs, you also get documentation of the application's behaviour ("living documentation").
-
-It's up to you whether you use BDD specs for your apps; it will depend on your development process and company culture. But you if don't then you certainly should write integration tests: acceptance criteria for user stories should be automated!
-
-
-
-
-
-== Simulated UI (`WrapperFactory`)
-
-When we talk about integration tests/specs here, we mean tests that exercise the domain object logic, through to the actual database. But we also want the tests to exercise the app from the users's perspective, which means including the user interface.
-
-For most other frameworks that would require having to test the application in a very heavy weight/fragile fashion using a tool such as link:http://docs.seleniumhq.org/[Selenium], driving a web browser to navigate . In this regard though, Apache Isis has a significant trick up its sleeve. Because Apache Isis implements the naked objects pattern, it means that the UI is generated automatically from the UI. This therefore allows for other implementations of the UI.
-
-The xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] domain service allows a test to wrap domain objects and thus to interact with said objects "as if" through the UI:
-
-image::{_imagesdir}testing/integ-tests.png[width="700px"]
-
-If the test invokes an action that is disabled, then the wrapper will throw an appropriate exception. If the action is ok to invoke, it delegates through.
-
-What this means is that an Isis application can be tested end-to-end without having to deploy it onto a webserver; the whole app can be tested while running in-memory. Although integration tests re (necessarily) slower than unit tests, they are not any harder to write (in fact, in some respects they are easier).
-
-
-
-
-== Dependency Injection
-
-Isis provides autowiring dependency injection into every domain object. This is most useful when writing unit tests; simply mock out the service and inject into the domain object.
-
-There are a number of syntaxes supported, but the simplest is to use `@javax.inject.Inject` annotation; for example:
-
-[source,java]
-----
-@javax.inject.Inject
-CustomerRepository customers;
-----
-
-Isis can inject into this even if the field has package-level (or even `private`) visibility. We recommend that you use package-level visibility, though, so that your unit tests (in the same package as the class under test) are able to inject mocks.
-
-Isis does also support a couple of other syntaxes:
-
-[source,java]
-----
-public void setCustomerRepository(CustomerRepository customers) { ... }
-----
-
-or
-
-[source,java]
-----
-public void injectCustomerRepository(CustomerRepository customers) { ... }
-----
-
-
-[TIP]
-====
-Apache Isis also supports automatic dependency injection into integration tests; just declare the service dependency in the usual fashion and it will be automatically injected.
-====
-
-
-
-
-== Given/When/Then
-
-Whatever type of test/spec you are writing, we recommend you follow the given/when/then idiom:
-
-* *given* the system is in this state (preconditions)
-* *when* I poke it with a stick
-* *then* it looks like this (postconditions)
-
-A good test should be 5 to 10 lines long; the test should be there to help you reason about the behaviour of the system. Certainly if the test becomes more than 20 lines it'll be too difficult to understand.
-
-The "when" part is usually a one-liner, and in the "then" part there will often be only two or three assertions that you want to make that the system has changed as it should.
-
-For unit test the "given" part shouldn't be too difficult either: just instantiate the class under test, wire in the appropriate mocks and set up the expectations. And if there are too many mock expectations to set up, then "listen to the tests" ... they are telling you your design needs some work.
-
-Where things get difficult though is the "given" for integration tests; which is the topic of the next section...
-
-
-
-
-== Fixture Management
-
-In the previous section we discussed using given/when/then as a form of organizing tests, and why you should keep your tests small.
-
-For integration tests though it can be difficult to keep the "given" short; there could be a lot of prerequisite data that needs to exist before you can actually exercise your system. Moreover, however we do set up that data, but we also want to do so in a way that is resilient to the system changing over time.
-
-The solution that Apache Isis provides is a domain service called xref:rgcms.adoc#_rgcms_classes_super_FixtureScripts[Fixture Scripts], that defines a pattern and supporting classes to help ensure that the "data setup" for your tests are reusable and maintainable over time.
-
-
-
-
-
-== Fake data
-
-In any given test there are often quite a few variables involved, to initialize the state of the objects, or to act as arguments for invoking a method, or when asserting on post-conditions. Sometimes those values are important (eg verifying that an `Order`'s state went from PENDING to SHIPPED, say), but often they aren't (a customer's name, for example) but nevertheless need to be set up (especially in integration tests).
-
-We want our tests to be easily understood, and we want the reader's eye to be drawn to the values that are significant and ignore those that are not.
-
-One way to do this is to use random (or fake) values for any insignificant data. This in effect tells the reader that "any value will do". Moreover, if it turns out that any data won't do, and that there's some behaviour that is sensitive to the value, then the test will start to flicker, passing and then failing depending on inputs. This is A Good Thing™.
-
-Apache Isis does not, itself, ship with a fake data library. However, the http://github.com/isisaddons/isis-module-fakedata[Isis addons' fakedata] module (non-ASF) does provide exactly this capability.
-
-[TIP]
-====
-Using fake data works very well with fixture scripts; the fixture script can invoke the business action with sensible (fake/random) defaults, and only require that the essential information is passed into it by the test.
-====
-
-
-
-
-== Feature Toggles
-
-Writing automated tests is just good development practice. Also good practice is developing on the mainline (master, trunk); so that your continuous integration system really is integrating all code. Said another way: link:http://martinfowler.com/bliki/FeatureBranch.html[don't use branches]!
-
-Sometimes, though, a feature will take longer to implement than your iteration cycle. In such a case, how do you use continuous integration to keep everyone working on the mainline without revealing a half-implemented feature on your releases? One option is to use link:http://martinfowler.com/bliki/FeatureToggle.html[feature toggle]s.
-
-Apache Isis does not, itself, ship with a feature toggle library. However, the http://github.com/isisaddons/isis-module-togglz[Isis addons' togglz] module (non-ASF) does provide exactly this capability.
-
-
-
-
-
-With all that said, let's look in detail at the testing features provided by Apache Isis.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support.adoc
deleted file mode 100644
index 09d8534..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support.adoc
+++ /dev/null
@@ -1,22 +0,0 @@
-[[_ugtst_bdd-spec-support]]
-= BDD Spec Support
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-link:http://en.wikipedia.org/wiki/Behavior-driven_development[Behaviour-driven design] (BDD) redefines testing not as an after-the-fact "let's check the system works", but rather as a means to work with the domain expert to (a) specify the behaviour of the feature _before_ starting implementation, and (b) provide a means that the domain expert can verify the feature after it has been implemented.
-
-Since domain experts are usually non-technical (at least, they are unlikely to be able to read or want to learn how to read JUnit/Java code), then applying BDD typically requires writing specifications in using structured English text and (ASCII) tables. The BDD tooling parses this text and uses it to actually interact with the system under test. As a byproduct the BDD frameworks generate readable output of some form; this is often an annotated version of the original specification, marked up to indicate which specifications passed, which have failed. This readable output is a form of "living documentation"; it captures the actual behaviour of the system, and so is guaranteed to be accurate.
-
-There are many BDD tools out there; Apache Isis provides an integration with link:https://cucumber.io/docs/reference/jvm#java[Cucumber JVM] (see also the https://github.com/cucumber/cucumber-jvm[github site]):
-
-
-
-include::_ugtst_bdd-spec-support_how-it-works.adoc[leveloffset=+1]
-include::_ugtst_bdd-spec-support_key-classes.adoc[leveloffset=+1]
-include::_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc[leveloffset=+1]
-include::_ugtst_bdd-spec-support_bdd-tooling.adoc[leveloffset=+1]
-include::_ugtst_bdd-spec-support_maven-configuration.adoc[leveloffset=+1]
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_bdd-tooling.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_bdd-tooling.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_bdd-tooling.adoc
deleted file mode 100644
index b2196be..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_bdd-tooling.adoc
+++ /dev/null
@@ -1,14 +0,0 @@
-[[_ugtst_bdd-spec-support_bdd-tooling]]
-= BDD Tooling
-: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/
-
-
-
-
-
-To help write feature files and generate step definitions, we recommend https://github.com/rlogiacco/Natural[Roberto Lo Giacco's Eclipse plugin]. For more information, see Dan's short http://danhaywood.com/2013/07/05/cucumber-editors-in-eclipse/[blog post]. It works very well. Of interest: this is implemented using http://www.eclipse.org/Xtext/[XText].
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_how-it-works.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_how-it-works.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_how-it-works.adoc
deleted file mode 100644
index a6da0ad..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_how-it-works.adoc
+++ /dev/null
@@ -1,20 +0,0 @@
-[[_ugtst_bdd-spec-support_how-it-works]]
-= How it works
-: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/
-
-
-
-At a high level, here's how Cucumber works
-
-* specifications are written in the https://github.com/cucumber/cucumber/wiki/Gherkin[Gherkin] DSL, following the https://github.com/cucumber/cucumber/wiki/Given-When-Then["given/when/then"] format.
-
-* Cucumber-JVM itself is a JUnit runner, and searches for https://github.com/cucumber/cucumber/wiki/Feature-Introduction[feature files] on the classpath.
-
-* These in turn are matched to link:https://github.com/cucumber/cucumber/wiki/Step-Definitions[step definition]s through regular expressions. +
-+
-It is the step definitions (the "glue") that exercise the system.
-
-The code that goes in step definitions is broadly the same as the code that goes in an integration test method. One benefit of using step definitions (rather than integration tests) is that the step definitions are reusable across scenarios, so there may be less code overall to maintain. For example, if you have a step definition that maps to "given an uncompleted todo item", then this can be used for all the scenarios that start with that as their precondition.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_key-classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_key-classes.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_key-classes.adoc
deleted file mode 100644
index 1a44cf2..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_key-classes.adoc
+++ /dev/null
@@ -1,59 +0,0 @@
-[[_ugtst_bdd-spec-support_key-classes]]
-= Key classes
-: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/
-
-
-
-
-There are some key framework classes that make up the spec support; these are discussed below.
-
-NOTE: some of these are also used by Apache Isis' xref:ugtst.adoc#_ugtst_integ-test-support[Integration Test support].
-
-
-
-
-== `IsisSystemForTest`
-
-The `IsisSystemForTest` class allows a complete running instance of Apache Isis to be bootstrapped (with the JDO objectstore); this is then held on a a `ThreadLocal` from one test to another.
-
-Typically bootstrapping code is used to lazily instantiate the `IsisSystemForTest` once and once only. The mechanism for doing this is line-for-line identical in both BDD step defs and integration tests.
-
-
-
-
-== `ScenarioExecution`
-
-The `ScenarioExecution` provides a context for a scenario that is being executed. It is Cucumber that determines which step definitions are run, and in which order, and so state cannot be passed between step definitions using local variables or instance variables. Instead the `ScenarioExecution` acts like a hashmap, allowing each step to put data (eg "given an uncompleted todoitem") into the map or get data ("when I complete the todoitem") from the map. This is done using the `putVar(...)` and `getVar(...)` methods.
-
-[TIP]
-====
-This corresponds broadly to the "World" object in Ruby-flavoured Cucumber.
-====
-
-The `ScenarioExecution` also provids access to the configured domain services (using the `service(...)` method) and the `DomainObjectContainer` (through the `container()` method).
-
-[NOTE]
-====
-This could probably be refactored; Cucumber JVM provides automatic dependency injection into setp definitions, but Apache Isis does not currently leverage or exploit this capability.
-====
-
-Like the `IsisSystemForTest` class, the `ScenarioExecution` class binds an instance of itself onto a `ThreadLocal`. It can then be accessed in BDD step definitions using `ScenarioExecution.current()` static method.
-
-
-
-== `WrapperFactory`
-
-As with integration tests, the UI can be simulated by "wrapping" each domain object in a proxy using the `WrapperFactory`.
-
-
-
-
-== `CukeGlueAbstract`
-
-The `CukeGlueAbstract` acts as a convenience superclass for writing BDD step definitions (analogous to the `IntegrationTestAbstract` for integation tests). Underneath the covers it delegates to an underlying `ScenarioExecution`.
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_maven-configuration.adoc
deleted file mode 100644
index 13bc26b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_maven-configuration.adoc
+++ /dev/null
@@ -1,73 +0,0 @@
-[[_ugtst_bdd-spec-support_maven-configuration]]
-= Maven Configuration
-: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' BDD spec support is automatically configured if you use the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]. To set it up manually, update the `pom.xml` of your domain object model module:
-
-[source,xml]
-----
-<dependency>
- <groupId>org.apache.isis.core</groupId>
- <artifactId>isis-core-specsupport</artifactId>
- <scope>test</scope> // <1>
-</dependency>
-----
-<1> Normally `test`; usual Maven scoping rules apply.
-
-
-We also recommend that you configure the `maven-surefire-plugin` to pick up the following class patterns:
-
-
-[source,xml]
-----
-<plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-surefire-plugin</artifactId>
- <version>2.10</version>
- <configuration>
- <includes>
- <include>**/*Test.java</include>
- <include>**/*Test_*.java</include>
- <include>**/*Spec*.java</include>
- </includes>
- <excludes>
- <exclude>**/Test*.java</exclude>
- <exclude>**/*ForTesting.java</exclude>
- <exclude>**/*Abstract*.java</exclude>
- </excludes>
- <useFile>true</useFile>
- <printSummary>true</printSummary>
- <outputDirectory>${project.build.directory}/surefire-reports</outputDirectory>
- </configuration>
-</plugin>
-----
-
-
-You may also find it more convenient to place the `.feature` files in `src/test/java`, rather than `src/test/resources`. If you wish to do this, then your integtest module's `pom.xml` must contain:
-
-[source,xml]
-----
-<build>
- <testResources>
- <testResource>
- <filtering>false</filtering>
- <directory>src/test/resources</directory>
- </testResource>
- <testResource>
- <filtering>false</filtering>
- <directory>src/test/java</directory>
- <includes>
- <include>**</include>
- </includes>
- <excludes>
- <exclude>**/*.java</exclude>
- </excludes>
- </testResource>
- </testResources>
-</build>
-----
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc
deleted file mode 100644
index d8a730e..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc
+++ /dev/null
@@ -1,141 +0,0 @@
-[[_ugtst_bdd-spec-support_writing-a-bdd-spec]]
-= Writing a BDD spec
-: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/
-
-
-
-
-BDD specifications contain:
-
-* a `XxxSpec.feature` file, describing the feature and the scenarios (given/when/then)s that constitute its acceptance criteria
-
-* a `RunSpecs.java` class file to run the specification (all boilerplate). This will run all `.feature` files in the same package or subpackages.
-
-* one or several `XxxGlue` constituting the step definitions to be matched against. +
-+
-The "glue" (step definitions) are intended to be reused across features. We therefore recommend that they reside in a separate package, and are organized by the entity type upon which they act. +
-+
-For example, given a feature that involves `Customer` and `Order`, have the step definitions pertaining to `Customer` reside in `CustomerGlue`, and the step definitions pertaining to `Order` reside in `OrderGlue`. +
-+
-The `glue` attribute of the Cucumber-JVM JUnit runner eallows you to indicate which package(s) should be recursively searched to find any glue.
-
-* a system initializer class. You can reuse the system initializer from any integration tests (as described in xref:ugtst.adoc#_ugtst_integ-test-support[Integration Test Support], bootstrapping section).
-
-
-Here's an example of a feature from the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
-
-[source,java]
-----
-@SimpleObjectsFixture
-Feature: List and Create New Simple Objects
-
- @integration
- Scenario: Existing simple objects can be listed and new ones created
- Given there are initially 3 simple objects
- When I create a new simple object
- Then there are 4 simple objects
-----
-
-The `@SimpleObjectsFixture` is a custom tag we've specified to indicate the prerequisite fixtures to be loaded; more on this in a moment. The `@integration` tag, meanwhile, says that this feature should be run with integration-level scope.
-
-
-[NOTE]
-====
-Although BDD specs are most commonly used for end-to-end tests (ie at the same scope as an integration test), the two concerns (expressability of a test to a business person vs granularity of the test) should not be conflated. There are a couple of http://silkandspinach.net/2013/01/18/a-testing-strategy/[good] blog http://claysnow.co.uk/the-testing-iceberg/[posts] discussing http://claysnow.co.uk/living-documentation-can-be-readable-and-fast/[this]. The basic idea is to avoid the overhead of a heavy-duty integration test if possible.
-
-Apache Isis does also support running BDD specs in unit test mode; by annotating the scenario with the `@unit` (rather than `@integration` tag). When running under unit-level scope, the Apache Isis system is _not_ instantiated. Instead, the `ScenarioExecution` class returns JMock mocks (except for the `WrapperFactory`, if configured).
-
-To support unit testing scope Apache Isis provides the `InMemoryDB` class; a glorified hashmap of "persisted" objects. Use of this utility class is optional.
-
-Writing a BDD spec that supports both modes of operation therefore takes more effort and we expect most users interested in BDD will use integration-testing scope; for these reasons we have chosen _not_ to include unit-testing support in the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]. For those who do require faster-executing test suite, it's worthwhile knowing that Apache Isis can support this.
-
-====
-
-
-The `RunSpecs` class to run this feature (and any other features in this package or subpackages) is just boilerplate
-
-[source,java]
-----
-@RunWith(Cucumber.class)
-@CucumberOptions(
- format = {
- "html:target/cucumber-html-report"
- ,"json:target/cucumber.json"
- },
- glue={"classpath:domainapp.integtests.specglue"},
- strict = true,
- tags = { "~@backlog", "~@ignore" })
-public class RunSpecs {
- // intentionally empty
-}
-----
-
-The JSON formatter allows integration with enhanced reports, for example as provided by http://www.masterthought.net/section/cucumber-reporting[Masterthought.net] (screenshots at end of page). (Commented out) configuration for this is provided in the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
-
-The bootstrapping of Apache Isis can be moved into a `BootstrappingGlue` step definition:
-
-[source,java]
-----
-public class BootstrappingGlue extends CukeGlueAbstract {
- @Before(value={"@integration"}, order=100)
- public void beforeScenarioIntegrationScope() {
- org.apache.log4j.PropertyConfigurator.configure("logging.properties");
- SimpleAppSystemInitializer.initIsft();
-
- before(ScenarioExecutionScope.INTEGRATION);
- }
- @After
- public void afterScenario(cucumber.api.Scenario sc) {
- assertMocksSatisfied();
- after(sc);
- }
-}
-----
-
-The fixture to run also lives in its own step definition, https://github.com/apache/isis/blob/07fe61ef3fb029ae36427f60da2afeeb931e4f88/example/application/simpleapp/integtests/src/test/java/domainapp/integtests/specglue/CatalogOfFixturesGlue.java#L24[`CatalogOfFixturesGlue`]:
-
-[source,java]
-----
-public class CatalogOfFixturesGlue extends CukeGlueAbstract {
- @Before(value={"@integration", "@SimpleObjectsFixture"}, order=20000)
- public void integrationFixtures() throws Throwable {
- scenarioExecution().install(new RecreateSimpleObjects());
- }
-}
-----
-
-Note that this is annotated with a tag (`@SimpleObjectsFixture`) so that the correct fixture runs. (We might have a whole variety of these).
-
-The step definitions pertaining to `SimpleObject` domain entity then reside in the https://github.com/apache/isis/blob/07fe61ef3fb029ae36427f60da2afeeb931e4f88/example/application/simpleapp/integtests/src/test/java/domainapp/integtests/specglue/modules/simple/SimpleObjectGlue.java#L31[`SimpleObjectGlue`] class. This is where the heavy lifting gets done:
-
-[source,java]
-----
-public class SimpleObjectGlue extends CukeGlueAbstract {
- @Given("^there are.* (\\d+) simple objects$")
- public void there_are_N_simple_objects(int n) throws Throwable {
- try {
- final List<SimpleObject> findAll = service(SimpleObjects.class).listAll();
- assertThat(findAll.size(), is(n));
- putVar("list", "all", findAll);
-
- } finally {
- assertMocksSatisfied();
- }
- }
- @When("^I create a new simple object$")
- public void I_create_a_new_simple_object() throws Throwable {
- service(SimpleObjects.class).create(UUID.randomUUID().toString());
- }
-}
-----
-
-[TIP]
-====
-If using Java 8, note that Cucumber JVM supports a link:https://cucumber.io/docs/reference/jvm#java-8-lambdas[simplified syntax using lambdas].
-====
-
-
-
-