svn commit: r1650191 - in /isis/site/trunk/content: documentation.md reference/services/images/user-profile-service.png reference/services/user-profile-service.md

[da...@apache.org]

Author: danhaywood
Date: Wed Jan  7 22:52:53 2015
New Revision: 1650191

URL: http://svn.apache.org/r1650191
Log:
user profile service

Added:
    isis/site/trunk/content/reference/services/images/user-profile-service.png   (with props)
    isis/site/trunk/content/reference/services/user-profile-service.md
      - copied, changed from r1650005, isis/site/trunk/content/reference/services/user-registration-service.md
Modified:
    isis/site/trunk/content/documentation.md

Modified: isis/site/trunk/content/documentation.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/documentation.md?rev=1650191&r1=1650190&r2=1650191&view=diff
==============================================================================
--- isis/site/trunk/content/documentation.md (original)
+++ isis/site/trunk/content/documentation.md Wed Jan  7 22:52:53 2015
@@ -417,8 +417,9 @@ Co-ordinate sharing of information acros
 
 * [Email Service](./reference/services/email-service.html) (1.8.0-SNAPSHOT)
 
-#### <a name="domain-services-user-registration">User Registration</a>
+#### <a name="domain-services-user-profile">User management</a>
 
+* [User Profile Service](./reference/services/user-profile-service.html) (API only)  (1.8.0-SNAPSHOT)
 * [User Registration Service](./reference/services/user-registration-service.html) (API only)  (1.8.0-SNAPSHOT)
 * [Email Notification Service](./reference/services/email-notification-service.html)  (1.8.0-SNAPSHOT)
 

Added: isis/site/trunk/content/reference/services/images/user-profile-service.png
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/reference/services/images/user-profile-service.png?rev=1650191&view=auto
==============================================================================
Binary file - no diff available.

Propchange: isis/site/trunk/content/reference/services/images/user-profile-service.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Copied: isis/site/trunk/content/reference/services/user-profile-service.md (from r1650005, isis/site/trunk/content/reference/services/user-registration-service.md)
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/reference/services/user-profile-service.md?p2=isis/site/trunk/content/reference/services/user-profile-service.md&p1=isis/site/trunk/content/reference/services/user-registration-service.md&r1=1650005&r2=1650191&rev=1650191&view=diff
==============================================================================
--- isis/site/trunk/content/reference/services/user-registration-service.md (original)
+++ isis/site/trunk/content/reference/services/user-profile-service.md Wed Jan  7 22:52:53 2015
@@ -1,53 +1,52 @@
-Title: User Registration Service (1.8.0-SNAPSHOT)
+Title: User Profile Service (1.8.0-SNAPSHOT)
 
-The user registration service API provides the ability for users to sign-up to access an application by providing a valid email address.  The Wicket viewer will check whether an implementation of this service (and also the [email notification service](./email-notification-service.html)) is available, and if so will (unless configured not to) expose a sign-up page where the user enters their email address.  A verification email is sent (using the aforementioned [email notification service](./email-notification-service.html)) which includes a link back to the running application; this allows the user then to complete their registration process (choose user name, password and so on).  When the user has provided the additional details, the Wicket viewer calls this service in order to create an account for them, and then logs the user on.
+The user profile service API provides the ability for the domain application to return supplementary metadata about
+the current user.  This information is used (by the Wicket viewer) to customize the appearance of the tertiary
+"Me" menu bar (top right).  For example, rather than display the username, instead the user's first and last name
+could be displayed.
 
-The user registration API also includes the ability to reset password, again by sending a verification email to the provided email address.
+Another use case is to allow the user to switch context in some fashion or other.  This might be to emulate a
+sort of "sudo"-like function, or perhaps to focus on some particular set of data.
 
-See [here](../../components/viewers/wicket/user-registration.html) for more on the Wicket viewer's support.
-
-Domain objects may also use this service; it will be injected into domain object or other domain services in the usual way.  (That said, we expect that such use cases will be comparatively rare; the primary use case is for the Wicket viewer's sign-up page).
-
-The core Isis framework itself defines only an API; there is no default implementation.  Rather, the implementation will depend on the security mechanism being used.  That said, if you have configured your app to use the [Isis addons security module](http://github.com/isisaddons/isis-module-security), then note that the security module does provide an implementation (`SecurityModuleAppUserRegistrationService`) of the user registration service.  This will be automatically registered if the security module is included on the classpath.
-
-Put another way: using the Isis addon security module will allow users to sign up and create their own account.
+> Currently this feature is not integrated with Isis' authentication mechanisms; the information provided is purely metadata provided for presentation purposes only.
 
 ## API
-
+
 The API for the service is:
 
-    public interface UserRegistrationService {
+    public interface UserProfileService {
 
         @Programmatic
-        boolean usernameExists(String username);
+        String userProfileName();
+    }
 
-        @Programmatic
-        boolean emailExists(String emailAddress);
+where:
 
-        @Programmatic
-        void registerUser(String username, String password, String emailAddress);
+* `userProfileName()` is used (in the Wicket viewer) as the menu name of the tertiary "Me" menu bar.
 
-        @Programmatic
-        boolean updatePasswordByEmail(String emailAddress, String password);
-    }
+If the method returns <tt>null</tt> or throws an exception then the framework will default to using the current user name.
 
-where:
+> In the future this API may be expanded; one obvious possibility is to return a profile photo or avatar URL.
 
-* `usernameExists()` checks if there is already a user with the specified username
-* `emailExists()` checks if there is already a user with the specified email address
-* `registerUser(...)` creates the user, with specified password and email address.  The username nor email address must be unique (not being used by an existing user)
-* `updatePasswordByEmail()` allows the user to reset their password
-      
-## Implementation
+## Screenshot
 
-There is no default implementation of the service provided by the core framework.  However, the [Isis addons security module](http://github.com/isisaddons/isis-module-security), provides an implementation which is automatically available if the security module is on the classpath.
+The [todoapp](../../intro/getting-started/todoapp-archetype.html) provides a custom implementation that demonstrates the
+use of this service:
 
-## Related Services
+![](images/user-profile-service.png)
 
-The most common use case is to allow users to sign-up through Isis' Wicket viewer.  Because the process requires email to be sent, the following services must be configured:
+The implementation is very straight-forward:
 
-* `EmailService` (as described [here](./email-service.html)).
-* `EmailNotificationService` (as described [here](./email-notification-service.html)).
-* `UserRegistrationService` (this service)
+    @DomainService
+    public class CustomUserProfileService implements UserProfileService {
 
-The `EmailService` in particular requires additional configuration properties to specify the external SMTP service.
+        @Override
+        @Programmatic
+        public String userProfileName() {
+            return "Hi " + getAuthenticationSession().getUserName() + "!";
+        }
+
+        protected AuthenticationSession getAuthenticationSession() {
+            return IsisContext.getAuthenticationSession();
+        }
+    }