svn commit: r1328604 - in /jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak: api/ContentRepository.java api/ContentSession.java core/ConnectionImpl.java

[ju...@apache.org]

Author: jukka
Date: Sat Apr 21 07:49:35 2012
New Revision: 1328604

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

Update javadocs about ContentSession.
Drop the getRepositoryConnection() method.

Modified:
    jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/ContentRepository.java
    jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/ContentSession.java
    jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/core/ConnectionImpl.java

Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/ContentRepository.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/ContentRepository.java?rev=1328604&r1=1328603&r2=1328604&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/ContentRepository.java (original)
+++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/ContentRepository.java Sat Apr 21 07:49:35 2012
@@ -32,6 +32,8 @@ import javax.security.auth.login.LoginEx
  * of each particular deployment and not covered by this interface.
  * Repository clients should use a deployment-specific mechanism (JNDI,
  * OSGi service, etc.) to acquire references to ContentRepository instances.
+ * <p>
+ * This interface is thread-safe.
  */
 public interface ContentRepository {
 
@@ -53,6 +55,19 @@ public interface ContentRepository {
      * TODO: Instead of the explicit access credentials, should this method
      * rather take the arguments to be passed to the relevant
      * JAAS {@link javax.security.auth.login.LoginContext} constructor?
+     * <p>
+     * The client should explicitly {@link ContentSession#close()} the
+     * returned session once it is no longer used. The recommended access
+     * pattern is:
+     * <pre>
+     * ContentRepository repository = ...;
+     * ContentSession session = repository.login(...);
+     * try {
+     *     ...; // Use the session
+     * } finally {
+     *     session.close();
+     * }
+     * </pre>
      *
      * @param credentials access credentials, or {@code null}
      * @param workspaceName

Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/ContentSession.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/ContentSession.java?rev=1328604&r1=1328603&r2=1328604&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/ContentSession.java (original)
+++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/ContentSession.java Sat Apr 21 07:49:35 2012
@@ -19,8 +19,9 @@ package org.apache.jackrabbit.oak.api;
 import java.io.Closeable;
 
 /**
- * The {@code Connection} interface ...
- *
+ * Authentication session for accessing (TODO: a workspace inside) a content
+ * repository.
+ * <p>
  * - retrieving information from persistent layer (MK) that are accessible to
  *   a given JCR session
  *
@@ -32,20 +33,14 @@ import java.io.Closeable;
  *
  * - 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.
- *
- * - Whether this connection is bound to a workspace or to the whole repository
- *   is determined by how the connection was acquired: connections acquired by
- *   {@link ContentRepository#login(Object, String)} are bound to the workspace
- *   passed to the login method. Connections acquired by
- *   {@link ContentSession#getRepositoryConnection()} are bound to the whole repository.
- *   TODO: check if that is really necessary, desirable and feasible.
- *
- * TODO: describe how this interface is intended to handle validation: nt, names, ac, constraints...
+ * <p>
+ * TODO: describe how this interface is intended to handle validation:
+ * nt, names, ac, constraints...
+ * <p>
+ * This interface is thread-safe.
  */
 public interface ContentSession extends Closeable {
 
@@ -71,15 +66,6 @@ public interface ContentSession extends 
     String getWorkspaceName();
 
     /**
-     * Provide access to the whole repository (i.e. all workspaces) respecting
-     * the access rights of the current connection. This method returns the
-     * same connection instance on every invocation.
-     *
-     * @return a {@code Connection} which covers the whole repository.
-     */
-    ContentSession getRepositoryConnection();
-
-    /**
      * Refresh this connection to the latest revision of the underlying Microkernel.
      */
     void refresh();

Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/core/ConnectionImpl.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/core/ConnectionImpl.java?rev=1328604&r1=1328603&r2=1328604&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/core/ConnectionImpl.java (original)
+++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/core/ConnectionImpl.java Sat Apr 21 07:49:35 2012
@@ -123,11 +123,6 @@ public class ConnectionImpl implements C
     }
 
     @Override
-    public ContentSession getRepositoryConnection() {
-        return new ConnectionImpl(credentials, null, store, store.getRoot(), queryEngine);
-    }
-
-    @Override
     public QueryEngine getQueryEngine() {
         return queryEngine;
     }