001/*
002 * (C) Copyright 2006-2007 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 *
016 * Contributors:
017 *     George Lefter
018 *
019 * $Id$
020 */
021
022package org.nuxeo.ecm.directory.api;
023
024import java.util.List;
025
026import org.nuxeo.ecm.core.api.DocumentModel;
027import org.nuxeo.ecm.directory.Directory;
028import org.nuxeo.ecm.directory.DirectoryException;
029import org.nuxeo.ecm.directory.DirectoryFactory;
030import org.nuxeo.ecm.directory.Session;
031import org.nuxeo.runtime.model.ComponentName;
032
033/**
034 * @author <a href="mailto:glefter@nuxeo.com">George Lefter</a>
035 */
036public interface DirectoryService {
037
038    ComponentName NAME = new ComponentName("org.nuxeo.ecm.directory.DirectoryServiceImpl");
039
040    List<String> getDirectoryNames();
041
042    String getDirectorySchema(String directoryName) throws DirectoryException;
043
044    /**
045     * Opens a session on specified directory.
046     * <p>
047     * This method prefers to throw rather than returning null.
048     *
049     * @param directoryName
050     * @return the session
051     * @throws DirectoryException in case the session cannot be created
052     */
053    Session open(String directoryName) throws DirectoryException;
054
055    /**
056     * Opens a session on the directory for the specified context. The context is given by the document. The document
057     * service will try to find the directory local configuration of the document that will specify the suffix. the
058     * directory will fetch the directoryName + suffix found. If no local configuration is found the service will return
059     * the directoryName directory.
060     * <p>
061     * This method prefers to throw rather than returning null.
062     *
063     * @param directoryName
064     * @param documentContext
065     * @return the session
066     * @throws DirectoryException in case the session cannot be created
067     */
068    Session open(String directoryName, DocumentModel documentContext) throws DirectoryException;
069
070    /**
071     * Return the directory for the specified context. The context is given by the document. The document service will
072     * try to find the directory local configuration of the document that will specify the suffix. The directory service
073     * will fetch the directoryName + suffix found. If no local configuration is found the service will return the
074     * directoryName directory.
075     * <p>
076     * If the directoryName is null, return null.
077     *
078     * @param directoryName
079     * @param documentContext
080     * @return the directory, if the factory of the directory or the directory itself is not found return null
081     * @throws DirectoryException
082     */
083    Directory getDirectory(String directoryName, DocumentModel documentContext) throws DirectoryException;
084
085    /**
086     * Return the directory with the name directoryName.
087     * <p>
088     * If the directoryName is null, return null.
089     *
090     * @param directoryName
091     * @return the directory, if the factory of the directory or the directory itself is not found return null
092     * @throws DirectoryException
093     */
094    Directory getDirectory(String directoryName) throws DirectoryException;
095
096    /**
097     * Return all the directories registered into the service.
098     * <p>
099     *
100     * @throws DirectoryException
101     */
102    List<Directory> getDirectories() throws DirectoryException;
103
104    void registerDirectory(String directoryName, DirectoryFactory factory);
105
106    void unregisterDirectory(String directoryName, DirectoryFactory factory);
107
108    String getDirectoryIdField(String directoryName) throws DirectoryException;
109
110    String getDirectoryPasswordField(String directoryName) throws DirectoryException;
111
112    /**
113     * Returns the name of the parent directory of specified directory, if applicable.
114     *
115     * @param directoryName
116     * @return the name, or null
117     * @throws DirectoryException
118     */
119    String getParentDirectoryName(String directoryName) throws DirectoryException;
120
121}