0
# Core LDAP Operations
1

2
Essential LDAP directory operations including connection management, authentication, and basic CRUD operations for interacting with LDAP directory servers.
3

4
## Capabilities
5

6
### Connection Management
7

8
#### LDAPConnection
9

10
Primary class for establishing and managing LDAP connections.
11

12
```java { .api }
13
/**
14
 * Primary class for establishing and managing LDAP connections
15
 */
16
public final class LDAPConnection implements FullLDAPInterface, LDAPConnectionInfo, ReferralConnector, Closeable {
17
    // Constructors
18
    public LDAPConnection() throws LDAPException;
19
    public LDAPConnection(String host, int port) throws LDAPException;
20
    public LDAPConnection(String host, int port, SSLSocketFactory socketFactory) throws LDAPException;
21
    public LDAPConnection(SocketFactory socketFactory, LDAPConnectionOptions connectionOptions, String host, int port) throws LDAPException;
22
    
23
    // Connection state
24
    public boolean isConnected();
25
    public String getConnectedAddress();
26
    public int getConnectedPort();
27
    public LDAPConnectionStatistics getConnectionStatistics();
28
    public void close();
29
    public void close(Control[] controls);
30
}
31
```
32

33
#### LDAPConnectionPool
34

35
Connection pooling implementation with load balancing and failover capabilities.
36

37
```java { .api }
38
/**
39
 * Connection pooling implementation with load balancing and failover
40
 */
41
public final class LDAPConnectionPool extends AbstractConnectionPool {
42
    // Constructors
43
    public LDAPConnectionPool(LDAPConnection connection, int initialConnections, int maxConnections) throws LDAPException;
44
    public LDAPConnectionPool(LDAPConnection connection, int initialConnections, int maxConnections, int initialConnectThreads) throws LDAPException;
45
    public LDAPConnectionPool(ServerSet serverSet, BindRequest bindRequest, int initialConnections, int maxConnections) throws LDAPException;
46
    
47
    // Pool management
48
    public LDAPConnection getConnection() throws LDAPException;
49
    public void releaseConnection(LDAPConnection connection);
50
    public void releaseDefunctConnection(LDAPConnection connection);
51
    public LDAPConnectionPoolStatistics getConnectionPoolStatistics();
52
    public int getCurrentAvailableConnections();
53
    public int getMaximumAvailableConnections();
54
    public void close();
55
}
56
```
57

58
#### LDAPConnectionOptions
59

60
Configuration options for LDAP connections.
61

62
```java { .api }
63
/**
64
 * Configuration options for LDAP connections
65
 */
66
public class LDAPConnectionOptions {
67
    public LDAPConnectionOptions();
68
    
69
    // Timeout settings
70
    public void setConnectTimeoutMillis(int connectTimeoutMillis);
71
    public int getConnectTimeoutMillis();
72
    public void setResponseTimeoutMillis(long responseTimeoutMillis);
73
    public long getResponseTimeoutMillis();
74
    
75
    // Connection behavior
76
    public void setAutoReconnect(boolean autoReconnect);
77
    public boolean autoReconnect();
78
    public void setBindWithDNRequiresPassword(boolean bindWithDNRequiresPassword);
79
    public boolean bindWithDNRequiresPassword();
80
    
81
    // SSL/TLS settings
82
    public void setSSLSocketVerifier(SSLSocketVerifier sslSocketVerifier);
83
    public SSLSocketVerifier getSSLSocketVerifier();
84
    
85
    // Connection pooling
86
    public void setMaxMessageSize(int maxMessageSize);
87
    public int getMaxMessageSize();
88
}
89
```
90

91
#### ServerSet Classes
92

93
Server selection strategies for connection pooling and high availability configurations.
94

