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