content/api/user-guide/1.1-java-and-ldap.mdtext

Title: 1.1 - Java and LDAP
NavPrev: 1-introduction.html
NavPrevText: 1 - Introduction
NavUp: 1-introduction.html
NavUpText: 1 - Introduction
NavNext: 1.2-ldap-in-a-few-words.html
NavNextText: 1.2 - LDAP in a few words
Notice: Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at
    .
    http://www.apache.org/licenses/LICENSE-2.0
    .
    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.

# 1.1 - Java and LDAP
Most developers will at some point need to learn how to communicate with an **LDAP** server. It should be a very simple technology to use but isn't because many aspects are not well known.

Java is one of the most commonly used languages in the enterprise. Some call it the new **Cobol**!

These facts mean it's necessary to communicate over **LDAP** using **Java**. This is why a convenient **API** is necessary, so we created this **API** to fill the necessary gaps.

There are alternatives, like **JNDI**. But the alternatives aren't effective helping users cope with **LDAP**'s inherent complexities. **JNDI**'s semantics are very different from what's required for proper **LDAP** usage. For example:

* **Bind** : used in **LDAP** to authenticate a user but creates an entry in **JNDI**
* **Unbind** : closes the **LDAP** session in **LDAP** but deletes an entry in **JNDI**
* **Compare **: is mapped to a search in **JNDI** while its proper usage is to compare to determine if a targeted attribute value matches a particular value inside an **LDAP** entry. 
* Various properties have to be set in **JNDI** in order to connect or tweak the **Search** operation, which is not convenient
* **Attributes** are case sensitive by default in **JNDI** and not schema aware which is not compliant with LDAP standard.
* **Name** in **JNDI** can't do a valid comparison in **JNDI**
* **NamingEnumeration** must be explcitly closed in **JNDI**, and don't close automatically upon disconnect, which causes resource leakage to occur.

Some of these same problems exist for the other **LDAP API**s.  Other alternatives are no longer supported and/or lack a permissive license.

All in all, writing applications to perform basic **LDAP** operations in **Java** is a painful task for most developers.

Our target is to provide a better **API**, one that leads to correct and efficient usage of **LDAP** operation.