95
```java { .api }
96
/**
97
 * Abstract base class for server selection strategies
98
 */
99
public abstract class ServerSet {
100
    public abstract LDAPConnection getConnection() throws LDAPException;
101
    public abstract LDAPConnection getConnection(LDAPConnectionPoolHealthCheck healthCheck) throws LDAPException;
102
    public ServerSet[] getServerSets();
103
}
104

105
/**
106
 * Single server configuration
107
 */
108
public class SingleServerSet extends ServerSet {
109
    public SingleServerSet(String host, int port);
110
    public SingleServerSet(String host, int port, SocketFactory socketFactory);
111
    public SingleServerSet(String host, int port, SocketFactory socketFactory, LDAPConnectionOptions connectionOptions);
112
    public SingleServerSet(String host, int port, SocketFactory socketFactory, LDAPConnectionOptions connectionOptions, BindRequest bindRequest, PostConnectProcessor postConnectProcessor);
113
}
114

115
/**
116
 * Round-robin server selection across multiple servers
117
 */
118
public class RoundRobinServerSet extends ServerSet {
119
    public RoundRobinServerSet(String[] hosts, int[] ports);
120
    public RoundRobinServerSet(String[] hosts, int[] ports, SocketFactory socketFactory);
121
    public RoundRobinServerSet(String[] hosts, int[] ports, SocketFactory socketFactory, LDAPConnectionOptions connectionOptions);
122
    public RoundRobinServerSet(String[] hosts, int[] ports, SocketFactory socketFactory, LDAPConnectionOptions connectionOptions, BindRequest bindRequest, PostConnectProcessor postConnectProcessor);
123
}
124

125
/**
126
 * Failover server selection with primary/backup servers
127
 */
128
public class FailoverServerSet extends ServerSet {
129
    public FailoverServerSet(ServerSet[] serverSets);
130
    public FailoverServerSet(ServerSet[] serverSets, long maxFailoverConnectionAgeMillis);
131
    public ServerSet[] getServerSets();
132
}
133

134
/**
135
 * Connects to the server with the fastest connection time
136
 */
137
public class FastestConnectServerSet extends ServerSet {
138
    public FastestConnectServerSet(String[] hosts, int[] ports);
139
    public FastestConnectServerSet(String[] hosts, int[] ports, SocketFactory socketFactory);
140
    public FastestConnectServerSet(String[] hosts, int[] ports, SocketFactory socketFactory, LDAPConnectionOptions connectionOptions);
141
}
142

143
/**
144
 * Connects to the server with the fewest established connections
145
 */
146
public class FewestConnectionsServerSet extends ServerSet {
147
    public FewestConnectionsServerSet(String[] hosts, int[] ports);
148
    public FewestConnectionsServerSet(String[] hosts, int[] ports, SocketFactory socketFactory);
149
    public FewestConnectionsServerSet(String[] hosts, int[] ports, SocketFactory socketFactory, LDAPConnectionOptions connectionOptions);
150
}
151

152
/**
153
 * Uses DNS SRV records to discover servers
154
 */
155
public class DNSSRVRecordServerSet extends ServerSet {
156
    public DNSSRVRecordServerSet(String serviceName, String providerURL);
157
    public DNSSRVRecordServerSet(String serviceName, String providerURL, long cacheTimeoutMillis);
158
    public DNSSRVRecordServerSet(String serviceName, String providerURL, long cacheTimeoutMillis, SocketFactory socketFactory, LDAPConnectionOptions connectionOptions);
159
}
160
```
161

162
### Basic LDAP Operations
163

164
#### Add Operations
165

166
```java { .api }
167
/**
168
 * Add a new entry to the directory
169
 * @param entry The entry to add
170
 * @return Result of the add operation
171
 * @throws LDAPException if the operation fails
172
 */
173
public LDAPResult add(Entry entry) throws LDAPException;
174

175
/**
176
 * Add a new entry to the directory with controls
177
 * @param addRequest Complete add request with controls
178
 * @return Result of the add operation
179
 * @throws LDAPException if the operation fails
180
 */
181
public LDAPResult add(AddRequest addRequest) throws LDAPException;
182

183
/**
184
 * Add request for LDAP add operations
185
 */
186
public class AddRequest extends UpdatableLDAPRequest {
187
    public AddRequest(String dn, Attribute... attributes);
188
    public AddRequest(String dn, Collection<Attribute> attributes);
189
    public AddRequest(Entry entry);
190
    
191
    public String getDN();
192
    public List<Attribute> getAttributes();
193
    public void addAttribute(Attribute attribute);
194
    public void addAttribute(String name, String... values);
195
}
196
```
197

198
#### Search Operations
199

200
```java { .api }
201
/**
202
 * Search for entries in the directory
203
 * @param baseDN The base DN for the search
204
 * @param scope The search scope
205
 * @param filter The search filter
206
 * @param attributes Attributes to return
207
 * @return Search results
208
 * @throws LDAPException if the search fails
209
 */
210
public SearchResult search(String baseDN, SearchScope scope, String filter, String... attributes) throws LDAPException;
211

212
/**
213
 * Search with a Filter object
214
 * @param baseDN The base DN for the search
215
 * @param scope The search scope
216
 * @param filter The search filter as Filter object
217
 * @param attributes Attributes to return
218
 * @return Search results
219
 * @throws LDAPException if the search fails
220
 */
221
public SearchResult search(String baseDN, SearchScope scope, Filter filter, String... attributes) throws LDAPException;
222

223
/**
224
 * Search with full request object
225
 * @param searchRequest Complete search request
226
 * @return Search results
227
 * @throws LDAPException if the search fails
228
 */
229
public SearchResult search(SearchRequest searchRequest) throws LDAPException;
230

231
/**
232
 * Search scope enumeration
233
 */
234
public enum SearchScope {
235
    BASE(0),
236
    ONE(1), 
237
    SUB(2),
238
    SUBORDINATE_SUBTREE(3);
239
}
240
```
241

