Title: Five Minutes Tutorial
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.

<h1>Groovy LDAP</h1>

Learn about an attempt to make LDAP available from Groovy scripts in a way, LDAP people would expect. 

[TOC]

Feel free to provide feedback: <mailto:dev@directory.apache.org>

>**Note:** Please note that this is not an official sub project of Apache Directory yet. There are no official releases. However if interest in this client library increases, it may become a sub project very soon.

## Mission Statement

Create a way to access LDAP from Groovy scripts, which is suitable for people familiar to LDAP. Primary audience are people who plan to write simple scripts against their LDAP servers. This is not about LDAP abstraction. The API should be comparable to the native LDAP library for C, in order to provide an easy start for the primary target group. Nevertheless it should "smell" like other Groovy integration solutions (namely GSQL) do. Especially the use of closures is planned. In order to reduce the number of dependencies, nothing besides Java SE and Groovy itself should be used. JNDI will therefore be used under the hood to communicate with LDAP. 

* Why this? Learn more about the origin of this attempt [here](groovy-ldap-origin.html). 

## How it looks like in Groovy 

Here are two example scripts which use Groovy LDAP in order to give you a first impression. Learn more about how to use Groovy LDAP in the [User Guide](groovy-ldap-user-guide.html).

### Adding an entry

The attribute values of an LDAP entry can be defined with the help of the expressive Map syntax of Groovy (\[DIRxSBOX:...\)). The following script uses the add operation to create a new entry in the directory:

    import org.apache.directory.groovyldap.LDAP

    ldap = LDAP.newInstance('ldap://zanzibar:10389', 'uid=admin,ou=system', '******')

    heather = [
      objectclass: ['top', 'person'],              
      sn: 'Nova',
      cn: 'Heather Nova'
    ]
    
    ldap.add('cn=Heather Nova,dc=example,dc=com', heather)

In LDIF format, the entry in the directory looks like this afterwards.

    dn: cn=Heather Nova,dc=example,dc=com
    cn: Heather Nova
    sn: Nova
    objectClass: person
    objectClass: top

### Performing an LDAP search with a closure 

Besides the operations found in the classic LDAP API, Groovy LDAP provides advanced functionality with the help of features specific to the Groovy language. Here is an example which performs a search operation, and executes the behavior given via a closure for each entry found:

    import org.apache.directory.groovyldap.LDAP

    ldap = LDAP.newInstance('ldap://zanzibar:10389/dc=example,dc=com')

    ldap.eachEntry (filter: '(objectClass=person)') { entry ->  
        println "${entry.cn} (${entry.dn})"
    }

The example also shows how to access attributes and the distinguished name (DN) of an entry (Map syntax, as well). The output looks like this:

    Tori Amos (cn=Tori Amos,dc=example,dc=com)
    Kate Bush (cn=Kate Bush,dc=example,dc=com)
    Heather Nova (cn=Heather Nova,dc=example,dc=com)
    ...

## Current status

Creation of the solution has just been started. We do not know, whether it will become an official project with releases and so (no official release yet). Even the name is not final yet. The current version only supports five of the LDAP operations (search, add, delete, compare, modify) explicitly. 

### Get involved

Feel free to ask questions and provide feedback! Use the [Apache Directory mailing lists](../mailing-lists-and-irc.html) for this purpose.

For issue tracking, Groovy LDAP has a project within the [JIRA](http://issues.apache.org/jira/browse/DIRGROOVY) installation of the Apache Software Foundation.

### Alternatives

There are other efforts to bring the Groovy and the LDAP World together.
An interesting alternative to Groovy LDAP is Gldapo (<http://gldapo.codehaus.org/>)

## Where to go from here

 * [Download](groovy-ldap-download.html) a binary version including the source code
 * Read the [User Guide](groovy-ldap-user-guide.html) in order to understand which operations are already implemented, and how to use them
 * Learn more about the [implementation](groovy-ldap-download.html#implementation)
 * Learn how to [build the software](groovy-ldap-download.html#building-the-software) on your own