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