242
#### Modify Operations
243

244
```java { .api }
245
/**
246
 * Modify an existing entry
247
 * @param dn The DN of the entry to modify
248
 * @param modifications The modifications to apply
249
 * @return Result of the modify operation
250
 * @throws LDAPException if the operation fails
251
 */
252
public LDAPResult modify(String dn, Modification... modifications) throws LDAPException;
253

254
/**
255
 * Modify with full request object
256
 * @param modifyRequest Complete modify request
257
 * @return Result of the modify operation
258
 * @throws LDAPException if the operation fails
259
 */
260
public LDAPResult modify(ModifyRequest modifyRequest) throws LDAPException;
261

262
/**
263
 * Represents a modification to an LDAP entry
264
 */
265
public class Modification {
266
    public Modification(ModificationType modificationType, String attributeName, String... values);
267
    public Modification(ModificationType modificationType, Attribute attribute);
268
    
269
    public ModificationType getModificationType();
270
    public String getAttributeName();
271
    public String[] getValues();
272
}
273

274
/**
275
 * Types of modifications
276
 */
277
public enum ModificationType {
278
    ADD(0),
279
    DELETE(1),
280
    REPLACE(2),
281
    INCREMENT(3);
282
}
283
```
284

285
#### Delete Operations
286

287
```java { .api }
288
/**
289
 * Delete an entry from the directory
290
 * @param dn The DN of the entry to delete
291
 * @return Result of the delete operation
292
 * @throws LDAPException if the operation fails
293
 */
294
public LDAPResult delete(String dn) throws LDAPException;
295

296
/**
297
 * Delete with full request object
298
 * @param deleteRequest Complete delete request
299
 * @return Result of the delete operation
300
 * @throws LDAPException if the operation fails
301
 */
302
public LDAPResult delete(DeleteRequest deleteRequest) throws LDAPException;
303

304
/**
305
 * Delete request for LDAP delete operations
306
 */
307
public class DeleteRequest extends UpdatableLDAPRequest {
308
    public DeleteRequest(String dn);
309
    
310
    public String getDN();
311
}
312
```
313

314
#### Compare Operations
315

316
```java { .api }
317
/**
318
 * Compare an attribute value against an entry
319
 * @param dn The DN of the entry
320
 * @param attributeName The attribute name
321
 * @param assertionValue The value to compare
322
 * @return Compare result
323
 * @throws LDAPException if the operation fails
324
 */
325
public CompareResult compare(String dn, String attributeName, String assertionValue) throws LDAPException;
326

327
/**
328
 * Compare with full request object
329
 * @param compareRequest Complete compare request
330
 * @return Compare result
331
 * @throws LDAPException if the operation fails
332
 */
333
public CompareResult compare(CompareRequest compareRequest) throws LDAPException;
334

335
/**
336
 * Result of a compare operation
337
 */
338
public class CompareResult extends LDAPResult {
339
    public boolean compareMatched();
340
}
341
```
342

343
#### Modify DN Operations
344

345
```java { .api }
346
/**
347
 * Modify the DN of an entry (rename/move)
348
 * @param dn Current DN of the entry
349
 * @param newRDN New relative DN
350
 * @param deleteOldRDN Whether to delete the old RDN
351
 * @return Result of the modify DN operation
352
 * @throws LDAPException if the operation fails
353
 */
354
public LDAPResult modifyDN(String dn, String newRDN, boolean deleteOldRDN) throws LDAPException;
355

356
/**
357
 * Modify DN with new superior
358
 * @param dn Current DN of the entry
359
 * @param newRDN New relative DN
360
 * @param deleteOldRDN Whether to delete the old RDN
361
 * @param newSuperiorDN New parent DN
362
 * @return Result of the modify DN operation
363
 * @throws LDAPException if the operation fails
364
 */
365
public LDAPResult modifyDN(String dn, String newRDN, boolean deleteOldRDN, String newSuperiorDN) throws LDAPException;
366
```
367

