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