Repository: isis Updated Branches: refs/heads/master 3aaad83f5 -> 556a213f4
ISIS-1133: moving more stuff over to adocs (jdo/dn, shiro, restful) Project: http://git-wip-us.apache.org/repos/asf/isis/repo Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/556a213f Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/556a213f Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/556a213f Branch: refs/heads/master Commit: 556a213f444591948cbeba6dc9c1fec8c605cc30 Parents: 3aaad83 Author: Dan Haywood <[email protected]> Authored: Wed May 6 07:48:08 2015 +0100 Committer: Dan Haywood <[email protected]> Committed: Wed May 6 07:48:08 2015 +0100 ---------------------------------------------------------------------- .../user-guide/__/format-of-permissions.adoc | 84 ------- .../__/simplified-object-representation.adoc | 71 ++++++ ...ressing-elements-of-the-representations.adoc | 54 +++++ .../user-guide/__/using-chrome-tools.adoc | 5 + .../main/asciidoc/user-guide/__/using-ldap.adoc | 133 ----------- ...r-guide_configuration_configuring-shiro.adoc | 57 ++--- .../user-guide/_user-guide_extending.adoc | 18 +- ...r-guide_extending_restfulobjects-viewer.adoc | 120 ++++++++++ .../_user-guide_extending_wicket-viewer.adoc | 39 ++++ .../_user-guide_isis-addons-modules.adoc | 115 ++++++++++ .../user-guide/_user-guide_isis-addons.adoc | 44 ---- .../_user-guide_restful-objects-viewer.adoc | 220 +++++++++++++++++-- .../action-invocation-published-to-stderr.png | Bin 0 -> 22377 bytes .../changed-object-published-to-stderr.png | Bin 0 -> 16645 bytes .../main/asciidoc/user-guide/user-guide.adoc | 2 +- 15 files changed, 638 insertions(+), 324 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/isis/blob/556a213f/adocs/documentation/src/main/asciidoc/user-guide/__/format-of-permissions.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/__/format-of-permissions.adoc b/adocs/documentation/src/main/asciidoc/user-guide/__/format-of-permissions.adoc deleted file mode 100644 index 193bbd5..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/__/format-of-permissions.adoc +++ /dev/null @@ -1,84 +0,0 @@ -Title: Format of Permissions - -Shiro converts permission strings (as found in `WEB-INF/shiro.ini`) internally into `Permission` instances. - -The default implementation converts these strings to `WildcardPermission` instances, which allows permissions to be organized hierarchical and with wildcarding. - -Shiro also allows the conversion to be mapped to alternative `Permission` instances; Isis provides its own `IsisPermission` which provides an extended and more flexible syntax. - -== Using the Shiro Default Permission Syntax - -The default syntax for permissions is: - -[source] ----- -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) - -Because these are wildcards, a '*' can be used at any level. Additionally, missing levels assume wildcards. - -Thus: - -[source] ----- -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 ----- - -== Using the Enhanced Isis Permission Syntax - -Isis defines its own extended syntax for permissions, following the format: - -[source] ----- -([!]?)([^/]+)[/](.+) ----- - -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] ----- -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 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`. - -To tell Shiro to use the Isis permission format, add the following to `shiro.ini`: - -[source] ----- -permissionResolver = org.apache.isis.security.shiro.authorization.IsisPermissionResolver -xxxRealm.permissionResolver = $permissionResolver ----- - -where `xxxRealm` is the realm to be configured. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/isis/blob/556a213f/adocs/documentation/src/main/asciidoc/user-guide/__/simplified-object-representation.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/__/simplified-object-representation.adoc b/adocs/documentation/src/main/asciidoc/user-guide/__/simplified-object-representation.adoc new file mode 100644 index 0000000..0780368 --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/user-guide/__/simplified-object-representation.adoc @@ -0,0 +1,71 @@ +Title: Simplified Object Representation + +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 link:suppressing-elements-of-the-representations.html[here], 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. + +== Global Configuration + +Configuring the Restful Objects viewer globally to generate the simple object representation is done using the +following property (typically added to `WEB-INF/viewer_restfulobjects.properties`): + +[source] +---- +isis.viewer.restfulobjects.objectPropertyValuesOnly=true +---- + +This generates a representation such as: + +[source] +---- +{ + "title" : "Buy milk due by 2014-10-27", + "domainType" : "TODO", + "instanceId" : "L_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/L_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:L_0" + }, +} +---- + +== Per request + +This is not currently supported (though may be in the future). + +== See also + +Rather than returning a completely different representation for objects, it is also possible to simply suppress certain elements; +see link:suppressing-elements-of-the-representation.html[here]. + +On the other hand, if complete control over all representations is required, see link:custom-representations.html[here]. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/isis/blob/556a213f/adocs/documentation/src/main/asciidoc/user-guide/__/suppressing-elements-of-the-representations.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/__/suppressing-elements-of-the-representations.adoc b/adocs/documentation/src/main/asciidoc/user-guide/__/suppressing-elements-of-the-representations.adoc new file mode 100644 index 0000000..1eae2d2 --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/user-guide/__/suppressing-elements-of-the-representations.adoc @@ -0,0 +1,54 @@ +Title: Suppressing Elements of the Representations + +____ + +Enabling these settings makes the representations non-standard with respect to the http://restfulobjects.org[Restful Object spec]. +In the future the spec may be updated to allow such extensions. + +____ + +{note +These configuration settings should be considered beta, and are likely to change in the future in response to emerging requirements +} + +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. + +== Global Configuration + +Suppressing of elements can be done using globally using the following properties (typically added to +`WEB-INF/viewer_restfulobjects.properties`): + +[source] +---- +isis.viewer.restfulobjects.suppressDescribedByLinks=true +isis.viewer.restfulobjects.suppressUpdateLink=true +isis.viewer.restfulobjects.suppressMemberId=true +isis.viewer.restfulobjects.suppressMemberLinks=true +isis.viewer.restfulobjects.suppressMemberExtensions=true +isis.viewer.restfulobjects.suppressMemberDisabledReason=true +---- + +where, respectively, these suppress: + +* "describedby" links (on all representations) +* "update" link (on object representation) +* "id" json-prop for object members (on object representation and member detail representations) +* "links" json-prop for object members (on the object representation and member detail representations) +* "extensions" json-prop for object members (on the object representation and member detail representations) +* "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. +==== + +== See also + +If even simpler representations (of objects) are required, see link:simplified-object-representation.html[here]. + +If complete control over all representations is required, see link:custom-representations.html[here]. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/isis/blob/556a213f/adocs/documentation/src/main/asciidoc/user-guide/__/using-chrome-tools.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/__/using-chrome-tools.adoc b/adocs/documentation/src/main/asciidoc/user-guide/__/using-chrome-tools.adoc new file mode 100644 index 0000000..83e55bb --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/user-guide/__/using-chrome-tools.adoc @@ -0,0 +1,5 @@ +Title: Interacting with the REST API using Chrome Plugins + +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. + +<iframe width="840" height="472" src="//www.youtube.com/embed/_-TOvVYWCHc" frameborder="0" allowfullscreen></iframe>) \ No newline at end of file http://git-wip-us.apache.org/repos/asf/isis/blob/556a213f/adocs/documentation/src/main/asciidoc/user-guide/__/using-ldap.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/__/using-ldap.adoc b/adocs/documentation/src/main/asciidoc/user-guide/__/using-ldap.adoc deleted file mode 100644 index 3bb27ff..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/__/using-ldap.adoc +++ /dev/null @@ -1,133 +0,0 @@ -Title: Using Shiro with an LDAP Server - -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. - -The configuration required in the `WEB-INF/shiro.ini` file is: - -[source] ----- -contextFactory = org.apache.isis.security.shiro.IsisLdapContextFactory -contextFactory.url = ldap://localhost:10389 -contextFactory.authenticationMechanism = CRAM-MD5 -contextFactory.systemAuthenticationMechanism = simple -contextFactory.systemUsername = uid=admin,ou=system -contextFactory.systemPassword = secret - -ldapRealm = org.apache.isis.security.shiro.IsisLdapRealm -ldapRealm.contextFactory = $contextFactory - -ldapRealm.searchBase = ou=groups,o=mojo -ldapRealm.groupObjectClass = groupOfUniqueNames -ldapRealm.uniqueMemberAttribute = uniqueMember -ldapRealm.uniqueMemberAttributeValueTemplate = uid={0} - -# optional mapping from physical groups to logical application roles -ldapRealm.rolesByGroup = \ - LDN_USERS: user_role,\ - NYK_USERS: user_role,\ - HKG_USERS: user_role,\ - GLOBAL_ADMIN: admin_role,\ - DEMOS: self-install_role - -ldapRealm.permissionsByRole=\ - user_role = *:ToDoItemsJdo:*:*,\ - *:ToDoItem:*:*; \ - self-install_role = *:ToDoItemsFixturesService:install:* ; \ - admin_role = * - -securityManager.realms = $ldapRealm ----- - -where: - -* user accounts are searched under `ou=system` -* users have, at minimum, a `uid` attribute and a password -* SASL (CRAM-MD5) authentication is used for this authentication -* the users credentials are used to verify their user/password -* groups are searched under `ou=groups,o=mojo` (where `mojo` is the company name) -* each group has an LDAP objectClass of `groupOfUniqueNames` -* each group has a vector attribute of `uniqueMember` -* each value of `uniqueMember` is in the form `uid=xxx`, with `xxx` being the uid of the user -* the group membership is looked up using the specified system user -* groups looked up from LDAP can be mapped to logical roles -* if no group-to-role mapping is provided, then the group names are used as role names with no translation - -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. - -=== Using a shared role/perms path - -As an alternative to injecting the `permissionsByRole` property, the role/permission mapping can alternatively be specified by injecting a resource path: - -[source] ----- -ldapRealm.resourcePath=classpath:webapp/myroles.ini ----- - -where `myroles.ini` is in `src/main/resources/webapp`, and takes the form: - -[source] ----- - [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 Configuration - -The screenshot below shows the ApacheDS using Apache Directory Studio. The setup here was initially base on http://krams915.blogspot.co.uk/2011/01/ldap-apache-directory-studio-basic.html[this tutorial]. However, user accounts have been moved to a separate node. - -==== Configure Mojo partition and nodes under Root - -Create a partition in order to hold the mojo node (holding the groups) - -image:resources/activeds-ldap-mojo-partition.png[ActiveDS LDAP Users] - -Create the `ou=groups,o=mojo` hierarchy - -image:resources/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 Isis connecting to LDAP using these credentials. - -image:resources/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:resources/activeds-ldap-users.png[ActiveDS LDAP Users] - -Configure the users into the groups. - -image:resources/activeds-ldap-groups.png[ActiveDS LDAP Users] - -== Shiro Realm Mappings - -When configuring role based permission mapping, there can only be one of these entries per realm: - -[source] ----- -realm.groupToRolesMappings = ... ----- - -and - -[source] ----- -realm.roleToPermissionsMappings = ... ----- - -This forces you to put everything on one line for each of the above. - -This is, unfortunately, a Shiro "feature". The only solution to this is to use '' to separate the mappings onto separate lines in the file so that it is at least maintainable. - -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. - -If you repeat the entries above then it's "last one wins". - -____ - -*Note* you can't use a [roles] section because that triggers Shiro to use the simple "INI" realm and not your defined realm (in most cases you are going to use an LDAP realm in an enterprise environment and the "simple" realm in Shiro isn't much use beyond prototyping work). - -____ \ No newline at end of file http://git-wip-us.apache.org/repos/asf/isis/blob/556a213f/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-shiro.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-shiro.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-shiro.adoc index 5bed961..7907707 100644 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-shiro.adoc +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-shiro.adoc @@ -214,28 +214,28 @@ The configuration required in the `WEB-INF/shiro.ini` file is: ---- contextFactory = org.apache.isis.security.shiro.IsisLdapContextFactory contextFactory.url = ldap://localhost:10389 -contextFactory.authenticationMechanism = CRAM-MD5 -contextFactory.systemAuthenticationMechanism = simple -contextFactory.systemUsername = uid=admin,ou=system +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 ldapRealm.contextFactory = $contextFactory -ldapRealm.searchBase = ou=groups,o=mojo -ldapRealm.groupObjectClass = groupOfUniqueNames -ldapRealm.uniqueMemberAttribute = uniqueMember +ldapRealm.searchBase = ou=groups,o=mojo # <3> +ldapRealm.groupObjectClass = groupOfUniqueNames # <4> +ldapRealm.uniqueMemberAttribute = uniqueMember # <5> ldapRealm.uniqueMemberAttributeValueTemplate = uid={0} # optional mapping from physical groups to logical application roles -ldapRealm.rolesByGroup = \ +ldapRealm.rolesByGroup = \ # <6> LDN_USERS: user_role,\ NYK_USERS: user_role,\ HKG_USERS: user_role,\ GLOBAL_ADMIN: admin_role,\ DEMOS: self-install_role -ldapRealm.permissionsByRole=\ +ldapRealm.permissionsByRole=\ # <7> user_role = *:ToDoItemsJdo:*:*,\ *:ToDoItem:*:*; \ self-install_role = *:ToDoItemsFixturesService:install:* ; \ @@ -243,20 +243,18 @@ ldapRealm.permissionsByRole=\ securityManager.realms = $ldapRealm ---- +<1> user accounts are searched using a dedicated service account +<2> SASL (CRAM-MD5) authentication is used for this authentication +<3> groups are searched under `ou=groups,o=mojo` (where `mojo` is the company name) +<4> each group has an LDAP objectClass of `groupOfUniqueNames` +<5> each group has a vector attribute of `uniqueMember` +<6> groups looked up from LDAP can optionally be mapped to logical roles; otherwise groups are used as role names directly +<7> roles are mapped in turn to permissions -where: - -* user accounts are searched under `ou=system` +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 -* SASL (CRAM-MD5) authentication is used for this authentication * the users credentials are used to verify their user/password -* groups are searched under `ou=groups,o=mojo` (where `mojo` is the company name) -* each group has an LDAP objectClass of `groupOfUniqueNames` -* each group has a vector attribute of `uniqueMember` -* each value of `uniqueMember` is in the form `uid=xxx`, with `xxx` being the uid of the user -* the group membership is looked up using the specified system user -* groups looked up from LDAP can be mapped to logical roles -* if no group-to-role mapping is provided, then the group names are used as role names with no translation 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. @@ -330,27 +328,18 @@ realm.roleToPermissionsMappings = ... This forces you to put everything on one line for each of the above. -This is, unfortunately, a Shiro "feature". The only solution to this is to use '' to separate the mappings onto separate lines in the file so that it is at least maintainable. +This is, unfortunately, a Shiro "feature". The only solution to this is to use "\" to separate the mappings onto separate lines in the file so that it is at least maintainable. 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. If you repeat the entries above then it's "last one wins". -____ - -*Note* you can't use a [roles] section because that triggers Shiro to use the simple "INI" realm and not your defined realm (in most cases you are going to use an LDAP realm in an enterprise environment and the "simple" realm in Shiro isn't much use beyond prototyping work). - -____ - - - - - - - - - +[WARNING] +==== +Configuring a [roles] section instead doesn't work because that triggers Shiro to use the simple "INI" realm and not your defined realm. +In an enterprise environment you are most likely going to use either an LDAP realm or the realm that comes with the http://github.com/isisaddons/isis-module-security}[Isis addons' security] module (non-ASF); so the "simple" realm in Shiro isn't much use beyond prototyping work). +==== http://git-wip-us.apache.org/repos/asf/isis/blob/556a213f/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending.adoc index ac791b6..8f80ea4 100644 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending.adoc +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending.adoc @@ -3,23 +3,11 @@ :_basedir: ../ :_imagesdir: images/ -IMPORTANT: TODO +This chapter explains the main APIs for extending Apache Isis: the programming model conventions, the Wicket viewer, and the Restful Objects viewer. include::_user-guide_extending_programming-model.adoc[leveloffset=+1] +include::_user-guide_extending_wicket-viewer.adoc[leveloffset=+1] +include::_user-guide_extending_restfulobjects-viewer.adoc[leveloffset=+1] -## Extending the Wicket viewer - -### Writing a custom theme - -### Replacing page elements - -### Custom pages - - - - -## Extending the Restful viewer - -### Custom Representations \ No newline at end of file http://git-wip-us.apache.org/repos/asf/isis/blob/556a213f/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_restfulobjects-viewer.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_restfulobjects-viewer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_restfulobjects-viewer.adoc new file mode 100644 index 0000000..1cb2164 --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_restfulobjects-viewer.adoc @@ -0,0 +1,120 @@ += Extending the Restful 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/ + + +The Restful Objects viewer implements the http://restfulobjects.org[Restful Object spec], meaning that it: + +* defines a well-defined set of endpoint URLs as resources +* generates a well-defined set of (JSON) representations when these resources are accessed. + +There are, however, a number of other "standards" for defining representations, among these: + +* http://stateless.co/hal_specification.html[HAL] (Mike Kelly) +* http://amundsen.com/media-types/collection/[Collection+JSON] (Mike Amundsen) +* https://github.com/kevinswiber/siren[Siren] (Kevin Swiber) +* http://jsonapi.org/[JSON API] (Steve Klabnik) +* https://github.com/cainus/hyper-json-spec[Hyper+JSON] (Gregg Cainus) +* https://www.w3.org/TR/json-ld/[JSON-LD] (W3C) +* http://www.markus-lanthaler.com/hydra/[Hydra] (Markus Lanthaler) + +A good discussion about the relative merits of several of these different hypermedia formats can be found https://groups.google.com/forum/#!msg/api-craft/NgjzQYVOE4s/EAB2jxtU_TMJ[here]. + +While Isis' Restful Objects viewer only has "out-of-the-box" support for the representations defined in the Restful Objects spec, +it is possible to plugin a custom representation generator that can produce any arbitrary representation. + +[TIP] +==== +If all that is required is a very simple representations (of objects), you can instead reconfigure RO viewer to provide a simplified output, as described <<_simplified_object_representation, here>>. Or, it is also possible to simply suppress certain elements, as described <<_suppressing_elements_of_the_representations, here>>. +==== + + +== API + +The API to implement is the `RepresentationService` API: + +[WARNING] +==== +This API should be considered beta, as it may change in the future in response to emerging requirements +==== + +[source,java] +---- +import javax.ws.rs.core.Response; +import org.apache.isis.applib.annotation.Programmatic; +import org.apache.isis.core.metamodel.adapter.ObjectAdapter; +import org.apache.isis.viewer.restfulobjects.rendering.RendererContext; +import org.apache.isis.viewer.restfulobjects.rendering.domainobjects.*; + +public interface RepresentationService { + + @Programmatic + Response objectRepresentation( + Context rendererContext, + ObjectAdapter objectAdapter); + + @Programmatic + Response propertyDetails( + Context rendererContext, + ObjectAndProperty objectAndProperty, + MemberReprMode memberReprMode); + + @Programmatic + Response collectionDetails( + Context rendererContext, + ObjectAndCollection objectAndCollection, + MemberReprMode memberReprMode); + + @Programmatic + Response actionPrompt( + Context rendererContext, + ObjectAndAction objectAndAction); + + @Programmatic + Response actionResult( + Context rendererContext, + ObjectAndActionInvocation objectAndActionInvocation, + ActionResultReprRenderer.SelfLink selfLink); + + public static interface Context extends RendererContext { + ObjectAdapterLinkTo getAdapterLinkTo(); + } +} +---- + + +== Default Implementation + +Restful Objects' out-of-the-box support for Restful Objects spec uses this same API, specifically `RepresentationServiceForRestfulObjects` (in the `org.apache.isis.viewer.restfulobjects.rendering.service` package). + +Each of these methods provides: + +* a `RendererContext` + ++ +providing 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` + + +== Configuring your Implementation + +Implement the service and register in `WEB-INF/isis.properties`, eg: + +[source,ini] +---- +isis.services=...,\ + com.mycompany.myservice.RepresentationServiceForMyRestApi, + ... +---- + +This will replace the default implementatoin. + + + http://git-wip-us.apache.org/repos/asf/isis/blob/556a213f/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer.adoc new file mode 100644 index 0000000..51d75a3 --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer.adoc @@ -0,0 +1,39 @@ += Extending the Wicket 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/ + + +IMPORTANT: TODO + +== Writing a custom theme + +IMPORTANT: TODO + + + + +== Replacing page elements + +IMPORTANT: TODO + + + + +== Custom pages + +IMPORTANT: TODO + + + +== Isis Addons Extensions + +IMPORTANT: TODO + +[WARNING] +==== +Note that Isis addons, while maintained by Isis committers, are not part of the ASF. +==== + + + http://git-wip-us.apache.org/repos/asf/isis/blob/556a213f/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_isis-addons-modules.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_isis-addons-modules.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_isis-addons-modules.adoc new file mode 100644 index 0000000..7a90efe --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_isis-addons-modules.adoc @@ -0,0 +1,115 @@ += Isis Addons Modules (not ASF) +: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 http://isisaddons.org[Isis Addons] website provides a number of reusable modules and other extensions for Apache Isis. This chapter focuses just on the modules, all of which have a name of the form `isis-module-xxx`. + +[WARNING] +==== +Note that Isis addons, while maintained by Isis committers, are not part of the ASF. +==== + +The modules themselves fall into four broad groups: + +* modules that provide an implementations of API defined by Apache Isis + ++ +where Isis has hooks to use the service if defined by provides no implementations of its own. The http://github.com/isisaddons/isis-module-command}[command], http://github.com/isisaddons/isis-module-auditing}[auditing], http://github.com/isisaddons/isis-module-publishing}[publishing], http://github.com/isisaddons/isis-module-security}[security] and http://github.com/isisaddons/isis-module-sessionlogger}[sessionlogger] modules fall into this category. Typically the domain objects themselves wouldn't interact with these services + +* modules that provide standalone domain services with their own API and implementation + ++ +These are simply intended to be used by domain objects. The http://github.com/isisaddons/isis-module-docx}[docx], http://github.com/isisaddons/isis-module-excel}[excel], http://github.com/isisaddons/isis-module-settings}[settings] and http://github.com/isisaddons/isis-module-stringinterpolator}[stringinterpolator] fall into this category. + +* modules that provide standalone domain entities (and supporting services) for a particular subdomain + ++ +The http://github.com/isisaddons/isis-module-tags}[tags] module falls into this category + +* modules that provide developer utilities + ++ +Not intended for use by either the framework or domain objects, but provide utilities that the developer themselves might use. The http://github.com/isisaddons/isis-module-devutils}[devutils] module (not suprisingly) falls into this category + +Each of the modules has a full README and example application demonstrating their usage. The sections below briefly outline the capabilities of these modules. + +== Command Service (persistence) + +IMPORTANT: TODO + +=== API +=== Isis addons implementation + + + +== Background Command Service + +IMPORTANT: TODO + +=== API +=== Background Execution +=== Isis addons implementation + + + +== Auditing + +IMPORTANT: TODO + +=== Auditing API +=== Isis addons implementation + + + + +== Publishing Service + +IMPORTANT: TODO + +=== API +=== Isis addons implementation + + +=== Event Serializer + +Isis' PublishingService API also has a companion API, the `EventSerializer`. This provides a pluggable mechanism by which the event can be rendered into different formats. + +The http://github.com/isisaddons/isis-module-publishing}[Isis addons' publishing] module provides an implementation of this API -- `RestfulObjectsSpecEventSerializer` -- that reuses part of the implementation of the Restful Objects viewer to serialize the the provided `EventPayload` into the form specified by the http://restfulobjects.org[Restful Objects spec]. + +For example, this is the JSON generated on an action invocation: + +.JSON generated by action invocation +image::{_imagesdir}isis-addons-modules/action-invocation-published-to-stderr.png[width="750px"] + +while this is the object change JSON: + +.JSON generated by action invocation +image::{_imagesdir}isis-addons-modules/changed-object-published-to-stderr.png[width="750px"] + +You could if you wish change the representation by registering your own implementation of this API in `isis.properties`: + +[source,ini] +---- +isis.services=...\ + com.mycompany.myapp.MyEventSerializer,\ + ... +---- + + + +== Security + +IMPORTANT: TODO + + + +== Other Isis Addons + +IMPORTANT: TODO + +=== Developer Utilities +=== Docx Mail merge +=== Excel download/upload +=== Fake Data +=== Poly +=== Session Logger +=== Settings +=== String interpolator +=== Tags \ No newline at end of file http://git-wip-us.apache.org/repos/asf/isis/blob/556a213f/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_isis-addons.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_isis-addons.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_isis-addons.adoc deleted file mode 100644 index a3d780a..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_isis-addons.adoc +++ /dev/null @@ -1,44 +0,0 @@ -= Isis Addons (not ASF) -: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 - -WARNING: Note that Isis addons, while maintained by Isis committers, are not part of the ASF. - -## Command Service (persistence) - -### API -### Isis addons implementation (not ASF) - -## Background Command Service - -### API -### Background Execution -### Isis addons implementation (not ASF) - -## Auditing - -### Auditing API -### Isis addons implementation (not ASF) - - -## Publishing Service - -### API -### Isis addons implementation (not ASF) -### Event Serializer per RO Spec (out-of-date) - -## Other Isis Addons - -### Developer Utilities (not ASF) -### Docx Mail merge (not ASF) -### Excel download/upload (not ASF) -### Fake Data (not ASF) -### Poly (not ASF) -### Security (not ASF) -### Session Logger (not ASF) -### Settings (not ASF) -### String interpolator (not ASF) -### Tags (not ASF) \ No newline at end of file http://git-wip-us.apache.org/repos/asf/isis/blob/556a213f/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_restful-objects-viewer.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_restful-objects-viewer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_restful-objects-viewer.adoc index 02fcb2d..ad0146e 100644 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_restful-objects-viewer.adoc +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_restful-objects-viewer.adoc @@ -3,34 +3,228 @@ :_basedir: ../ :_imagesdir: images/ -IMPORTANT: TODO +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. -## Features +The Restful Objects viewer also provides a number of proprietary extensions. -### Restful Objects Specification +== Features -### Pretty printing +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 -## Configuration +The Restful Objects spec can be downloaded link:http://restfulobjects.org[here]. -### Honor UI hints +=== Pretty printing -### Suppressing elements of the representations +The JSON representations generated by the Restful Objects viewer are in compact form if the <<_deployment_types, deployment type>> is SERVER (ie production), but will automatically be "pretty printed" (in other words indented) if the deployment type is PROTOTYPE. -### Simplified object representation +== Configuration -## Extending the viewer +The Restful Objects viewer provides a number of configuration option that extend/simplify/alter the representations generated from the Restful Objects specification. -Discussed in <<Extending the Restful viewer>> +[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). +==== -## Hints and Tips +=== Honor UI hints + + +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. +==== + + +=== Suppressing elements of the representations + +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 and even simpler representations (of objects) are required, see <<_simplified_object_representation, Simplified object representation>>, below. + +If the above isn't flexible and you need complete control over all representations see the section on <<_extending_the_restful_viewer, Extending the Restful viewer>>. + + + +=== Simplified object representation + +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 <<_suppressing_elements_of_the_representations, 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" : "L_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/L_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:L_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 <<_extending_the_restful_viewer, Extending the Restful viewer>>. + + + +== Extending the viewer + +Discussed in <<_extending_the_restful_viewer, Extending the Restful viewer>>. + + + +== Hints and Tips + +=== 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. -### Using Chrome Tools -### AngularJS Tips \ No newline at end of file http://git-wip-us.apache.org/repos/asf/isis/blob/556a213f/adocs/documentation/src/main/asciidoc/user-guide/images/isis-addons-modules/action-invocation-published-to-stderr.png ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/isis-addons-modules/action-invocation-published-to-stderr.png b/adocs/documentation/src/main/asciidoc/user-guide/images/isis-addons-modules/action-invocation-published-to-stderr.png new file mode 100644 index 0000000..b0b3ca8 Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/user-guide/images/isis-addons-modules/action-invocation-published-to-stderr.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/556a213f/adocs/documentation/src/main/asciidoc/user-guide/images/isis-addons-modules/changed-object-published-to-stderr.png ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/isis-addons-modules/changed-object-published-to-stderr.png b/adocs/documentation/src/main/asciidoc/user-guide/images/isis-addons-modules/changed-object-published-to-stderr.png new file mode 100644 index 0000000..f894d8d Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/user-guide/images/isis-addons-modules/changed-object-published-to-stderr.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/556a213f/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc index e252a27..683f519 100644 --- a/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc +++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc @@ -26,7 +26,7 @@ include::_user-guide_configuration.adoc[leveloffset=+1] include::_user-guide_deployment.adoc[leveloffset=+1] -include::_user-guide_isis-addons.adoc[leveloffset=+1] +include::_user-guide_isis-addons-modules.adoc[leveloffset=+1] include::_user-guide_integrating-with-other-systems.adoc[leveloffset=+1]
