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
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     */
052    DocumentModel getEntry(String id);
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     */
061    DocumentModel getEntry(String id, boolean fetchReferences);
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 SizeLimitExceededException if the number of results is larger than the limit configured for the directory
071     *             and the server does not send partial results.
072     */
073    @Deprecated
074    DocumentModelList getEntries();
075
076    /**
077     * Creates an entry in a directory.
078     *
079     * @param fieldMap A map with keys and values that should be stored in a directory
080     *            <p>
081     *            Note: The values in the map should be of type String
082     * @return The new entry created in the directory
083     * @throws UnsupportedOperationException if the directory does not allow the creation of new entries
084     */
085    DocumentModel createEntry(Map<String, Object> fieldMap);
086
087    /**
088     * Updates a directory entry.
089     *
090     * @param docModel The entry to update
091     * @throws UnsupportedOperationException if the directory does not support entry updating
092     */
093    void updateEntry(DocumentModel docModel);
094
095    /**
096     * Deletes a directory entry.
097     *
098     * @param docModel The entry to delete
099     * @throws UnsupportedOperationException if the directory does not support entry deleting
100     */
101    void deleteEntry(DocumentModel docModel);
102
103    /**
104     * Deletes a directory entry by id.
105     *
106     * @param id the id of the entry to delete
107     * @throws UnsupportedOperationException if the directory does not support entry deleting
108     */
109    void deleteEntry(String id);
110
111    /**
112     * Deletes a directory entry by id and secondary ids.
113     * <p>
114     * This is used for hierarchical vocabularies, where the actual unique key is the couple (parent, id).
115     *
116     * @param id the id of the entry to delete.
117     * @param map a map of secondary key values.
118     * @deprecated since 9.2 (unused), use {@link #deleteEntry(String)} instead.
119     */
120    @Deprecated
121    void deleteEntry(String id, Map<String, String> map);
122
123    /*
124     * FIXME: Parses a query string and create a query object for this directory.
125     * @param query the query string to parse @return a new query object @throws QueryException if the query cannot be
126     * parsed maybe not needed public SQLQuery createQuery(String query) throws QueryException;
127     */
128
129    /**
130     * Executes a simple query. The conditions will be 'AND'-ed. Search is done with exact match.
131     * <p>
132     * Does not fetch reference fields.
133     * </p>
134     * If the remote server issues a size limit exceeded error while sending partial results up to that limit, the
135     * method {@code DocumentModelList#totalsize} on the returned list will return -2 as a special marker for truncated
136     * results.
137     *
138     * @param filter a filter to apply to entries in directory
139     * @return a list of document models containing the entries matched by the query
140     * @throws SizeLimitExceededException if the number of results is larger than the limit configured for the directory
141     *             and the server does not send partial results.
142     */
143    DocumentModelList query(Map<String, Serializable> filter);
144
145    /**
146     * Executes a simple query. The conditions will be 'AND'-ed.
147     * <p>
148     * fieldNames present in the fulltext set are treated as a fulltext match. Does not fetch reference fields.
149     * </p>
150     * If the remote server issues a size limit exceeded error while sending partial results up to that limit, the
151     * method {@code DocumentModelList#totalsize} on the returned list will return -2 as a special marker for truncated
152     * results.
153     *
154     * @param filter a filter to apply to entries in directory
155     * @param fulltext a set of field that should be treated as a fulltext search
156     * @return a list of document models containing the entries matched by the query
157     * @throws SizeLimitExceededException if the number of results is larger than the limit configured for the directory
158     *             and the server does not send partial results.
159     */
160    DocumentModelList query(Map<String, Serializable> filter, Set<String> fulltext);
161
162    /**
163     * Executes a simple query. The conditions will be 'AND'-ed and the result will be sorted by the orderBy criteria
164     * list.
165     * <p>
166     * fieldNames present in the fulltext set are treated as a fulltext match. Does not fetch reference fields.
167     * </p>
168     * If the remote server issues a size limit exceeded error while sending partial results up to that limit, the
169     * method {@code DocumentModelList#totalsize} on the returned list will return -2 as a special marker for truncated
170     * results.
171     *
172     * @param filter a filter to apply to entries in directory
173     * @param orderBy a LinkedHashMap with the 'order by' criterias.The key of an entry of this map represents the
174     *            column name and the value of the same entry represent the column order,which may be 'asc' or 'desc'.
175     * @param fulltext a set of field that should be treated as a fulltext search
176     * @return a list of document models containing the entries matched by the query
177     * @throws SizeLimitExceededException if the number of results is larger than the limit configured for the directory
178     *             and the server does not send partial results.
179     */
180    DocumentModelList query(Map<String, Serializable> filter, Set<String> fulltext, Map<String, String> orderBy);
181
182    /**
183     * Executes a query with the possibility to fetch references
184     *
185     * @see #query(Map, Set, Map)
186     */
187    DocumentModelList query(Map<String, Serializable> filter, Set<String> fulltext, Map<String, String> orderBy,
188            boolean fetchReferences);
189
190    /**
191     * Executes a query with the possibility to fetch a subset of the results. org.nuxeo.ecm.directory.BaseSession
192     * provides a default implementation fetching all results to return the subset. Not recommended.
193     *
194     * @param limit maximum number of results ignored if less than 1
195     * @param offset number of rows skipped before starting, will be 0 if less than 0.
196     * @see #query(Map, Set, Map, boolean)
197     * @since 5.7
198     */
199    DocumentModelList query(Map<String, Serializable> filter, Set<String> fulltext, Map<String, String> orderBy,
200            boolean fetchReferences, int limit, int offset);
201
202    /**
203     * Executes a query with the possibility to fetch a subset of the results.
204     *
205     * @param queryBuilder the query to use, including limit, offset, ordering and countTotal
206     * @param fetchReferences boolean stating if references have to be fetched
207     * @return the list of documents, where the total size may be present if countTotal was true
208     * @since 10.3
209     */
210    DocumentModelList query(QueryBuilder queryBuilder, boolean fetchReferences);
211
212    /**
213     * Executes a query with the possibility to fetch a subset of the results. Returns the matching ids.
214     *
215     * @param queryBuilder the query to use, including limit, offset and ordering
216     * @return the list of document ids
217     * @since 10.3
218     */
219    List<String> queryIds(QueryBuilder queryBuilder);
220
221    /**
222     * Closes the session and all open result sets obtained from this session.
223     * <p>
224     * Releases this Connection object's resources immediately instead of waiting for them to be automatically released.
225     * <p>
226     * TODO: should this operation auto-commit pending changes?
227     */
228    @Override
229    void close();
230
231    /**
232     * Executes a query using filter and return only the column <b>columnName</b>.
233     *
234     * @param filter the filter for the query
235     * @param columnName the column whose content should be returned
236     * @return the list with the values of <b>columnName</b> for the entries matching <b>filter</b>
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);
240
241    List<String> getProjection(Map<String, Serializable> filter, Set<String> fulltext, String columnName);
242
243    /**
244     * Tells whether the directory implementation can be used as an authenticating backend for the UserManager (based on
245     * login / password check).
246     *
247     * @return true is the directory is authentication aware
248     */
249    boolean isAuthenticating();
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);
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     */
291    DocumentModel createEntry(DocumentModel entry);
292
293    /**
294     * For test framework. Changes the read/query methods to return all of the entries, including the password field.
295     *
296     * @param readAllColumns whether to read all columns
297     * @since 9.1
298     */
299    void setReadAllColumns(boolean readAllColumns);
300
301}