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