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