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.BaseDirectoryDescriptor;
028import org.nuxeo.ecm.directory.Directory;
029import org.nuxeo.ecm.directory.Session;
030
031/**
032 * @author <a href="mailto:[email protected]">George Lefter</a>
033 */
034public interface DirectoryService {
035
036    public final static String SYSTEM_DIRECTORY_TYPE = "system";
037
038    /**
039     * Gets the directory ids.
040     */
041    List<String> getDirectoryNames();
042
043    /**
044     * Gets all the directories.
045     */
046    List<Directory> getDirectories();
047
048    /**
049     * Returns the directory for the specified id and document context.
050     * <p>
051     * The context is given by the document. The document service will try to find the directory local configuration of
052     * the document that will specify the suffix. The directory service will fetch the id + suffix found. If no local
053     * configuration is found the service will return the directory with the given id.
054     * <p>
055     * If the id is {@code null}, returns {@code null}.
056     *
057     * @param id the directory id
058     * @param documentContext the document context
059     * @return the directory, or {@code null} if not found
060     */
061    Directory getDirectory(String id, DocumentModel documentContext);
062
063    /**
064     * Return the directory with the given id.
065     * <p>
066     * If the id is {@code null}, returns {@code null}.
067     *
068     * @param id the directory id
069     * @return the directory, or {@code null} if not found
070     */
071    Directory getDirectory(String id);
072
073    /**
074     * Gets the effective directory descriptor for the given directory.
075     *
076     * @param id the directory id
077     * @return the effective directory descriptor, or {@code null} if not registered
078     *
079     * @since 8.2
080     */
081    BaseDirectoryDescriptor getDirectoryDescriptor(String id);
082
083    /**
084     * Opens a session on specified directory.
085     * <p>
086     * This method prefers to throw rather than returning null.
087     *
088     * @param directoryName
089     * @return the session
090     */
091    Session open(String directoryName);
092
093    /**
094     * Opens a session on the directory for the specified context. The context is given by the document. The document
095     * service will try to find the directory local configuration of the document that will specify the suffix. the
096     * directory will fetch the directoryName + suffix found. If no local configuration is found the service will return
097     * the directoryName directory.
098     * <p>
099     * This method prefers to throw rather than returning null.
100     *
101     * @param directoryName
102     * @param documentContext
103     * @return the session
104     */
105    Session open(String directoryName, DocumentModel documentContext);
106
107    /**
108     * Gets the schema for a directory.
109     *
110     * @param id the directory id
111     * @return the schema for the directory
112     */
113    String getDirectorySchema(String id);
114
115    /**
116     * Gets the id field for a directory.
117     *
118     * @param id the directory id
119     * @return the id field for the directory
120     */
121    String getDirectoryIdField(String id);
122
123    /**
124     * Gets the password field for a directory.
125     *
126     * @param id the directory id
127     * @return the password field for the directory
128     */
129    String getDirectoryPasswordField(String directoryName);
130
131    /**
132     * Gets the parent directory id a directory.
133     *
134     * @param id the directory id
135     * @return the parent directory id, which may be {@code null}
136     */
137    String getParentDirectoryName(String id);
138
139    /**
140     * INTERNAL registers a directory descriptor.
141     */
142    void registerDirectoryDescriptor(BaseDirectoryDescriptor descriptor);
143
144    /**
145     * INTERNAL unregisters a directory descriptor.
146     */
147    void unregisterDirectoryDescriptor(BaseDirectoryDescriptor descriptor);
148
149}