368
### Result Processing
369

370
#### LDAPResult
371

372
```java { .api }
373
/**
374
 * Generic result for LDAP operations
375
 */
376
public class LDAPResult {
377
    public int getMessageID();
378
    public ResultCode getResultCode();
379
    public String getDiagnosticMessage();
380
    public String getMatchedDN();
381
    public String[] getReferralURLs();
382
    public Control[] getResponseControls();
383
    public boolean hasResponseControl(String oid);
384
    public <T extends Control> T getResponseControl(Class<T> controlClass);
385
}
386

387
/**
388
 * LDAP result codes
389
 */
390
public enum ResultCode {
391
    SUCCESS(0),
392
    OPERATIONS_ERROR(1),
393
    PROTOCOL_ERROR(2),
394
    TIME_LIMIT_EXCEEDED(3),
395
    SIZE_LIMIT_EXCEEDED(4),
396
    COMPARE_FALSE(5),
397
    COMPARE_TRUE(6),
398
    AUTH_METHOD_NOT_SUPPORTED(7),
399
    STRONG_AUTH_REQUIRED(8),
400
    REFERRAL(10),
401
    ADMIN_LIMIT_EXCEEDED(11),
402
    UNAVAILABLE_CRITICAL_EXTENSION(12),
403
    CONFIDENTIALITY_REQUIRED(13),
404
    SASL_BIND_IN_PROGRESS(14),
405
    NO_SUCH_ATTRIBUTE(16),
406
    UNDEFINED_ATTRIBUTE_TYPE(17),
407
    INAPPROPRIATE_MATCHING(18),
408
    CONSTRAINT_VIOLATION(19),
409
    ATTRIBUTE_OR_VALUE_EXISTS(20),
410
    INVALID_ATTRIBUTE_SYNTAX(21),
411
    NO_SUCH_OBJECT(32),
412
    ALIAS_PROBLEM(33),
413
    INVALID_DN_SYNTAX(34),
414
    ALIAS_DEREFERENCING_PROBLEM(36),
415
    INAPPROPRIATE_AUTHENTICATION(48),
416
    INVALID_CREDENTIALS(49),
417
    INSUFFICIENT_ACCESS_RIGHTS(50),
418
    BUSY(51),
419
    UNAVAILABLE(52),
420
    UNWILLING_TO_PERFORM(53),
421
    LOOP_DETECT(54),
422
    NAMING_VIOLATION(64),
423
    OBJECT_CLASS_VIOLATION(65),
424
    NOT_ALLOWED_ON_NONLEAF(66),
425
    NOT_ALLOWED_ON_RDN(67),
426
    ENTRY_ALREADY_EXISTS(68),
427
    OBJECT_CLASS_MODS_PROHIBITED(69),
428
    AFFECTS_MULTIPLE_DSAS(71),
429
    OTHER(80);
430
}
431
```
432

433
#### SearchResult
434

435
```java { .api }
436
/**
437
 * Result of a search operation
438
 */
439
public class SearchResult extends LDAPResult {
440
    public List<SearchResultEntry> getSearchEntries();
441
    public List<SearchResultReference> getSearchReferences();
442
    public int getEntryCount();
443
    public int getReferenceCount();
444
}
445

446
/**
447
 * Individual entry from search results
448
 */
449
public class SearchResultEntry extends Entry {
450
    public SearchResultEntry(String dn, Attribute... attributes);
451
    public SearchResultEntry(String dn, Collection<Attribute> attributes);
452
    public Control[] getControls();
453
    public boolean hasControl(String oid);
454
}
455
```
456

457
### Asynchronous Operations
458

459
```java { .api }
460
/**
461
 * Asynchronous request ID for tracking operations
462
 */
463
public class AsyncRequestID {
464
    public int getMessageID();
465
    public OperationType getOperationType();
466
}
467

468
/**
469
 * Asynchronous search operations
470
 * @param searchRequest The search request
471
 * @param resultListener Listener for handling results
472
 * @return Request ID for tracking
473
 * @throws LDAPException if the operation fails
474
 */
475
public AsyncRequestID asyncSearch(SearchRequest searchRequest, AsyncSearchResultListener resultListener) throws LDAPException;
476

477
/**
478
 * Listener interface for asynchronous search results
479
 */
480
public interface AsyncSearchResultListener extends AsyncResultListener {
481
    void searchEntryReturned(SearchResultEntry entry);
482
    void searchReferenceReturned(SearchResultReference reference);
483
    void searchResultReceived(AsyncRequestID requestID, SearchResult result);
484
}
485
```
486

