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}