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}