0
# UnboundID LDAP SDK for Java
1

2
The UnboundID LDAP SDK for Java is a comprehensive, high-performance Java library providing full LDAPv3 protocol support for communicating with LDAP directory servers. It offers extensive features including connection pooling, schema handling, persistence framework, and built-in support for standard LDAP controls and extensions.
3

4
## Package Information
5

6
- **Package Name**: com.unboundid:unboundid-ldapsdk
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Version**: 6.0.11
10
- **Requirements**: Java 7+
11
- **Dependencies**: None (zero external dependencies)
12
- **Installation**: 
13
  ```xml
14
  <dependency>
15
    <groupId>com.unboundid</groupId>
16
    <artifactId>unboundid-ldapsdk</artifactId>
17
    <version>6.0.11</version>
18
  </dependency>
19
  ```
20

21
## Core Imports
22

23
```java
24
import com.unboundid.ldap.sdk.LDAPConnection;
25
import com.unboundid.ldap.sdk.LDAPConnectionPool;
26
import com.unboundid.ldap.sdk.LDAPException;
27
import com.unboundid.ldap.sdk.LDAPResult;
28
import com.unboundid.ldap.sdk.Entry;
29
import com.unboundid.ldap.sdk.Attribute;
30
import com.unboundid.ldap.sdk.DN;
31
import com.unboundid.ldap.sdk.Filter;
32
import com.unboundid.ldap.sdk.SearchRequest;
33
import com.unboundid.ldap.sdk.SearchResult;
34
import com.unboundid.ldap.sdk.SearchResultEntry;
35
```
36

37
## Basic Usage
38

39
```java
40
import com.unboundid.ldap.sdk.*;
41

42
// Establish connection
43
LDAPConnection connection = new LDAPConnection("ldap.example.com", 389);
44

45
try {
46
    // Bind (authenticate)
47
    connection.bind("cn=admin,dc=example,dc=com", "password");
48
    
49
    // Search for entries
50
    SearchResult searchResult = connection.search(
51
        "dc=example,dc=com",           // base DN
52
        SearchScope.SUB,               // scope
53
        "(objectClass=person)",        // filter
54
        "cn", "mail"                   // attributes to return
55
    );
56
    
57
    // Process results
58
    for (SearchResultEntry entry : searchResult.getSearchEntries()) {
59
        System.out.println("DN: " + entry.getDN());
60
        System.out.println("CN: " + entry.getAttributeValue("cn"));
61
        System.out.println("Mail: " + entry.getAttributeValue("mail"));
62
    }
63
    
64
    // Add new entry
65
    Entry newEntry = new Entry(
66
        "cn=John Doe,ou=people,dc=example,dc=com",
67
        new Attribute("objectClass", "inetOrgPerson"),
68
        new Attribute("cn", "John Doe"),
69
        new Attribute("sn", "Doe"),
70
        new Attribute("mail", "john.doe@example.com")
71
    );
72
    connection.add(newEntry);
73
    
74
} finally {
75
    connection.close();
76
}
77
```
78

79
## Architecture
80

81
The UnboundID LDAP SDK is built around several key architectural components:
82

83
- **Connection Management**: Core connection classes (`LDAPConnection`, `LDAPConnectionPool`) with built-in load balancing and failover
84
- **Operation Framework**: Request/response pattern for all LDAP operations with comprehensive error handling
85
- **Type System**: Rich data types (`Entry`, `Attribute`, `DN`, `Filter`) with full validation and manipulation support
86
- **Extension System**: Pluggable architecture for LDAP controls and extended operations
87
- **Schema Framework**: Complete schema representation and validation capabilities
88
- **Persistence Layer**: Object-relational mapping for treating LDAP entries as Java objects
89
- **LDIF Support**: Full LDAP Data Interchange Format reading and writing capabilities
90

91
## Capabilities
92

93
### Core LDAP Operations
94

95
Essential LDAP directory operations including connection management, connection pooling with ServerSet load balancing strategies, and basic CRUD operations.
96

97
```java { .api }
98
// Primary connection class
99
public final class LDAPConnection implements FullLDAPInterface, LDAPConnectionInfo, ReferralConnector, Closeable {
100
    public LDAPConnection(String host, int port) throws LDAPException;
101
    public LDAPResult bind(String bindDN, String password) throws LDAPException;
102
    public LDAPResult add(Entry entry) throws LDAPException;
103
    public SearchResult search(String baseDN, SearchScope scope, String filter, String... attributes) throws LDAPException;
104
    public LDAPResult modify(String dn, Modification... modifications) throws LDAPException;
105
    public LDAPResult delete(String dn) throws LDAPException;
106
    public void close();
107
}
108

109
// Connection pooling for high-performance applications
110
public final class LDAPConnectionPool extends AbstractConnectionPool {
111
    public LDAPConnectionPool(LDAPConnection connection, int initialConnections, int maxConnections) throws LDAPException;
112
    public LDAPConnectionPoolStatistics getConnectionPoolStatistics();
113
    public void close();
114
}
115
```
116

