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.io.Serializable;
024import java.util.List;
025import java.util.Map;
026import java.util.Set;
027
028import org.nuxeo.ecm.core.api.DocumentModel;
029import org.nuxeo.ecm.core.api.DocumentModelList;
030
031/**
032 * A session used to access entries in a directory.
033 * <p>
034 * This class is used to create, obtain, modify and delete entries in a directory.
035 *
036 * @see
037 * @see Directory#getSession()
038 * @author glefter@nuxeo.com
039 */
040
041public interface Session extends AutoCloseable {
042
043    /**
044     * Retrieves a directory entry using its id.
045     * <p>
046     * TODO what happens when the entry is not found? return null if not found?
047     *
048     * @param id the entry id
049     * @return a DocumentModel representing the entry
050     * @throws DirectoryException
051     */
052    DocumentModel getEntry(String id) throws DirectoryException;
053
054    /**
055     * Retrieves a directory entry using its id.
056     *
057     * @param id the entry id
058     * @param fetchReferences boolean stating if references have to be fetched
059     * @return a DocumentModel representing the entry
060     * @throws DirectoryException
061     */
062    DocumentModel getEntry(String id, boolean fetchReferences) throws DirectoryException;
063
064    /**
065     * Retrieves all the entries in the directory. If the remote server issues a size limit exceeded error while sending
066     * partial results up to that limit, the method {@code DocumentModelList#totalsize} on the returned list will return
067     * -2 as a special marker for truncated results.
068     *
069     * @deprecated since 6.0 Use query method instead with parameters
070     * @return a collection with all the entries in the directory
071     * @throws DirectoryException
072     * @throws SizeLimitExceededException if the number of results is larger than the limit configured for the directory
073     *             and the server does not send partial results.
074     */
075    @Deprecated
076    DocumentModelList getEntries() throws DirectoryException;
077
078    /**
079     * Creates an entry in a directory.
080     *
081     * @param fieldMap A map with keys and values that should be stored in a directory
082     *            <p>
083     *            Note: The values in the map should be of type String
084     * @return The new entry created in the directory
085     * @throws UnsupportedOperationException if the directory does not allow the creation of new entries
086     * @throws DirectoryException if a communication exception occurs or if an entry with the same id already exists.
087     */
088    DocumentModel createEntry(Map<String, Object> fieldMap) throws DirectoryException;
089
090    /**
091     * Updates a directory entry.
092     *
093     * @param docModel The entry to update
094     * @throws UnsupportedOperationException if the directory does not support entry updating
095     * @throws DirectoryException if a communication error occurs
096     */
097    void updateEntry(DocumentModel docModel) throws DirectoryException;
098
099    /**
100     * Deletes a directory entry.
101     *
102     * @param docModel The entry to delete
103     * @throws UnsupportedOperationException if the directory does not support entry deleting
104     * @throws DirectoryException if a communication error occurs
105     */
106    void deleteEntry(DocumentModel docModel) throws DirectoryException;
107
108    /**
109     * Deletes a directory entry by id.
110     *
111     * @param id the id of the entry to delete
112     * @throws UnsupportedOperationException if the directory does not support entry deleting
113     * @throws DirectoryException if a communication error occurs
114     */
115    void deleteEntry(String id) throws DirectoryException;
116
117    /**
118     * Deletes a directory entry by id and secondary ids.
119     * <p>
120     * This is used for hierarchical vocabularies, where the actual unique key is the couple (parent, id).
121     *
122     * @param id the id of the entry to delete.
123     * @param map a map of secondary key values.
124     * @throws DirectoryException if a communication error occurs.
125     * @deprecated since 9.2 (unused), use {@link #deleteEntry(String)} instead.
126     */
127    @Deprecated
128    void deleteEntry(String id, Map<String, String> map) throws DirectoryException;
129
130    /*
131     * FIXME: Parses a query string and create a query object for this directory.
132     * @param query the query string to parse @return a new query object @throws QueryException if the query cannot be
133     * parsed maybe not needed public SQLQuery createQuery(String query) throws QueryException;
134     */
135
136    /**
137     * Executes a simple query. The conditions will be 'AND'-ed. Search is done with exact match.
138     * <p>
139     * Does not fetch reference fields.
140     * </p>
141     * If the remote server issues a size limit exceeded error while sending partial results up to that limit, the
142     * method {@code DocumentModelList#totalsize} on the returned list will return -2 as a special marker for truncated
143     * results.
144     *
145     * @param filter a filter to apply to entries in directory
146     * @return a list of document models containing the entries matched by the query
147     * @throws DirectoryException if a communication error occurs
148     * @throws SizeLimitExceededException if the number of results is larger than the limit configured for the directory
149     *             and the server does not send partial results.
150     */
151    DocumentModelList query(Map<String, Serializable> filter) throws DirectoryException;
152
153    /**
154     * Executes a simple query. The conditions will be 'AND'-ed.
155     * <p>
156     * fieldNames present in the fulltext set are treated as a fulltext match. Does not fetch reference fields.
157     * </p>
158     * If the remote server issues a size limit exceeded error while sending partial results up to that limit, the
159     * method {@code DocumentModelList#totalsize} on the returned list will return -2 as a special marker for truncated
160     * results.
161     *
162     * @param filter a filter to apply to entries in directory
163     * @param fulltext a set of field that should be treated as a fulltext search
164     * @return a list of document models containing the entries matched by the query
165     * @throws DirectoryException if a communication error occurs
166     * @throws SizeLimitExceededException if the number of results is larger than the limit configured for the directory
167     *             and the server does not send partial results.
168     */
169    DocumentModelList query(Map<String, Serializable> filter, Set<String> fulltext) throws
170            DirectoryException;
171
172    /**
173     * Executes a simple query. The conditions will be 'AND'-ed and the result will be sorted by the orderBy criteria
174     * list.
175     * <p>
176     * fieldNames present in the fulltext set are treated as a fulltext match. Does not fetch reference fields.
177     * </p>
178     * If the remote server issues a size limit exceeded error while sending partial results up to that limit, the
179     * method {@code DocumentModelList#totalsize} on the returned list will return -2 as a special marker for truncated
180     * results.
181     *
182     * @param filter a filter to apply to entries in directory
183     * @param orderBy a LinkedHashMap with the 'order by' criterias.The key of an entry of this map represents the
184     *            column name and the value of the same entry represent the column order,which may be 'asc' or 'desc'.
185     * @param fulltext a set of field that should be treated as a fulltext search
186     * @return a list of document models containing the entries matched by the query
187     * @throws DirectoryException if a communication error occurs
188     * @throws SizeLimitExceededException if the number of results is larger than the limit configured for the directory
189     *             and the server does not send partial results.
190     */
191    DocumentModelList query(Map<String, Serializable> filter, Set<String> fulltext, Map<String, String> orderBy)
192            throws DirectoryException;
193
194    /**
195     * Executes a query with the possibility to fetch references
196     *
197     * @see #query(Map, Set, Map)
198     */
199    DocumentModelList query(Map<String, Serializable> filter, Set<String> fulltext, Map<String, String> orderBy,
200            boolean fetchReferences) throws DirectoryException;
201
202    /**
203     * Executes a query with the possibility to fetch a subset of the results. org.nuxeo.ecm.directory.BaseSession
204     * provides a default implementation fetching all results to return the subset. Not recommended.
205     *
206     * @param limit maximum number of results ignored if less than 1
207     * @param offset number of rows skipped before starting, will be 0 if less than 0.
208     * @see #query(Map, Set, Map, boolean)
209     * @since 5.7
210     */
211    DocumentModelList query(Map<String, Serializable> filter, Set<String> fulltext, Map<String, String> orderBy,
212            boolean fetchReferences, int limit, int offset) throws DirectoryException;
213
214    // TODO: create an API to allow sql AND/OR/NOT/LIKE conditions
215    // public DocumentModelList query(Criteria criteria ) throws
216    // DirectoryException;
217
218    /**
219     * Closes the session and all open result sets obtained from this session.
220     * <p>
221     * Releases this Connection object's resources immediately instead of waiting for them to be automatically released.
222     * <p>
223     * TODO: should this operation auto-commit pending changes?
224     *
225     * @throws DirectoryException if a communication error occurs
226     */
227    @Override
228    void close() throws DirectoryException;
229
230    /**
231     * Executes a query using filter and return only the column <b>columnName</b>.
232     *
233     * @param filter the filter for the query
234     * @param columnName the column whose content should be returned
235     * @return the list with the values of <b>columnName</b> for the entries matching <b>filter</b>
236     * @throws DirectoryException
237     * @throws SizeLimitExceededException if the number of results is larger than the limit configured for the directory
238     */
239    List<String> getProjection(Map<String, Serializable> filter, String columnName) throws
240            DirectoryException;
241
242    List<String> getProjection(Map<String, Serializable> filter, Set<String> fulltext, String columnName)
243            throws DirectoryException;
244
245    /**
246     * Tells whether the directory implementation can be used as an authenticating backend for the UserManager (based on
247     * login / password check).
248     *
249     * @return true is the directory is authentication aware
250     * @throws DirectoryException
251     */
252    boolean isAuthenticating() throws DirectoryException;
253
254    /**
255     * Checks that the credentials provided by the UserManager match those registered in the directory. If username is
256     * not in the directory, this should return false instead of throrwing an exception.
257     *
258     * @param username
259     * @param password
260     * @return true is the credentials match those stored in the directory
261     */
262    boolean authenticate(String username, String password) throws DirectoryException;
263
264    /**
265     * The Id field is the name of the field that is used a primary key: unique and not null value in the whole
266     * directory. This field is also used as login field if the directory is authenticating.
267     *
268     * @return the name of the id field
269     */
270    String getIdField();
271
272    /**
273     * @return the name of the field to store the password if the directory is authenticating (can be null)
274     */
275    String getPasswordField();
276
277    boolean isReadOnly();
278
279    /**
280     * Returns true if session has an entry with given id.
281     *
282     * @since 5.2M4
283     */
284    boolean hasEntry(String id);
285
286    /**
287     * Creates an entry in a directory.
288     *
289     * @since 5.2M4
290     * @param entry the document model representing the entry to create
291     * @return The new entry created in the directory
292     * @throws UnsupportedOperationException if the directory does not allow the creation of new entries
293     * @throws DirectoryException if a communication exception occurs or if an entry with the same id already exists.
294     */
295    DocumentModel createEntry(DocumentModel entry);
296
297    /**
298     * For test framework. Changes the read/query methods to return all of the entries, including the password field.
299     *
300     * @param readAllColumns whether to read all columns
301     * @since 9.1
302     */
303    void setReadAllColumns(boolean readAllColumns);
304
305}