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 *     Nuxeo - initial API and implementation
018 * $Id$
019 */
020
021package org.nuxeo.ecm.directory;
022
023import java.util.Collection;
024import java.util.List;
025import java.util.Map;
026
027import org.nuxeo.ecm.core.schema.types.Field;
028import org.nuxeo.ecm.directory.api.DirectoryDeleteConstraint;
029
030/**
031 * The directory interface.
032 * <p>
033 * This interface is implemented in order to create an NXDirectory. One should implement this interface in order to
034 * create either a new Directory implementation or a new Directory Source.
035 *
036 * @author glefter@nuxeo.com
037 */
038// TODO: maybe separate Directory implementation and Directory Source
039public interface Directory {
040
041    /**
042     * Gets the unique name of the directory, used for registering.
043     *
044     * @return the unique directory name
045     * @throws DirectoryException
046     */
047    String getName() throws DirectoryException;
048
049    /**
050     * Gets the schema name used by this directory.
051     *
052     * @return the schema name
053     * @throws DirectoryException
054     */
055    String getSchema() throws DirectoryException;
056
057    /**
058     * Gets the name of the parent directory. This is used for hierarchical vocabularies.
059     *
060     * @return the name of the parent directory, or null.
061     */
062    String getParentDirectory() throws DirectoryException;
063
064    /**
065     * Gets the id field of the schema for this directory.
066     *
067     * @return the id field.
068     * @throws DirectoryException
069     */
070    String getIdField() throws DirectoryException;
071
072    /**
073     * Gets the password field of the schema for this directory.
074     *
075     * @return the password field.
076     * @throws DirectoryException
077     */
078    String getPasswordField() throws DirectoryException;
079
080    /**
081     * Checks if this directory is read-only.
082     *
083     * @since 8.2
084     */
085    boolean isReadOnly();
086
087    /**
088     * Shuts down the directory.
089     *
090     * @throws DirectoryException
091     */
092    void shutdown() throws DirectoryException;
093
094    /**
095     * Creates a session for accessing entries in this directory.
096     *
097     * @return a Session object
098     * @throws DirectoryException if a session cannot be created
099     */
100    Session getSession() throws DirectoryException;
101
102    /**
103     * Lookup a Reference by field name.
104     *
105     * @return the matching reference implementation or null
106     * @throws DirectoryException
107     * @deprecated since 7.4, kept for compatibility with old code, use {@link #getReferences(String)} instead
108     */
109    @Deprecated
110    Reference getReference(String referenceFieldName) throws DirectoryException;
111
112    /**
113     * Lookup the References by field name.
114     *
115     * @return the matching references implementation or null
116     * @throws DirectoryException
117     */
118    List<Reference> getReferences(String referenceFieldName) throws DirectoryException;
119
120    /**
121     * Lookup all References defined on the directory.
122     *
123     * @return all registered references
124     * @throws DirectoryException
125     */
126    Collection<Reference> getReferences() throws DirectoryException;
127
128    /**
129     * Gets the cache instance of the directory
130     *
131     * @return the cache of the directory
132     * @throws DirectoryException
133     */
134    DirectoryCache getCache() throws DirectoryException;
135
136    /**
137     * Invalidates the cache instance of the directory
138     *
139     * @throws DirectoryException
140     */
141    void invalidateDirectoryCache() throws DirectoryException;
142
143    /**
144     * Returns {@code true} if this directory is a multi tenant directory, {@code false} otherwise.
145     *
146     * @since 5.6
147     */
148    boolean isMultiTenant() throws DirectoryException;
149
150    /**
151     * @since 8.4
152     */
153    List<String> getTypes();
154
155    /**
156     * @since 8.4
157     */
158    List<DirectoryDeleteConstraint> getDirectoryDeleteConstraints();
159
160    /**
161     * Invalidate caches
162     *
163     * @since 9.2
164     */
165    void invalidateCaches() throws DirectoryException;
166
167    /**
168     * Get schema field map
169     *
170     * @since 9.2
171     */
172    Map<String, Field> getSchemaFieldMap();
173
174    /**
175     * Get descriptor
176     *
177     * @since 9.2
178     */
179    BaseDirectoryDescriptor getDescriptor();
180
181}