117
[Core LDAP Operations](./core-operations.md)
118

119
### Authentication and Security
120

121
Comprehensive authentication mechanisms including simple bind, SASL (PLAIN, CRAM-MD5, DIGEST-MD5, GSSAPI, SCRAM-SHA family, OAUTHBEARER, EXTERNAL), and SSL/TLS support.
122

123
```java { .api }
124
// Simple authentication
125
public class SimpleBindRequest extends BindRequest {
126
    public SimpleBindRequest(String bindDN, String password);
127
}
128

129
// SASL authentication mechanisms
130
public abstract class SASLBindRequest extends BindRequest {
131
    // Base class for SASL mechanisms
132
}
133

134
public class CRAMMD5BindRequest extends SASLBindRequest {
135
    public CRAMMD5BindRequest(String authenticationID, String password);
136
}
137

138
public class GSSAPIBindRequest extends SASLBindRequest {
139
    public GSSAPIBindRequest(String authenticationID, String authorizationID);
140
}
141
```
142

143
[Authentication and Security](./authentication.md)
144

145
### Data Types and Manipulation
146

147
Core LDAP data types for representing directory entries, attributes, and distinguished names.
148

149
```java { .api }
150
// LDAP entry representation
151
public class Entry {
152
    public Entry(String dn, Attribute... attributes);
153
    public Entry(DN dn, Collection<Attribute> attributes);
154
    public String getDN();
155
    public Attribute getAttribute(String name);
156
    public String getAttributeValue(String name);
157
    public Collection<Attribute> getAttributes();
158
}
159

160
// LDAP attribute with values
161
public class Attribute {
162
    public Attribute(String name, String... values);
163
    public Attribute(String name, byte[]... values);
164
    public String getName();
165
    public String[] getValues();
166
    public byte[][] getValueByteArrays();
167
}
168

169
// Distinguished Name parsing and manipulation
170
public class DN {
171
    public DN(String dnString) throws LDAPException;
172
    public RDN[] getRDNs();
173
    public DN getParent();
174
    public boolean isAncestorOf(DN dn, boolean strict);
175
}
176
```
177

178
[Data Types and Manipulation](./data-types.md)
179

180
### Search and Filtering
181

182
Advanced search capabilities with filter construction, result processing, and search controls.
183

184
```java { .api }
185
// Search request construction
186
public class SearchRequest extends UpdatableLDAPRequest {
187
    public SearchRequest(String baseDN, SearchScope scope, String filter, String... attributes);
188
    public SearchRequest(String baseDN, SearchScope scope, Filter filter, String... attributes);
189
    public void setControls(Control... controls);
190
    public void setSizeLimit(int sizeLimit);
191
    public void setTimeLimit(int timeLimitSeconds);
192
}
193

194
// LDAP filter construction and parsing
195
public class Filter {
196
    public static Filter createEqualityFilter(String attributeName, String assertionValue);
197
    public static Filter createSubstringFilter(String attributeName, String subInitial, String[] subAny, String subFinal);
198
    public static Filter createANDFilter(Filter... filters);
199
    public static Filter createORFilter(Filter... filters);
200
    public static Filter create(String filterString) throws LDAPException;
201
}
202
```
203

204
[Search and Filtering](./search.md)
205

206
### Schema Management
207

208
Complete LDAP schema representation, validation, and manipulation capabilities.
209

210
```java { .api }
211
// Complete schema representation
212
public class Schema {
213
    public static Schema getSchema(LDAPConnection connection) throws LDAPException;
214
    public static Schema getSchema(LDAPConnection connection, String subschemaSubentryDN) throws LDAPException;
215
    public Set<AttributeTypeDefinition> getAttributeTypes();
216
    public Set<ObjectClassDefinition> getObjectClasses();
217
    public EntryValidator getEntryValidator();
218
}
219

220
// Schema validation
221
public class EntryValidator {
222
    public List<String> validateEntry(Entry entry);
223
    public List<String> validateEntry(Entry entry, boolean checkMissingAttributes);
224
}
225
```
226

