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