001/* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, 013 * software distributed under the License is distributed on an 014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 015 * KIND, either express or implied. See the License for the 016 * specific language governing permissions and limitations 017 * under the License. 018 * 019 */ 020package org.apache.directory.ldap.client.template; 021 022 023import java.util.List; 024 025import org.apache.directory.api.ldap.model.entry.Attribute; 026import org.apache.directory.api.ldap.model.message.AddRequest; 027import org.apache.directory.api.ldap.model.message.AddResponse; 028import org.apache.directory.api.ldap.model.message.DeleteRequest; 029import org.apache.directory.api.ldap.model.message.DeleteResponse; 030import org.apache.directory.api.ldap.model.message.ModifyRequest; 031import org.apache.directory.api.ldap.model.message.ModifyResponse; 032import org.apache.directory.api.ldap.model.message.ResultResponse; 033import org.apache.directory.api.ldap.model.message.SearchRequest; 034import org.apache.directory.api.ldap.model.message.SearchScope; 035import org.apache.directory.api.ldap.model.name.Dn; 036import org.apache.directory.ldap.client.api.search.FilterBuilder; 037import org.apache.directory.ldap.client.template.exception.PasswordException; 038 039 040/** 041 * Specifies the set of operations available on 042 * {@link org.apache.directory.ldap.client.template.LdapConnectionTemplate 043 * LdapConnectionTemplate}. This interface can be useful for unit testing 044 * in order to stub out methods. 045 * 046 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a> 047 */ 048public interface LdapConnectionOperations 049{ 050 051 /** 052 * Adds an entry specified by an AddRequest to the LDAP server. 053 * 054 * @param addRequest The request 055 * @return An AddResponse 056 */ 057 AddResponse add( AddRequest addRequest ); 058 059 060 /** 061 * Adds an entry specified by a Dn and an array of Attribute's to the LDAP 062 * server. 063 * 064 * @param dn The distinguished name of the new entry 065 * @param attributes The attributes of the new entry 066 * @return An AddResponse 067 */ 068 AddResponse add( Dn dn, Attribute... attributes ); 069 070 071 /** 072 * Adds an entry specified by a Dn, to be filled out by a RequestBuilder, 073 * to the LDAP server. 074 * 075 * @param dn The distinguished name of the new entry 076 * @param requestBuilder The request builder 077 * @return An AddResponse 078 */ 079 AddResponse add( Dn dn, RequestBuilder<AddRequest> requestBuilder ); 080 081 082 /** 083 * Attempts to authenticate the supplied credentials against the first 084 * entry found matching the search criteria. If authentication fails, 085 * a PasswordException is thrown. If successful, the response is 086 * checked for warnings, and if present, a PasswordWarning is returned. 087 * Otherwise, null is returned. 088 * 089 * @param baseDn The base DN from which to start the search for the user to authenticate 090 * @param filter The filter selecting the entries 091 * @param scope The scope to look from 092 * @param password The password 093 * @return A PasswordWarning or null 094 * @throws PasswordException If the authentication failed 095 * @see #authenticate(Dn, char[]) 096 * @see #searchFirst(String, String, SearchScope, EntryMapper) 097 */ 098 PasswordWarning authenticate( String baseDn, String filter, SearchScope scope, char[] password ) 099 throws PasswordException; 100 101 102 /** 103 * Attempts to authenticate the supplied credentials against the first 104 * entry found matching the search criteria. If authentication fails, 105 * a PasswordException is thrown. If successful, the response is 106 * checked for warnings, and if present, a PasswordWarning is returned. 107 * Otherwise, null is returned. 108 * 109 * @param baseDn The base DN from which to start the search for the user to authenticate 110 * @param filter The filter selecting the entries 111 * @param scope The scope to look from 112 * @param password The password 113 * @return A PasswordWarning or null 114 * @throws PasswordException If the authentication failed 115 * @see #authenticate(Dn, char[]) 116 * @see #searchFirst(Dn, String, SearchScope, EntryMapper) 117 */ 118 PasswordWarning authenticate( Dn baseDn, String filter, SearchScope scope, char[] password ) 119 throws PasswordException; 120 121 122 /** 123 * Attempts to authenticate the supplied credentials against the first 124 * entry found matching the search criteria. If authentication fails, 125 * a PasswordException is thrown. If successful, the response is 126 * checked for warnings, and if present, a PasswordWarning is returned. 127 * Otherwise, null is returned. 128 * 129 * @param searchRequest The SearchRequst to use to find the user to authenticate 130 * @param password The password 131 * @return A PasswordWarning or null 132 * @throws PasswordException If the authentication failed 133 * @see #authenticate(Dn, char[]) 134 * @see #searchFirst(SearchRequest, EntryMapper) 135 */ 136 PasswordWarning authenticate( SearchRequest searchRequest, char[] password ) throws PasswordException; 137 138 139 /** 140 * Attempts to authenticate the supplied credentials. If authentication 141 * fails, a PasswordException is thrown. If successful, the response is 142 * checked for warnings, and if present, a PasswordWarning is returned. 143 * Otherwise, null is returned. 144 * 145 * @param userDn The distinguished name of the user 146 * @param password The password 147 * @return A PasswordWarning or null 148 * @throws PasswordException If authentication fails 149 */ 150 PasswordWarning authenticate( Dn userDn, char[] password ) throws PasswordException; 151 152 153 /** 154 * Deletes an entry specified by a DeleteRequest from the LDAP server. 155 * 156 * @param deleteRequest The request 157 * @return A DeleteResponse 158 */ 159 DeleteResponse delete( DeleteRequest deleteRequest ); 160 161 162 /** 163 * Deletes an entry specified by Dn from the LDAP server. 164 * 165 * @param dn The distinguished name of the entry 166 * @return A DeleteResponse 167 */ 168 DeleteResponse delete( Dn dn ); 169 170 171 /** 172 * Deletes an entry specified by Dn, and whose request is configured 173 * by a RequestBuilder, from the LDAP server. 174 * 175 * @param dn The distinguished name of the entry 176 * @param requestBuilder The RequestBuilder 177 * @return A DeleteResponse 178 */ 179 DeleteResponse delete( Dn dn, RequestBuilder<DeleteRequest> requestBuilder ); 180 181 182 /** 183 * Executes the <code>connectionCallback</code>, supplying it a managed 184 * connection. 185 * 186 * @param connectionCallback The callback 187 * @param <T> The type of the mapped entry 188 * @return Whatever the callback returns 189 */ 190 <T> T execute( ConnectionCallback<T> connectionCallback ); 191 192 193 /** 194 * Performs a lookup, and supplies the matching entry to the 195 * <code>entryMapper</code>. 196 * 197 * @param dn The distinguished name of the entry 198 * @param entryMapper The mapper from entry to model object 199 * @param <T> The type of the mapped entry 200 * @return Whatever the <code>entryMapper</code> returns 201 */ 202 <T> T lookup( Dn dn, EntryMapper<T> entryMapper ); 203 204 205 /** 206 * Performs a lookup, requesting <code>attributes</code>, and supplies 207 * the matching entry to the <code>entryMapper</code>. 208 * 209 * @param dn The distinguished name of the entry 210 * @param attributes The attributes to be fetched 211 * @param entryMapper The mapper from entry to model object 212 * @param <T> The type of the mapped entry 213 * @return Whatever the <code>entryMapper</code> returns 214 */ 215 <T> T lookup( Dn dn, String[] attributes, EntryMapper<T> entryMapper ); 216 217 218 /** 219 * Modifies the password for <code>userDn</code> to 220 * <code>newPassword</code> using the admin account. 221 * 222 * @param userDn The DN of the entry we want to modify the pwassword for 223 * @param newPassword The new password 224 * @throws PasswordException If the password change failed 225 * @see #modifyPassword(Dn, char[], char[], boolean) 226 */ 227 void modifyPassword( Dn userDn, char[] newPassword ) 228 throws PasswordException; 229 230 231 /** 232 * Modifies the password for <code>userDn</code> from 233 * <code>oldPassword</code> to <code>newPassword</code>. 234 * 235 * @param userDn The DN of the entry we want to modify the pwassword for 236 * @param oldPassword The old password 237 * @param newPassword The new password 238 * @throws PasswordException If the password change failed 239 * @see #modifyPassword(Dn, char[], char[], boolean) 240 */ 241 void modifyPassword( Dn userDn, char[] oldPassword, 242 char[] newPassword ) throws PasswordException; 243 244 245 /** 246 * Modifies the password for <code>userDn</code> from 247 * <code>oldPassword</code> to <code>newPassword</code>, optionally using 248 * an admin account. If <code>asAdmin</code> is true, then the operation 249 * is performed in admin context which means <code>oldPassword</code> is 250 * may be <code>null</code>. 251 * 252 * @param userDn The distinguished name of the user 253 * @param oldPassword The users old password (optional if asAdmin is true) 254 * @param newPassword The users new password 255 * @param asAdmin If true, execute in admin context 256 * @throws PasswordException If the password modification fails 257 */ 258 void modifyPassword( Dn userDn, char[] oldPassword, char[] newPassword, 259 boolean asAdmin ) throws PasswordException; 260 261 262 /** 263 * Modifies an entry specified by a ModifyRequest on the LDAP server. 264 * 265 * @param modifyRequest The request 266 * @return A ModifyResponse 267 */ 268 ModifyResponse modify( ModifyRequest modifyRequest ); 269 270 271 /** 272 * Modifies an entry specified by Dn, and whose request is configured 273 * by a RequestBuilder, on the LDAP server. 274 * 275 * @param dn The distinguished name of the entry 276 * @param requestBuilder The RequestBuilder 277 * @return A ModifyResponse 278 */ 279 ModifyResponse modify( Dn dn, RequestBuilder<ModifyRequest> requestBuilder ); 280 281 282 /** 283 * Checks the supplied response for its result code, and if not 284 * ResultCodeEnum#SUCCESS, an exception is thrown. This method is 285 * intended to be used inline: 286 * 287 * <pre> 288 * template.responseOrException( template.delete( dn ) ); 289 * </pre> 290 * 291 * @param response The response to check for success 292 * @param <T> The type of response 293 * @return The supplied <code>response</code> 294 */ 295 <T extends ResultResponse> T responseOrException( T response ); 296 297 298 /** 299 * Searches for the entries matching the supplied criteria, feeding the 300 * result into the <code>entryMapper</code>. 301 * 302 * @param baseDn The base DN from which to start the search 303 * @param filter The filter selecting the entries 304 * @param scope The scope to look from 305 * @param entryMapper The mapper 306 * @param <T> The type of the mapped entry 307 * @return The mapped entries 308 * @see #search(SearchRequest, EntryMapper) 309 */ 310 <T> List<T> search( String baseDn, FilterBuilder filter, SearchScope scope, 311 EntryMapper<T> entryMapper ); 312 313 314 /** 315 * Searches for the entries matching the supplied criteria, feeding the 316 * result into the <code>entryMapper</code>. 317 * 318 * @param baseDn The base DN from which to start the search 319 * @param filter The filter selecting the entries 320 * @param scope The scope to look from 321 * @param entryMapper The mapper 322 * @param <T> The type of the mapped entry 323 * @return The mapped entries 324 * @see #search(SearchRequest, EntryMapper) 325 */ 326 <T> List<T> search( String baseDn, String filter, SearchScope scope, 327 EntryMapper<T> entryMapper ); 328 329 330 /** 331 * Searches for the entries matching the supplied criteria, feeding the 332 * result into the <code>entryMapper</code>. 333 * 334 * @param baseDn The base DN from which to start the search 335 * @param filter The filter selecting the entries 336 * @param scope The scope to look from 337 * @param entryMapper The mapper 338 * @param <T> The type of the mapped entry 339 * @return The mapped entries 340 * @see #search(SearchRequest, EntryMapper) 341 */ 342 <T> List<T> search( Dn baseDn, FilterBuilder filter, SearchScope scope, 343 EntryMapper<T> entryMapper ); 344 345 346 /** 347 * Searches for the entries matching the supplied criteria, feeding the 348 * result into the <code>entryMapper</code>. 349 * 350 * @param baseDn The base DN from which to start the search 351 * @param filter The filter selecting the entries 352 * @param scope The scope to look from 353 * @param entryMapper The mapper 354 * @param <T> The type of the mapped entry 355 * @return The mapped entries 356 * @see #search(SearchRequest, EntryMapper) 357 */ 358 <T> List<T> search( Dn baseDn, String filter, SearchScope scope, 359 EntryMapper<T> entryMapper ); 360 361 362 /** 363 * Searches for the entries matching the supplied criteria, feeding the 364 * result into the <code>entryMapper</code>, querying only the requested 365 * attributes. 366 * 367 * @param baseDn The base DN from which to start the search 368 * @param filter The filter selecting the entries 369 * @param scope The scope to look from 370 * @param attributes The list of AttributeType to return 371 * @param entryMapper The mapper 372 * @param <T> The type of the mapped entry 373 * @return The mapped entries 374 * @see #search(SearchRequest, EntryMapper) 375 */ 376 <T> List<T> search( String baseDn, FilterBuilder filter, SearchScope scope, 377 String[] attributes, EntryMapper<T> entryMapper ); 378 379 380 /** 381 * Searches for the entries matching the supplied criteria, feeding the 382 * result into the <code>entryMapper</code>, querying only the requested 383 * attributes. 384 * 385 * @param baseDn The base DN from which to start the search 386 * @param filter The filter selecting the entries 387 * @param scope The scope to look from 388 * @param attributes The list of AttributeType to return 389 * @param entryMapper The mapper 390 * @param <T> The type of the mapped entry 391 * @return The mapped entries 392 * @see #search(SearchRequest, EntryMapper) 393 */ 394 <T> List<T> search( String baseDn, String filter, SearchScope scope, 395 String[] attributes, EntryMapper<T> entryMapper ); 396 397 398 /** 399 * Searches for the entries matching the supplied criteria, feeding the 400 * result into the <code>entryMapper</code>, querying only the requested 401 * attributes. 402 * 403 * @param baseDn The base DN from which to start the search 404 * @param filter The filter selecting the entries 405 * @param scope The scope to look from 406 * @param attributes The list of AttributeType to return 407 * @param entryMapper The mapper 408 * @param <T> The type of the mapped entry 409 * @return The mapped entries 410 * @see #search(SearchRequest, EntryMapper) 411 */ 412 <T> List<T> search( Dn baseDn, FilterBuilder filter, SearchScope scope, 413 String[] attributes, EntryMapper<T> entryMapper ); 414 415 416 /** 417 * Searches for the entries matching the supplied criteria, feeding the 418 * result into the <code>entryMapper</code>, querying only the requested 419 * attributes. 420 * 421 * @param baseDn The base DN from which to start the search 422 * @param filter The filter selecting the entries 423 * @param scope The scope to look from 424 * @param attributes The list of AttributeType to return 425 * @param entryMapper The mapper 426 * @param <T> The type of the mapped entry 427 * @return The mapped entries 428 * @see #search(SearchRequest, EntryMapper) 429 */ 430 <T> List<T> search( Dn baseDn, String filter, SearchScope scope, 431 String[] attributes, EntryMapper<T> entryMapper ); 432 433 434 /** 435 * Searches for the entries matching the supplied 436 * <code>searchRequest</code>, feeding the result into the 437 * <code>entryMapper</code>. 438 * 439 * @param searchRequest The search request 440 * @param entryMapper The mapper 441 * @param <T> The type of the mapped entry 442 * @return The mapped entries 443 */ 444 <T> List<T> search( SearchRequest searchRequest, 445 EntryMapper<T> entryMapper ); 446 447 448 /** 449 * Searches for the first entry matching the supplied criteria, feeding the 450 * result into the <code>entryMapper</code>. 451 * 452 * @param baseDn The base DN from which to start the search 453 * @param filter The filter selecting the entries 454 * @param scope The scope to look from 455 * @param entryMapper The mapper 456 * @param <T> The type of the mapped entry 457 * @return The mapped entries 458 * @see #searchFirst(SearchRequest, EntryMapper) 459 */ 460 <T> T searchFirst( String baseDn, FilterBuilder filter, SearchScope scope, 461 EntryMapper<T> entryMapper ); 462 463 464 /** 465 * Searches for the first entry matching the supplied criteria, feeding the 466 * result into the <code>entryMapper</code>. 467 * 468 * @param baseDn The base DN from which to start the search 469 * @param filter The filter selecting the entries 470 * @param scope The scope to look from 471 * @param entryMapper The mapper 472 * @param <T> The type of the mapped entry 473 * @return The mapped entries 474 * @see #searchFirst(SearchRequest, EntryMapper) 475 */ 476 <T> T searchFirst( String baseDn, String filter, SearchScope scope, 477 EntryMapper<T> entryMapper ); 478 479 480 /** 481 * Searches for the first entry matching the supplied criteria, feeding the 482 * result into the <code>entryMapper</code>. 483 * 484 * @param baseDn The base DN from which to start the search 485 * @param filter The filter selecting the entries 486 * @param scope The scope to look from 487 * @param entryMapper The mapper 488 * @param <T> The type of the mapped entry 489 * @return The mapped entries 490 * @see #searchFirst(SearchRequest, EntryMapper) 491 */ 492 <T> T searchFirst( Dn baseDn, FilterBuilder filter, SearchScope scope, 493 EntryMapper<T> entryMapper ); 494 495 496 /** 497 * Searches for the first entry matching the supplied criteria, feeding the 498 * result into the <code>entryMapper</code>. 499 * 500 * @param baseDn The base DN from which to start the search 501 * @param filter The filter selecting the entries 502 * @param scope The scope to look from 503 * @param entryMapper The mapper 504 * @param <T> The type of the mapped entry 505 * @return The mapped entries 506 * @see #searchFirst(SearchRequest, EntryMapper) 507 */ 508 <T> T searchFirst( Dn baseDn, String filter, SearchScope scope, 509 EntryMapper<T> entryMapper ); 510 511 512 /** 513 * Searches for the first entry matching the supplied criteria, feeding the 514 * result into the <code>entryMapper</code>, querying only the requested 515 * attributes. 516 * 517 * @param baseDn The base DN from which to start the search 518 * @param filter The filter selecting the entries 519 * @param scope The scope to look from 520 * @param attributes The list of AttributeType to return 521 * @param entryMapper The mapper 522 * @param <T> The type of the mapped entry 523 * @return The mapped entries 524 * @see #searchFirst(SearchRequest, EntryMapper) 525 */ 526 <T> T searchFirst( String baseDn, FilterBuilder filter, SearchScope scope, 527 String[] attributes, EntryMapper<T> entryMapper ); 528 529 530 /** 531 * Searches for the first entry matching the supplied criteria, feeding the 532 * result into the <code>entryMapper</code>, querying only the requested 533 * attributes. 534 * 535 * @param baseDn The base DN from which to start the search 536 * @param filter The filter selecting the entries 537 * @param scope The scope to look from 538 * @param attributes The list of AttributeType to return 539 * @param entryMapper The mapper 540 * @param <T> The type of the mapped entry 541 * @return The mapped entries 542 * @see #searchFirst(SearchRequest, EntryMapper) 543 */ 544 <T> T searchFirst( String baseDn, String filter, SearchScope scope, 545 String[] attributes, EntryMapper<T> entryMapper ); 546 547 548 /** 549 * Searches for the first entry matching the supplied criteria, feeding the 550 * result into the <code>entryMapper</code>, querying only the requested 551 * attributes. 552 * 553 * @param baseDn The base DN from which to start the search 554 * @param filter The filter selecting the entries 555 * @param scope The scope to look from 556 * @param attributes The list of AttributeType to return 557 * @param entryMapper The mapper 558 * @param <T> The type of the mapped entry 559 * @return The mapped entries 560 * @see #searchFirst(SearchRequest, EntryMapper) 561 */ 562 <T> T searchFirst( Dn baseDn, FilterBuilder filter, SearchScope scope, 563 String[] attributes, EntryMapper<T> entryMapper ); 564 565 566 /** 567 * Searches for the first entry matching the supplied criteria, feeding the 568 * result into the <code>entryMapper</code>, querying only the requested 569 * attributes. 570 * 571 * @param baseDn The base DN from which to start the search 572 * @param filter The filter selecting the entries 573 * @param scope The scope to look from 574 * @param attributes The list of AttributeType to return 575 * @param entryMapper The mapper 576 * @param <T> The type of the mapped entry 577 * @return The mapped entries 578 * @see #searchFirst(SearchRequest, EntryMapper) 579 */ 580 <T> T searchFirst( Dn baseDn, String filter, SearchScope scope, 581 String[] attributes, EntryMapper<T> entryMapper ); 582 583 584 /** 585 * Searches for the first entry matching the supplied 586 * <code>searchRequest</code>, feeding the result into the 587 * <code>entryMapper</code>. This is basically the same as 588 * {@link #search(SearchRequest, EntryMapper)}, but is optimized by 589 * modifying the <code>searchRequest</code> to set its size limit to 1. 590 * The <code>searchRequest</code> is returned to its original size limit 591 * before this method returns (or throws an exception). 592 * 593 * @param searchRequest The search request 594 * @param entryMapper The mapper 595 * @param <T> The type of the mapped entry 596 * @return The mapped entry 597 */ 598 <T> T searchFirst( SearchRequest searchRequest, 599 EntryMapper<T> entryMapper ); 600 601}