/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.jackrabbit.oak.api;

import javax.jcr.NoSuchWorkspaceException;
import javax.security.auth.login.LoginException;

/**
 * The {@code RepositoryService} is the main access point of the oak-api. It
 * serves the following purposes:
 *
 * <ul>
 * <li> validating a given login request and providing a {@link ContentSession}
 *   that is used for further communication with the persistent layer (i.e.
 *   Microkernel).</li>
 * </ul>
 */
public interface ContentRepository {

    /**
     * Try to login a user identified by the passed {@code credentials}. On success
     * this method returns a {@link ContentSession} to the given {@code workspace}.
     *
     * @param credentials
     * @param workspaceName
     * @return the connection
     * @throws LoginException
     * @throws NoSuchWorkspaceException
     */
    ContentSession login(Object credentials, String workspaceName)
            throws LoginException, NoSuchWorkspaceException;
}
@@ -940,566 +940,1750 @@
 %0A * 
-The %7B@code RepositoryService%7D is the main access point of the oak-api. It%0A * serves the following purposes:%0A *
+Oak content repository. The repository may local or remote, or a cluster%0A * of any size. These deployment details are all hidden behind this interface.
 %0A * %3C
-ul
+p
 %3E%0A * 
-%3Cli%3E validating a given login request and providing a %7B@link ContentSession%7D%0A *   that is used for further communication with the persistent layer (i.e.%0A *   Microkernel).%3C/li%3E%0A * %3C/ul%3E%0A */%0Apublic interface ContentRepository %7B%0A%0A    /**%0A     * Try to login a user identified by the passed %7B@code credentials%7D. On success%0A     * this method returns a %7B@link ContentSession%7D to the given %7B@code workspace%7D.%0A     *%0A     * @param credentials
+All access to the repository happens through authenticated%0A * %7B@link ContentSession%7D instances acquired through the%0A * %7B@link #login(Object, String)%7D method, which is why that is the only%0A * method of this interface.%0A * %3Cp%3E%0A * Starting and stopping ContentRepository instances is the responsibility%0A * of each particular deployment and not covered by this interface.%0A * Repository clients should use a deployment-specific mechanism (JNDI,%0A * OSGi service, etc.) to acquire references to ContentRepository instances.%0A */%0Apublic interface ContentRepository %7B%0A%0A    /**%0A     * Authenticates a user based on the given credentials or available%0A     * out-of-band information and, if successful, returns a%0A     * %7B@link ContentSession%7D instance for accessing repository content%0A     * inside the specified workspace as the authenticated user.%0A     * %3Cp%3E%0A     * TODO: Determine whether ContentSessions should cover a single%0A     * workspace or the entire repository.%0A     * %3Cp%3E%0A     * The exact type of access credentials is undefined, as this method%0A     * simply acts as a generic messenger between clients and pluggable%0A     * login modules that take care of the actual authentication. See%0A     * the documentation of relevant login modules for the kind of access%0A     * credentials they expect.%0A     * %3Cp%3E%0A     * TODO: Instead of the explicit access credentials, should this method%0A     * rather take the arguments to be passed to the relevant%0A     * JAAS %7B@link javax.security.auth.login.LoginContext%7D constructor?%0A     *%0A     * @param credentials access credentials, or %7B@code null%7D
 %0A   
@@ -2726,19 +2726,37 @@
 urn 
+au
 the
- connect
+nticated repository sess
 ion%0A
@@ -2780,24 +2780,49 @@
 ginException
+ if authentication failed
 %0A     * @thr
@@ -2986,9 +2986,11 @@
 eption;%0A
-%7D
+%0A%7D%0A

Define Oak API