svn commit: r1306782 - in /jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api: AuthInfo.java Connection.java RepositoryService.java

[md...@apache.org]

Author: mduerig
Date: Thu Mar 29 10:45:21 2012
New Revision: 1306782

URL: http://svn.apache.org/viewvc?rev=1306782&view=rev
Log:
OAK-18: Define Oak API
javadoc

Modified:
    jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/AuthInfo.java
    jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/Connection.java
    jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/RepositoryService.java

Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/AuthInfo.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/AuthInfo.java?rev=1306782&r1=1306781&r2=1306782&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/AuthInfo.java (original)
+++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/AuthInfo.java Thu Mar 29 10:45:21 2012
@@ -17,7 +17,9 @@
 package org.apache.jackrabbit.oak.api;
 
 /**
- * The {@code AuthInfo} TODO... used for identification, authorization....
+ * {@code AuthInfo} instances provide access to information related
+ * to authentication and authorization of a given connection.
+ * {@code AuthInfo} instances are guaranteed to be immutable.
  */
 public interface AuthInfo {
 

Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/Connection.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/Connection.java?rev=1306782&r1=1306781&r2=1306782&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/Connection.java (original)
+++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/Connection.java Thu Mar 29 10:45:21 2012
@@ -30,13 +30,30 @@ import java.io.Closeable;
  * - validate information being written back to the persistent layer. this includes
  *   permission evaluation, node type and name constraints etc.
  *
- * - update the revision ID a given session is operating on.
+ * - update the revision ID a given session is operating on when certain actions
+ *   take place (save, refresh, TBD)
+ *
+ * - Provide access to authentication and authorization related information
+ *
+ * - Connection instances are not thread safe.
+ *
+ * - The implementation of this and all related interfaces are intended to only
+ *   hold the state of the persistent layer at a given revision without any
+ *   session-related state modifications.
  *
  * TODO: define whether this is a repository-level connection or just bound to a single workspace.
  * TODO: describe how this interface is intended to handle validation: nt, names, ac, constraints...
  */
 public interface Connection extends Closeable {
 
+    /**
+     * This methods provides access to information related to authentication
+     * and authorization of this connection. Multiple calls to this method
+     * may return different instances which are guaranteed to be equal wrt.
+     * to {@link Object#equals(Object)}.
+     *
+     * @return  immutable {@link AuthInfo} instance
+     */
     AuthInfo getAuthInfo();
 
     /**

Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/RepositoryService.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/RepositoryService.java?rev=1306782&r1=1306781&r2=1306782&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/RepositoryService.java (original)
+++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/RepositoryService.java Thu Mar 29 10:45:21 2012
@@ -20,17 +20,27 @@ import javax.jcr.NoSuchWorkspaceExceptio
 import javax.security.auth.login.LoginException;
 
 /**
- * TODO:
  * The {@code RepositoryService} is the main access point of the oak-api. It
  * serves the following purposes:
  *
- * - validating a given login request and providing a connection
- *   that is used for further communication with the persistent layer (MK).
- *
- * The implementation of this and all related interfaces are intended to only
- * hold the state of the persistent layer at a given revision without any
- * session-related state modifications.
+ * <ul>
+ * <li> validating a given login request and providing a {@link Connection}
+ *   that is used for further communication with the persistent layer (i.e.
+ *   Microkernel).</li>
+ * </ul>
  */
 public interface RepositoryService {
-    Connection login(Object credentials, String workspaceName) throws LoginException, NoSuchWorkspaceException;
+
+    /**
+     * Try to login a user identified by the passed {@code credentials}. On success
+     * this method returns a {@link Connection} to the given {@code workspace}.
+     *
+     * @param credentials
+     * @param workspaceName
+     * @return
+     * @throws LoginException
+     * @throws NoSuchWorkspaceException
+     */
+    Connection login(Object credentials, String workspaceName)
+            throws LoginException, NoSuchWorkspaceException;
 }
\ No newline at end of file