487
## Usage Examples
488

489
### Basic Connection and Search
490

491
```java
492
import com.unboundid.ldap.sdk.*;
493

494
// Establish connection
495
LDAPConnection connection = new LDAPConnection("ldap.example.com", 389);
496

497
try {
498
    // Simple bind
499
    BindResult bindResult = connection.bind("cn=admin,dc=example,dc=com", "password");
500
    
501
    // Search for users
502
    SearchResult searchResult = connection.search(
503
        "ou=people,dc=example,dc=com",     // base DN
504
        SearchScope.ONE,                   // scope
505
        "(objectClass=inetOrgPerson)",     // filter
506
        "cn", "mail", "telephoneNumber"    // attributes
507
    );
508
    
509
    System.out.println("Found " + searchResult.getEntryCount() + " entries");
510
    
511
    for (SearchResultEntry entry : searchResult.getSearchEntries()) {
512
        System.out.println("DN: " + entry.getDN());
513
        System.out.println("CN: " + entry.getAttributeValue("cn"));
514
        System.out.println("Mail: " + entry.getAttributeValue("mail"));
515
        System.out.println("Phone: " + entry.getAttributeValue("telephoneNumber"));
516
        System.out.println("---");
517
    }
518
    
519
} finally {
520
    connection.close();
521
}
522
```
523

524
### Connection Pool Usage
525

526
```java
527
import com.unboundid.ldap.sdk.*;
528

529
// Create initial connection
530
LDAPConnection connection = new LDAPConnection("ldap.example.com", 389);
531
connection.bind("cn=admin,dc=example,dc=com", "password");
532

533
// Create connection pool
534
LDAPConnectionPool pool = new LDAPConnectionPool(connection, 5, 10);
535

536
try {
537
    // Use pool for operations
538
    SearchResult result = pool.search(
539
        "dc=example,dc=com",
540
        SearchScope.SUB,
541
        "(cn=John*)"
542
    );
543
    
544
    // Pool automatically manages connections
545
    System.out.println("Available connections: " + pool.getCurrentAvailableConnections());
546
    
547
} finally {
548
    pool.close();
549
}
550
```
551

552
### Adding Entries
553

554
```java
555
import com.unboundid.ldap.sdk.*;
556

557
LDAPConnection connection = new LDAPConnection("ldap.example.com", 389);
558

559
try {
560
    connection.bind("cn=admin,dc=example,dc=com", "password");
561
    
562
    // Create new entry
563
    Entry newEntry = new Entry(
564
        "cn=Jane Smith,ou=people,dc=example,dc=com",
565
        new Attribute("objectClass", "inetOrgPerson"),
566
        new Attribute("cn", "Jane Smith"),
567
        new Attribute("sn", "Smith"),
568
        new Attribute("givenName", "Jane"),
569
        new Attribute("mail", "jane.smith@example.com"),
570
        new Attribute("telephoneNumber", "+1-555-0123")
571
    );
572
    
573
    // Add entry
574
    LDAPResult addResult = connection.add(newEntry);
575
    
576
    if (addResult.getResultCode() == ResultCode.SUCCESS) {
577
        System.out.println("Entry added successfully");
578
    } else {
579
        System.err.println("Add failed: " + addResult.getDiagnosticMessage());
580
    }
581
    
582
} catch (LDAPException e) {
583
    System.err.println("LDAP operation failed: " + e.getMessage());
584
    System.err.println("Result code: " + e.getResultCode());
585
} finally {
586
    connection.close();
587
}
588
```
589

590
### Modifying Entries
591

592
```java
593
import com.unboundid.ldap.sdk.*;
594

595
LDAPConnection connection = new LDAPConnection("ldap.example.com", 389);
596

597
try {
598
    connection.bind("cn=admin,dc=example,dc=com", "password");
599
    
600
    // Create modifications
601
    Modification[] mods = {
602
        new Modification(ModificationType.REPLACE, "mail", "jane.doe@example.com"),
603
        new Modification(ModificationType.ADD, "description", "Software Engineer"),
604
        new Modification(ModificationType.DELETE, "telephoneNumber", "+1-555-0123")
605
    };
606
    
607
    // Apply modifications
608
    LDAPResult modifyResult = connection.modify("cn=Jane Smith,ou=people,dc=example,dc=com", mods);
609
    
610
    if (modifyResult.getResultCode() == ResultCode.SUCCESS) {
611
        System.out.println("Entry modified successfully");
612
    }
613
    
614
} finally {
615
    connection.close();
616
}
617
```