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