227
[Schema Management](./schema.md)
228

229
### Persistence Framework
230

231
Object-relational mapping system for treating LDAP entries as Java objects with annotations.
232

233
```java { .api }
234
// Main persister class
235
public class LDAPPersister<T> {
236
    public LDAPPersister(Class<T> type, LDAPInterface ldapInterface) throws LDAPPersistException;
237
    public T get(String dn) throws LDAPPersistException;
238
    public PersistedObjects<T> search(String baseDN, SearchScope scope, Filter filter) throws LDAPPersistException;
239
    public void add(T object) throws LDAPPersistException;
240
    public void modify(T object) throws LDAPPersistException;
241
    public void delete(T object) throws LDAPPersistException;
242
}
243

244
// Key annotations for object mapping
245
@Target({ElementType.TYPE})
246
@Retention(RetentionPolicy.RUNTIME)
247
public @interface LDAPObject {
248
    String[] objectClass();
249
    String structuralClass() default "";
250
}
251

252
@Target({ElementType.FIELD})
253
@Retention(RetentionPolicy.RUNTIME)
254
public @interface LDAPField {
255
    String attribute() default "";
256
    boolean inRDN() default false;
257
}
258
```
259

260
[Persistence Framework](./persistence.md)
261

262
### LDIF Processing
263

264
Complete support for LDAP Data Interchange Format (LDIF) reading, writing, and manipulation.
265

266
```java { .api }
267
// LDIF reading capabilities
268
public class LDIFReader implements Closeable {
269
    public LDIFReader(String filePath) throws IOException;
270
    public LDIFReader(InputStream inputStream);
271
    public LDIFRecord readLDIFRecord() throws IOException, LDIFException;
272
    public Entry readEntry() throws IOException, LDIFException;
273
    public LDIFChangeRecord readChangeRecord() throws IOException, LDIFException;
274
}
275

276
// LDIF writing capabilities  
277
public class LDIFWriter implements Closeable {
278
    public LDIFWriter(String filePath) throws IOException;
279
    public LDIFWriter(OutputStream outputStream);
280
    public void writeEntry(Entry entry) throws IOException;
281
    public void writeChangeRecord(LDIFChangeRecord changeRecord) throws IOException;
282
}
283
```
284

285
[LDIF Processing](./ldif.md)
286

287
### Controls and Extensions
288

289
Standard LDAP controls and extended operations for advanced directory functionality.
290

291
```java { .api }
292
// Standard LDAP controls
293
public class PagedResultsRequestControl extends Control {
294
    public PagedResultsRequestControl(int pageSize, ASN1OctetString cookie);
295
}
296

297
public class ServerSideSortRequestControl extends Control {
298
    public ServerSideSortRequestControl(SortKey... sortKeys);
299
}
300

301
// Extended operations
302
public class PasswordModifyExtendedRequest extends ExtendedRequest {
303
    public PasswordModifyExtendedRequest(String userIdentity, String oldPassword, String newPassword);
304
}
305

306
public class WhoAmIExtendedRequest extends ExtendedRequest {
307
    public WhoAmIExtendedRequest();
308
}
309
```
310

311
[Controls and Extensions](./controls-extensions.md)
312

313
## Common Patterns
314

315
### Connection Pooling
316
```java
317
// Create connection pool for high-performance applications
318
LDAPConnection connection = new LDAPConnection("ldap.example.com", 389);
319
connection.bind("cn=admin,dc=example,dc=com", "password");
320

321
LDAPConnectionPool pool = new LDAPConnectionPool(connection, 10, 20);
322
// Use pool for operations
323
// pool automatically manages connections
324
pool.close();
325
```
326

327
### Error Handling
328
```java
329
try {
330
    LDAPResult result = connection.add(entry);
331
    if (result.getResultCode() == ResultCode.SUCCESS) {
332
        System.out.println("Entry added successfully");
333
    }
334
} catch (LDAPException e) {
335
    System.err.println("LDAP operation failed: " + e.getMessage());
336
    System.err.println("Result code: " + e.getResultCode());
337
}
338
```
339

340
### Asynchronous Operations
341
```java
342
// Asynchronous search
343
AsyncRequestID requestID = connection.asyncSearch(
344
    searchRequest,
345
    new AsyncSearchResultListener() {
346
        public void searchEntryReturned(SearchResultEntry entry) {
347
            // Process each entry as it arrives
348
        }
349
        public void searchResultReceived(AsyncRequestID requestID, SearchResult result) {
350
            // Handle final result
351
        }
352
    }
353
);
354
```