1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 * 19 */ 20 package org.apache.directory.ldap.client.template; 21 22 23 import java.util.List; 24 25 import org.apache.directory.api.ldap.model.entry.Attribute; 26 import org.apache.directory.api.ldap.model.message.AddRequest; 27 import org.apache.directory.api.ldap.model.message.AddResponse; 28 import org.apache.directory.api.ldap.model.message.DeleteRequest; 29 import org.apache.directory.api.ldap.model.message.DeleteResponse; 30 import org.apache.directory.api.ldap.model.message.ModifyRequest; 31 import org.apache.directory.api.ldap.model.message.ModifyResponse; 32 import org.apache.directory.api.ldap.model.message.ResultCodeEnum; 33 import org.apache.directory.api.ldap.model.message.ResultResponse; 34 import org.apache.directory.api.ldap.model.message.SearchRequest; 35 import org.apache.directory.api.ldap.model.message.SearchScope; 36 import org.apache.directory.api.ldap.model.name.Dn; 37 import org.apache.directory.ldap.client.api.search.FilterBuilder; 38 import org.apache.directory.ldap.client.template.exception.LdapRequestUnsuccessfulException; 39 import org.apache.directory.ldap.client.template.exception.PasswordException; 40 41 42 /** 43 * Specifies the set of operations available on 44 * {@link org.apache.directory.ldap.client.template.LdapConnectionTemplate 45 * LdapConnectionTemplate}. This interface can be useful for unit testing 46 * in order to stub out methods. 47 * 48 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a> 49 */ 50 public interface LdapConnectionOperations 51 { 52 53 /** 54 * Adds an entry specified by an AddRequest to the LDAP server. 55 * 56 * @param addRequest The request 57 * @return An AddResponse 58 */ 59 public abstract AddResponse add( AddRequest addRequest ); 60 61 62 /** 63 * Adds an entry specified by a Dn and an array of Attribute's to the LDAP 64 * server. 65 * 66 * @param dn The distinguished name of the new entry 67 * @param attributes The attributes of the new entry 68 * @return An AddResponse 69 */ 70 public abstract AddResponse add( Dn dn, Attribute... attributes ); 71 72 73 /** 74 * Adds an entry specified by a Dn, to be filled out by a RequestBuilder, 75 * to the LDAP server. 76 * 77 * @param dn The distinguished name of the new entry 78 * @param requestBuilder The request builder 79 * @return An AddResponse 80 */ 81 public abstract AddResponse add( Dn dn, RequestBuilder<AddRequest> requestBuilder ); 82 83 84 /** 85 * Attempts to authenticate the supplied credentials against the first 86 * entry found matching the search criteria. If authentication fails, 87 * a PasswordException is thrown. If successful, the response is 88 * checked for warnings, and if present, a PasswordWarning is returned. 89 * Otherwise, null is returned. 90 * 91 * @param baseDn 92 * @param filter 93 * @param scope 94 * @param password 95 * @return 96 * @throws PasswordException 97 * @see {@link #authenticate(Dn, char[])} 98 * @see {@link #searchFirst(String, String, SearchScope, EntryMapper)} 99 */ 100 public PasswordWarning authenticate( String baseDn, String filter, SearchScope scope, char[] password ) throws PasswordException; 101 102 103 /** 104 * Attempts to authenticate the supplied credentials against the first 105 * entry found matching the search criteria. If authentication fails, 106 * a PasswordException is thrown. If successful, the response is 107 * checked for warnings, and if present, a PasswordWarning is returned. 108 * Otherwise, null is returned. 109 * 110 * @param baseDn 111 * @param filter 112 * @param scope 113 * @param password 114 * @return 115 * @throws PasswordException 116 * @see {@link #authenticate(Dn, char[])} 117 * @see {@link #searchFirst(Dn, String, SearchScope, EntryMapper)} 118 */ 119 public PasswordWarning authenticate( Dn baseDn, String filter, SearchScope scope, char[] password ) 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 baseDn 130 * @param filter 131 * @param scope 132 * @param password 133 * @return 134 * @throws PasswordException 135 * @see {@link #authenticate(Dn, char[])} 136 * @see {@link #searchFirst(SearchRequest, EntryMapper)} 137 */ 138 public PasswordWarning authenticate( SearchRequest searchRequest, char[] password ) throws PasswordException; 139 140 141 /** 142 * Attempts to authenticate the supplied credentials. If authentication 143 * fails, a PasswordException is thrown. If successful, the response is 144 * checked for warnings, and if present, a PasswordWarning is returned. 145 * Otherwise, null is returned. 146 * 147 * @param userDn The distinguished name of the user 148 * @param password The password 149 * @return A PasswordWarning or null 150 * @throws PasswordException If authentication fails 151 */ 152 public abstract PasswordWarning authenticate( Dn userDn, char[] password ) throws PasswordException; 153 154 155 /** 156 * Deletes an entry specified by a DeleteRequest from the LDAP server. 157 * 158 * @param deleteRequest The request 159 * @return A DeleteResponse 160 */ 161 public abstract DeleteResponse delete( DeleteRequest deleteRequest ); 162 163 164 /** 165 * Deletes an entry specified by Dn from the LDAP server. 166 * 167 * @param dn The distinguished name of the entry 168 * @return A DeleteResponse 169 */ 170 public abstract DeleteResponse delete( Dn dn ); 171 172 173 /** 174 * Deletes an entry specified by Dn, and whose request is configured 175 * by a RequestBuilder, from the LDAP server. 176 * 177 * @param dn The distinguished name of the entry 178 * @param requestBuilder The RequestBuilder 179 * @return A DeleteResponse 180 */ 181 public abstract DeleteResponse delete( Dn dn, RequestBuilder<DeleteRequest> requestBuilder ); 182 183 184 /** 185 * Executes the <code>connectionCallback</code>, supplying it a managed 186 * connection. 187 * 188 * @param connectionCallback The callback 189 * @return Whatever the callback returns 190 */ 191 public abstract <T> T execute( ConnectionCallback<T> connectionCallback ); 192 193 194 /** 195 * Performs a lookup, and supplies the matching entry to the 196 * <code>entryMapper</code>. 197 * 198 * @param dn The distinguished name of the entry 199 * @param entryMapper The mapper from entry to model object 200 * @return Whatever the <code>entryMapper</code> returns 201 */ 202 public abstract <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 * @return Whatever the <code>entryMapper</code> returns 213 */ 214 public abstract <T> T lookup( Dn dn, String[] attributes, EntryMapper<T> entryMapper ); 215 216 217 /** 218 * Modifies the password for <code>userDn</code> to 219 * <code>newPassword</code> using the admin account. 220 * 221 * @param userDn 222 * @param newPassword 223 * @throws PasswordException 224 * @see {@link #modifyPassword(Dn, char[], char[], boolean)} 225 */ 226 public void modifyPassword( Dn userDn, char[] newPassword ) 227 throws PasswordException; 228 229 230 /** 231 * Modifies the password for <code>userDn</code> from 232 * <code>oldPassword</code> to <code>newPassword</code>. 233 * 234 * @param userDn 235 * @param oldPassword 236 * @param newPassword 237 * @throws PasswordException 238 * @see {@link #modifyPassword(Dn, char[], char[], boolean)} 239 */ 240 public void modifyPassword( Dn userDn, char[] oldPassword, 241 char[] newPassword ) throws PasswordException; 242 243 244 /** 245 * Modifies the password for <code>userDn</code> from 246 * <code>oldPassword</code> to <code>newPassword</code>, optionally using 247 * an admin account. If <code>asAdmin</code> is true, then the operation 248 * is performed in admin context which means <code>oldPassword</code> is 249 * may be <code>null</code>. 250 * 251 * @param userDn The distinguished name of the user 252 * @param oldPassword The users old password (optional if asAdmin is true) 253 * @param newPassword The users new password 254 * @param asAdmin If true, execute in admin context 255 * @throws PasswordException If the password modification fails 256 */ 257 public abstract void modifyPassword( Dn userDn, char[] oldPassword, char[] newPassword, 258 boolean asAdmin ) throws PasswordException; 259 260 261 /** 262 * Modifies an entry specified by a ModifyRequest on the LDAP server. 263 * 264 * @param modifyRequest The request 265 * @return A ModifyResponse 266 */ 267 public abstract ModifyResponse modify( ModifyRequest modifyRequest ); 268 269 270 /** 271 * Modifies an entry specified by Dn, and whose request is configured 272 * by a RequestBuilder, on the LDAP server. 273 * 274 * @param dn The distinguished name of the entry 275 * @param requestBuilder The RequestBuilder 276 * @return A ModifyResponse 277 */ 278 public abstract ModifyResponse modify( Dn dn, RequestBuilder<ModifyRequest> requestBuilder ); 279 280 281 /** 282 * Checks the supplied response for its result code, and if not 283 * {@link ResultCodeEnum#SUCCESS}, an exception is thrown. This method is 284 * intened to be used inline: 285 * 286 * <pre> 287 * template.responseOrException( template.delete( dn ) ); 288 * </pre> 289 * 290 * @param response The response to check for success 291 * @return The supplied <code>response</code> 292 * @throws LdapRequestUnsuccessfulException If the response is not 293 * {@link ResultCodeEnum#SUCCESS} 294 */ 295 public abstract <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 303 * @param filter 304 * @param scope 305 * @param entryMapper 306 * @return The mapped entries 307 * @see {@link #search(SearchRequest, EntryMapper)} 308 */ 309 public abstract <T> List<T> search( String baseDn, FilterBuilder filter, SearchScope scope, 310 EntryMapper<T> entryMapper ); 311 312 313 /** 314 * Searches for the entries matching the supplied criteria, feeding the 315 * result into the <code>entryMapper</code>. 316 * 317 * @param baseDn 318 * @param filter 319 * @param scope 320 * @param entryMapper 321 * @return The mapped entries 322 * @see {@link #search(SearchRequest, EntryMapper)} 323 */ 324 public abstract <T> List<T> search( String baseDn, String filter, SearchScope scope, 325 EntryMapper<T> entryMapper ); 326 327 328 /** 329 * Searches for the entries matching the supplied criteria, feeding the 330 * result into the <code>entryMapper</code>. 331 * 332 * @param baseDn 333 * @param filter 334 * @param scope 335 * @param entryMapper 336 * @return The mapped entries 337 * @see {@link #search(SearchRequest, EntryMapper)} 338 */ 339 public abstract <T> List<T> search( Dn baseDn, FilterBuilder filter, SearchScope scope, 340 EntryMapper<T> entryMapper ); 341 342 343 /** 344 * Searches for the entries matching the supplied criteria, feeding the 345 * result into the <code>entryMapper</code>. 346 * 347 * @param baseDn 348 * @param filter 349 * @param scope 350 * @param entryMapper 351 * @return The mapped entries 352 * @see {@link #search(SearchRequest, EntryMapper)} 353 */ 354 public abstract <T> List<T> search( Dn baseDn, String filter, SearchScope scope, 355 EntryMapper<T> entryMapper ); 356 357 358 /** 359 * Searches for the entries matching the supplied criteria, feeding the 360 * result into the <code>entryMapper</code>, querying only the requested 361 * attributes. 362 * 363 * @param baseDn 364 * @param filter 365 * @param scope 366 * @param attributes 367 * @param entryMapper 368 * @return The mapped entries 369 * @see {@link #search(SearchRequest, EntryMapper)} 370 */ 371 public abstract <T> List<T> search( String baseDn, FilterBuilder filter, SearchScope scope, 372 String[] attributes, EntryMapper<T> entryMapper ); 373 374 375 /** 376 * Searches for the entries matching the supplied criteria, feeding the 377 * result into the <code>entryMapper</code>, querying only the requested 378 * attributes. 379 * 380 * @param baseDn 381 * @param filter 382 * @param scope 383 * @param attributes 384 * @param entryMapper 385 * @return The mapped entries 386 * @see {@link #search(SearchRequest, EntryMapper)} 387 */ 388 public abstract <T> List<T> search( String baseDn, String filter, SearchScope scope, 389 String[] attributes, EntryMapper<T> entryMapper ); 390 391 392 /** 393 * Searches for the entries matching the supplied criteria, feeding the 394 * result into the <code>entryMapper</code>, querying only the requested 395 * attributes. 396 * 397 * @param baseDn 398 * @param filter 399 * @param scope 400 * @param attributes 401 * @param entryMapper 402 * @return The mapped entries 403 * @see {@link #search(SearchRequest, EntryMapper)} 404 */ 405 public abstract <T> List<T> search( Dn baseDn, FilterBuilder filter, SearchScope scope, 406 String[] attributes, EntryMapper<T> entryMapper ); 407 408 409 /** 410 * Searches for the entries matching the supplied criteria, feeding the 411 * result into the <code>entryMapper</code>, querying only the requested 412 * attributes. 413 * 414 * @param baseDn 415 * @param filter 416 * @param scope 417 * @param attributes 418 * @param entryMapper 419 * @return The mapped entries 420 * @see {@link #search(SearchRequest, EntryMapper)} 421 */ 422 public abstract <T> List<T> search( Dn baseDn, String filter, SearchScope scope, 423 String[] attributes, EntryMapper<T> entryMapper ); 424 425 426 /** 427 * Searches for the entries matching the supplied 428 * <code>searchRequest</code>, feeding the result into the 429 * <code>entryMapper</code>. 430 * 431 * @param searchRequest The search request 432 * @param entryMapper The mapper 433 * @return The mapped entries 434 */ 435 public abstract <T> List<T> search( SearchRequest searchRequest, 436 EntryMapper<T> entryMapper ); 437 438 439 /** 440 * Searches for the first entry matching the supplied criteria, feeding the 441 * result into the <code>entryMapper</code>. 442 * 443 * @param baseDn 444 * @param filter 445 * @param scope 446 * @param entryMapper 447 * @return The mapped entries 448 * @see {@link #searchFirst(SearchRequest, EntryMapper)} 449 */ 450 public abstract <T> T searchFirst( String baseDn, FilterBuilder filter, SearchScope scope, 451 EntryMapper<T> entryMapper ); 452 453 454 /** 455 * Searches for the first entry matching the supplied criteria, feeding the 456 * result into the <code>entryMapper</code>. 457 * 458 * @param baseDn 459 * @param filter 460 * @param scope 461 * @param entryMapper 462 * @return The mapped entries 463 * @see {@link #searchFirst(SearchRequest, EntryMapper)} 464 */ 465 public abstract <T> T searchFirst( String baseDn, String filter, SearchScope scope, 466 EntryMapper<T> entryMapper ); 467 468 469 /** 470 * Searches for the first entry matching the supplied criteria, feeding the 471 * result into the <code>entryMapper</code>. 472 * 473 * @param baseDn 474 * @param filter 475 * @param scope 476 * @param entryMapper 477 * @return The mapped entries 478 * @see {@link #searchFirst(SearchRequest, EntryMapper)} 479 */ 480 public abstract <T> T searchFirst( Dn baseDn, FilterBuilder filter, SearchScope scope, 481 EntryMapper<T> entryMapper ); 482 483 484 /** 485 * Searches for the first entry matching the supplied criteria, feeding the 486 * result into the <code>entryMapper</code>. 487 * 488 * @param baseDn 489 * @param filter 490 * @param scope 491 * @param entryMapper 492 * @return The mapped entries 493 * @see {@link #searchFirst(SearchRequest, EntryMapper)} 494 */ 495 public abstract <T> T searchFirst( Dn baseDn, String filter, SearchScope scope, 496 EntryMapper<T> entryMapper ); 497 498 499 /** 500 * Searches for the first entry matching the supplied criteria, feeding the 501 * result into the <code>entryMapper</code>, querying only the requested 502 * attributes. 503 * 504 * @param baseDn 505 * @param filter 506 * @param scope 507 * @param attributes 508 * @param entryMapper 509 * @return The mapped entries 510 * @see {@link #searchFirst(SearchRequest, EntryMapper)} 511 */ 512 public abstract <T> T searchFirst( String baseDn, FilterBuilder filter, SearchScope scope, 513 String[] attributes, EntryMapper<T> entryMapper ); 514 515 516 /** 517 * Searches for the first entry matching the supplied criteria, feeding the 518 * result into the <code>entryMapper</code>, querying only the requested 519 * attributes. 520 * 521 * @param baseDn 522 * @param filter 523 * @param scope 524 * @param attributes 525 * @param entryMapper 526 * @return The mapped entries 527 * @see {@link #searchFirst(SearchRequest, EntryMapper)} 528 */ 529 public abstract <T> T searchFirst( String baseDn, String filter, SearchScope scope, 530 String[] attributes, EntryMapper<T> entryMapper ); 531 532 533 /** 534 * Searches for the first entry matching the supplied criteria, feeding the 535 * result into the <code>entryMapper</code>, querying only the requested 536 * attributes. 537 * 538 * @param baseDn 539 * @param filter 540 * @param scope 541 * @param attributes 542 * @param entryMapper 543 * @return The mapped entries 544 * @see {@link #searchFirst(SearchRequest, EntryMapper)} 545 */ 546 public abstract <T> T searchFirst( Dn baseDn, FilterBuilder filter, SearchScope scope, 547 String[] attributes, EntryMapper<T> entryMapper ); 548 549 550 /** 551 * Searches for the first entry matching the supplied criteria, feeding the 552 * result into the <code>entryMapper</code>, querying only the requested 553 * attributes. 554 * 555 * @param baseDn 556 * @param filter 557 * @param scope 558 * @param attributes 559 * @param entryMapper 560 * @return The mapped entries 561 * @see {@link #searchFirst(SearchRequest, EntryMapper)} 562 */ 563 public abstract <T> T searchFirst( Dn baseDn, String filter, SearchScope scope, 564 String[] attributes, EntryMapper<T> entryMapper ); 565 566 567 /** 568 * Searches for the first entry matching the supplied 569 * <code>searchRequest</code>, feeding the result into the 570 * <code>entryMapper</code>. This is basically the same as 571 * {@link #search(SearchRequest, EntryMapper)}, but is optimized by 572 * modifying the <code>searchRequest</code> to set its size limit to 1. 573 * The <code>searchRequest</code> is returned to its original size limit 574 * before this method returns (or throws an exception). 575 * 576 * @param searchRequest The search request 577 * @param entryMapper The mapper 578 * @return The mapped entry 579 */ 580 public abstract <T> T searchFirst( SearchRequest searchRequest, 581 EntryMapper<T> entryMapper ); 582 583 }