svn commit: r1481020 - in /jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak: security/principal/PrincipalConfigurationImpl.java spi/security/principal/PrincipalConfiguration.java

[an...@apache.org]

Author: angela
Date: Fri May 10 14:17:14 2013
New Revision: 1481020

URL: http://svn.apache.org/r1481020
Log:
OAK-90 : Implement Principal Management (javadoc)

Modified:
    jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/security/principal/PrincipalConfigurationImpl.java
    jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/principal/PrincipalConfiguration.java

Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/security/principal/PrincipalConfigurationImpl.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/security/principal/PrincipalConfigurationImpl.java?rev=1481020&r1=1481019&r2=1481020&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/security/principal/PrincipalConfigurationImpl.java (original)
+++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/security/principal/PrincipalConfigurationImpl.java Fri May 10 14:17:14 2013
@@ -27,7 +27,7 @@ import org.apache.jackrabbit.oak.spi.sec
 import org.apache.jackrabbit.oak.spi.security.principal.PrincipalProvider;
 
 /**
- * PrincipalConfigurationImpl... TODO
+ * Default implementation of the {@code PrincipalConfiguration}
  */
 public class PrincipalConfigurationImpl extends SecurityConfiguration.Default implements PrincipalConfiguration {
 

Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/principal/PrincipalConfiguration.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/principal/PrincipalConfiguration.java?rev=1481020&r1=1481019&r2=1481020&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/principal/PrincipalConfiguration.java (original)
+++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/principal/PrincipalConfiguration.java Fri May 10 14:17:14 2013
@@ -24,13 +24,48 @@ import org.apache.jackrabbit.oak.namepat
 import org.apache.jackrabbit.oak.spi.security.SecurityConfiguration;
 
 /**
- * PrincipalConfig... TODO
+ * Configuration interface for principal management.
  */
 public interface PrincipalConfiguration extends SecurityConfiguration {
 
+    /**
+     * Returns an instance of {@link PrincipalManager} that can be used
+     * to query and retrieve principals such as needed for JCR access control
+     * management.
+     *
+     * @param root The target root.
+     * @param namePathMapper The {@code NamePathMapper} to be used.
+     * @return An instance of {@link PrincipalManager}.
+     * @see {@link org.apache.jackrabbit.api.JackrabbitSession#getPrincipalManager()}
+     */
     @Nonnull
     PrincipalManager getPrincipalManager(Root root, NamePathMapper namePathMapper);
 
+    /**
+     * Returns an instance of the OAK {@link PrincipalProvider}.
+     *
+     * <h3>Backwards compatibility with Jackrabbit 2.x</h3>
+     * <h4>Configuration of Principal Providers</h4>
+     * In Jackrabbit 2.x the configuration of principal providers was tied to
+     * the LoginModule configuration and thus mixing authentication concerns
+     * with the principal management. Since OAK makes the {@code PrincipalProvider}
+     * a public interface of the SPI, it's configuration goes along with the
+     * configuration of the JCR level {@link PrincipalManager}. The authentication
+     * setup may have access to the principal configuration if the
+     * {@link org.apache.jackrabbit.oak.spi.security.SecurityProvider} is
+     * made available in the {@link org.apache.jackrabbit.oak.spi.security.authentication.AuthenticationConfiguration}.
+     *
+     * <h4>Multiple Sources for Principals</h4>
+     * In Jackrabbit 2.x it was possible to configure multiple principal providers.
+     * As of OAK there is only one single principal provider implementation
+     * responsible for a given workspace. If principals originate from different
+     * sources it is recommended to use the {@link CompositePrincipalProvider}
+     * to combine the different sources.
+     *
+     * @param root The target {@code Root}.
+     * @param namePathMapper The {@code NamePathMapper} to be used.
+     * @return An instance of {@link PrincipalProvider}.
+     */
     @Nonnull
     PrincipalProvider getPrincipalProvider(Root root, NamePathMapper namePathMapper);
 }
\ No newline at end of file