jackrabbit-oak-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ang...@apache.org
Subject svn commit: r1593500 - in /jackrabbit/oak/trunk/oak-doc/src/site/markdown/security: user.md user/authorizableaction.md
Date Fri, 09 May 2014 09:19:02 GMT
Author: angela
Date: Fri May  9 09:19:02 2014
New Revision: 1593500

URL: http://svn.apache.org/r1593500
Log:
OAK-301 : oak docu

Modified:
    jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user.md
    jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/authorizableaction.md

Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user.md?rev=1593500&r1=1593499&r2=1593500&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user.md Fri May  9 09:19:02 2014
@@ -20,13 +20,16 @@ User Management
 
 ### JCR User Management
 
-_todo_
+JCR itself doesn't come with a dedicated user management API. The only method
+related and ultemately used for user management tasks is `Session.getUserID()`.
+Therefore an API for user and group management has been defined as part of the
+extensions present with Jackrabbit API.
 
 ### Jackrabbit User Management API
 
 _todo_
 
-### Oak User Management
+### Oak User Management Implementation
 
 The default user management implementation stores user/group information in the
 content repository. In contrast to Jackrabbit 2.x, which by default used a single,
@@ -38,16 +41,14 @@ all actions with this editing session. T
 the alternative implementation present with Jackrabbit 2.x ((see Jackrabbit 2.x `UserPerWorkspaceUserManager`).
 
 #### General
+* The Oak implementation is build on the Oak API. This allows for double usage as
+  extension to the JCR API as well as within the Oak layer (aka SPI).
 * The `UserManager` is always associated with the same JCR workspace as the editing
   `Session` from which the class has been obtained.
 * Changes made to the user management API are always transient and require `Session#save()`
to be persisted.
-* In case of any failure during user management related write operations `Session#refresh`
-  is no longer called in order to prevent reverting other changes unrelated to
-  the user management operation. Tt's the responsibility of the API consumer to
-  specifically revert pending or invalid transient modifications.
-* The implementation is no longer built on top of the JCR API but instead directly
-  acts on `Tree` and `PropertyState` defined by the OAK API. This also allows to
-  make use of the Jackrabbit user management API within the OAK layer (aka SPI).
+* In case of any failure during user management related write operations the API
+  consumer is in charge of specifically revert pending or invalid transient modifications
+  or calling `Session#refresh(false)`.
 
 #### Differences wrt Jackrabbit 2.x
 
@@ -92,19 +93,17 @@ name [everyone] and corresponds to the `
 
 This special group always contains all Authorizable as member and cannot be edited
 with user management API. As of OAK this fact is consistently reflected in all
-group membership related methods.
-
-See also [Principal Management](principal.html).
+group membership related methods. See also [Principal Management](principal.html).
 
 #### Reading Authorizables
 
 ##### Handling of the Authorizable ID
-* As of OAK the node type definition of `rep:Authorizable` defines a new property `rep:authorizableId`
which is intended to store the ID of a user or group.
+* As of Oak the node type definition of `rep:Authorizable` defines a new property `rep:authorizableId`
which is intended to store the ID of a user or group.
 * The default implementation comes with a dedicated property index for `rep:authorizableId`
which asserts the uniqueness of that ID.
 * `Authorizable#getID` returns the string value contained in `rep:authorizableID` and for
backwards compatibility falls back on the node name in case the ID property is missing.
 * The name of the authorizable node is generated based on a configurable implementation of
the `AuthorizableNodeName` interface (see configuration section below). By default it uses
the ID as name hint and includes a conversion to a valid JCR node name.
 
-##### equals() and hashCode() for Authorizables
+##### equals() and hashCode()
 The implementation of `Object#equals()` and `Object#hashCode()` for user and
 groups slightly differs from Jackrabbit 2.x. It no longer relies on the _sameness_
 of the underlaying JCR node but only compares IDs and the user manager instance.
@@ -164,15 +163,13 @@ The following block lists the built-in n
       + * (rep:Members) = rep:Members protected multiple
       - * (WEAKREFERENCE) protected < 'rep:Authorizable'
 
+
 ### XML Import
-As of OAK 1.0 user and group nodes can be imported both with Session and Workspace
-import. The difference compare to Jackrabbit 2.x are listed below:
+As of Oak 1.0 user and group nodes can be imported both with Session and Workspace
+import. Other differences compared to Jackrabbit 2.x:
 
 * Importing an authorizable to another tree than the configured user/group node will only
failed upon save (-> see `UserValidator` during the `Root#commit`). With Jackrabbit 2.x
core it used to fail immediately.
-* NEW: The `BestEffort` behavior is now also implemented for the import of impersonators
(was missing in Jackrabbit /2.x).
-* NEW: Workspace Import
-
-
+* The `BestEffort` behavior is now also implemented for the import of impersonators (was
missing in Jackrabbit /2.x).
 
 ### API Extensions
 The Oak project introduces the following user management related public
@@ -181,19 +178,12 @@ interfaces and classes:
 #### Authorizable Actions
 
 The former internal Jackrabbit interface `AuthorizableAction` has been slightly
-adjusted to match OAK requirements and is now part of the public OAK SPI interfaces.
+adjusted to match Oak requirements and is now part of the public Oak SPI interfaces.
 In contrast to Jackrabbit-core the AuthorizableAction(s) now operate directly on
 the Oak API, which eases the handling of implementation specific tasks such as
 writing protected items.
 
-_todo_
-
-`org.apache.jackrabbit.oak.spi.security.user.action.*`
-
-- `AuthorizableAction`
-- `AuthorizableActionProvider`
-
-See also section [Authorizable Actions](user/authorizableaction.html) for further
+See section [Authorizable Actions](user/authorizableaction.html) for further
 details and examples.
 
 #### Node Name Generation

Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/authorizableaction.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/authorizableaction.md?rev=1593500&r1=1593499&r2=1593500&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/authorizableaction.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/authorizableaction.md Fri
May  9 09:19:02 2014
@@ -29,6 +29,25 @@ the Oak API, which eases the handling of
 writing protected items.
 
 
+### AuthorizableAction API
+
+The following public interfaces and base implementations are provided by Oak
+ in the package `org.apache.jackrabbit.oak.spi.security.user.action.*`:
+
+- [AuthorizableAction]
+- [AuthorizableActionProvider]
+- `AbstractAuthorizableAction`: abstract base implementation that doesn't perform any action.
+- `DefaultAuthorizableActionProvider`: default action provider service that allows to enable
the built-in actions provided with oak.
+
+Note that AuthorizableAction(s) operate directly on the Oak API, which eases the
+handling of implementation specific tasks such as e.g. writing protected items.
+
+The `AuthorizableAction` interface itself allows to perform validations or write
+addition application specific content while executing user management related
+write operations. The actions are consequently executed as part of the transient
+modifications and contrast to `org.apache.jackrabbit.oak.spi.commit.CommitHook`s
+that are triggered upon persisting content modifications.
+
 ### Default Actions
 
 The default implementations of the `AuthorizableAction` interface are present with
@@ -39,9 +58,9 @@ Oak 1.0:
 * `PasswordChangeAction`: verifies that the new password is different from the old one
 * `ClearMembershipAction`: clear group membership upon removal of an authorizable.
 
-As in jackrabbit core the actions are executed with the editing session and the target operation
will fail if any of the configured actions fails (e.g. due to insufficient permissions by
the editing OAK ContentSession).
-
-In order to match the OAK repository configuration setup and additional interface AuthorizableActionProvider
has been introduced. See section Configuration below.
+As in Jackrabbit 2.x the actions are executed with the editing session and the
+target operation will fail if any of the configured actions fails (e.g. due to
+insufficient permissions by the editing Oak ContentSession).
 
 
 ### Pluggability
@@ -51,11 +70,93 @@ _todo_
 
 #### Examples
 
-##### Custom Action Provider
-
-_todo_
-
-##### Custom Action
-
-_todo_
+##### Example Action Provider
 
+    @Component()
+    @Service(AuthorizableActionProvider.class)
+    public class MyAuthorizableActionProvider implements AuthorizableActionProvider {
+
+        private static final String PUBLIC_PROFILE_NAME = "publicProfileName";
+        private static final String PRIVATE_PROFILE_NAME = "privateProfileName";
+        private static final String FRIENDS_PROFILE_NAME = "friendsProfileName";
+
+        @Property(name = PUBLIC_PROFILE_NAME, value = "publicProfile")
+        private String publicName;
+
+        @Property(name = PRIVATE_PROFILE_NAME, value = "privateProfile")
+        private String privateName;
+
+        @Property(name = FRIENDS_PROFILE_NAME, value = "friendsProfile")
+        private String friendsName;
+
+        private ConfigurationParameters config = ConfigurationParameters.EMPTY;
+
+        public MyAuthorizableActionProvider() {}
+
+        public MyAuthorizableActionProvider(ConfigurationParameters config) {
+            this.config = config;
+        }
+
+        //-----------------------------------------< AuthorizableActionProvider >---
+        @Override
+        public List<? extends AuthorizableAction> getAuthorizableActions(SecurityProvider
securityProvider) {
+            AuthorizableAction action = new ProfileAction(publicName, privateName, friendsName);
+            action.init(securityProvider, config);
+            return Collections.singletonList(action);
+        }
+
+        //----------------------------------------------------< SCR Integration >---
+        @Activate
+        private void activate(Map<String, Object> properties) {
+            config = ConfigurationParameters.of(properties);
+        }
+    }
+
+##### Example Action
+
+This example action generates additional child nodes upon user/group creation
+that will later be used to store various target-specific profile information:
+
+    class ProfileAction extends AbstractAuthorizableAction {
+
+        private final String publicName;
+        private final String privateName;
+        private final String friendsName;
+
+        ProfileAction(@Nullable String publicName, @Nullable String privateName, @Nullable
String friendsName) {
+            this.publicName = publicName;
+            this.privateName = privateName;
+            this.friendsName = friendsName;
+        }
+
+        @Override
+        public void onCreate(Group group, Root root, NamePathMapper namePathMapper) throws
RepositoryException {
+            createProfileNodes(group.getPath(), root);
+        }
+
+        @Override
+        public void onCreate(User user, String password, Root root, NamePathMapper namePathMapper)
throws RepositoryException {
+            createProfileNodes(user.getPath(), root);
+        }
+
+        private void createProfileNodes(@Nonnull String authorizablePath, @Nonnull Root root)
throws AccessDeniedException {
+            Tree tree = root.getTree(authorizablePath);
+            if (tree.exists()) {
+                NodeUtil authorizableNode = new NodeUtil(tree);
+                if (publicName != null) {
+                    authorizableNode.addChild(publicName, NodeTypeConstants.NT_OAK_UNSTRUCTURED);
+                }
+                if (privateName != null) {
+                    authorizableNode.addChild(privateName, NodeTypeConstants.NT_OAK_UNSTRUCTURED);
+                }
+                if (friendsName != null) {
+                    authorizableNode.addChild(friendsName, NodeTypeConstants.NT_OAK_UNSTRUCTURED);
+                }
+            }
+        }
+
+
+
+<!-- hidden references -->
+[AuthorizableAction]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/user/action/AuthorizableAction.html
+[AuthorizableActionProvider]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/user/action/AuthorizableActionProvider.html



Mime
View raw message