You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by bu...@apache.org on 2012/10/02 18:40:19 UTC
svn commit: r833770 - in /websites/staging/directory/trunk/content: ./
api/groovy-ldap-user-guide.html api/groovy-ldap.html
Author: buildbot
Date: Tue Oct 2 16:40:18 2012
New Revision: 833770
Log:
Staging update by buildbot for directory
Added:
websites/staging/directory/trunk/content/api/groovy-ldap-user-guide.html
websites/staging/directory/trunk/content/api/groovy-ldap.html
Modified:
websites/staging/directory/trunk/content/ (props changed)
Propchange: websites/staging/directory/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Tue Oct 2 16:40:18 2012
@@ -1 +1 @@
-1392920
+1393024
Added: websites/staging/directory/trunk/content/api/groovy-ldap-user-guide.html
==============================================================================
--- websites/staging/directory/trunk/content/api/groovy-ldap-user-guide.html (added)
+++ websites/staging/directory/trunk/content/api/groovy-ldap-user-guide.html Tue Oct 2 16:40:18 2012
@@ -0,0 +1,350 @@
+<!DOCTYPE html>
+<!--
+ 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.
+-->
+<html>
+ <head>
+ <title>Groovy LDAP User Guide — Apache Directory</title>
+
+ <link href="./../css/common.css" rel="stylesheet" type="text/css">
+ <link href="./../css/brown.css" rel="stylesheet" type="text/css">
+
+ </head>
+ <body>
+ <div id="container">
+ <div id="header">
+ <div id="subProjectsNavBar">
+ <a href="./../">
+
+ Apache Directory Project
+
+ </a>
+ |
+ <a href="./../apacheds">
+
+ ApacheDS
+
+ </a>
+ |
+ <a href="./../studio">
+
+ Apache Directory Studio
+
+ </a>
+ |
+ <a href="./../api">
+
+ <STRONG>Apache LDAP API</STRONG>
+
+ </a>
+ </div><!-- subProjectsNavBar -->
+ </div><!-- header -->
+ <div id="content">
+ <div id="leftColumn">
+
+<div id="navigation">
+
+ <h5>Latest Downloads</h5>
+ <ul>
+ <li><a href="./../api/downloads.html">Version 1.0.0-M11</a> <IMG src="./../images/new_badge.gif" alt="" style="margin-bottom:-3px;" border="0"></li>
+ </ul>
+ <h5>Getting Started</h5>
+ <ul>
+ <li><a href="./../api/vision.html">Vision</a></li>
+ <li><a href="./../api/java-api.html">Java API</a></li>
+ <li><a href="./../api/groovy-ldap.html">Groovy API</a></li>
+ </ul>
+ <h5>Documentation</h5>
+ <ul>
+ <li><a href="./../api/five-minutes-tutorial.html">Five minutes tutorial</a></li>
+ <li><a href="./../api/user-guide.html">User Guide</a></li>
+ <li><a href="./../api/gen-docs/latest/apidocs/">JavaDocs</a></li>
+ <li><a href="./../api/gen-docs/latest/">Generated Reports</a></li>
+ <li><a href="./../api/developer-guide.html">Developer Guide</a></li>
+ </ul>
+
+
+ <h5>Community</h5>
+ <ul>
+ <li><a href="./../contribute.html">How to Contribute</a></li>
+ <li><a href="./../team.html">Team</a></li>
+ <li><a href="./../original-project-proposal.html">Original Project Proposal</a></li>
+ </ul>
+ <h5>About Apache</h5>
+ <ul>
+ <li><a href="http://www.apache.org/">Apache</a></li>
+ <li><a href="http://www.apache.org/licenses/">License</a></li>
+ <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
+ <li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+ <li><a href="http://www.apache.org/security/">Security</a></li>
+ </ul>
+
+</div><!-- navigation -->
+
+ </div><!-- leftColumn -->
+ <div id="rightColumn">
+
+<h1>Groovy LDAP User Guide</h1>
+
+<blockquote>
+<p><strong>Note:</strong> This guide is work in progress and is written at the same time as Groovy LDAP integration developes. The API may change. Feedback highly welcome.</p>
+</blockquote>
+<div class="toc">
+<ul>
+<li><a href="#prerequisites">Prerequisites</a></li>
+<li><a href="#installation">Installation</a></li>
+<li><a href="#connection-to-an-ldap-server">Connection to an LDAP server</a></li>
+<li><a href="#basic-ldap-operations">Basic LDAP operations</a><ul>
+<li><a href="#ldap-add-operation">LDAP add operation</a></li>
+<li><a href="#ldap-delete-operation">LDAP delete operation</a></li>
+<li><a href="#ldap-search-operation">LDAP search operation</a></li>
+<li><a href="#ldap-compare-operation">LDAP compare operation</a></li>
+<li><a href="#ldap-modify-operation">LDAP modify operation</a></li>
+</ul>
+</li>
+<li><a href="#additions-to-the-original-ldap-api">Additions to the original LDAP API</a><ul>
+<li><a href="#ldapexists-checking-whether-an-entry-exist">LDAP.exists(...): Checking whether an entry exist</a></li>
+<li><a href="#ldapread-reading-an-entry-by-its-distinguished-name">LDAP.read(...): Reading an entry by its distinguished name</a></li>
+</ul>
+</li>
+<li><a href="#ldap-the-groovy-way">LDAP the Groovy way</a><ul>
+<li><a href="#performing-searches-with-closures">Performing searches with closures</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<h2 id="prerequisites">Prerequisites</h2>
+<ul>
+<li>Java SE 5 (JDK 1.5) or above</li>
+<li>Groovy 1.0 or above</li>
+</ul>
+<h2 id="installation">Installation</h2>
+<p>You only have to add the jar file <em>groovy-ldap.jar</em> with the <em>Groovy LDAP</em> classes to the class path. If you plan to write Groovy scripts whoich use the functionality, an easy option is to copy the library into the <em>lib</em> folder of your Groovy installation.</p>
+<p>That's it.</p>
+<h2 id="connection-to-an-ldap-server">Connection to an LDAP server</h2>
+<p>Main entry point is the class <em>LDAP</em> from the <em>org.apache.directory.groovyldap</em> package (contained in <em>groovy-ldap.jar</em>). You obtain an instance via a call to a static method <em>newInstance</em>, like this:</p>
+<div class="codehilite"><pre><span class="kr">import</span> <span class="nx">org</span><span class="p">.</span><span class="nx">apache</span><span class="p">.</span><span class="nx">directory</span><span class="p">.</span><span class="nx">groovyldap</span><span class="p">.</span><span class="nx">LDAP</span>
+
+<span class="nx">ldap</span> <span class="o">=</span> <span class="nx">LDAP</span><span class="p">.</span><span class="nx">newInstance</span><span class="p">(</span><span class="s1">'ldap://zanzibar:10389/'</span><span class="p">)</span>
+<span class="p">...</span>
+</pre></div>
+
+
+<p>The argument used here is the LDAP URL of your directory server and contains hostname and port. This method as shown above is for anonymous binds. A variant of it expects the bind name of a user and his/her credentials:</p>
+<div class="codehilite"><pre><span class="p">...</span>
+<span class="nx">ldap</span> <span class="o">=</span> <span class="nx">LDAP</span><span class="p">.</span><span class="nx">newInstance</span><span class="p">(</span><span class="s1">'ldap://zanzibar:10389/'</span><span class="p">,</span> <span class="s1">'uid=admin,ou=system'</span><span class="p">,</span> <span class="s1">'******'</span><span class="p">)</span>
+<span class="p">...</span>
+</pre></div>
+
+
+<p>Please note that <em>Groovy LDAP</em> uses JNDI and its configuration facilities. This means that if you provide a <em>jndi.properties</em> file in your class path, Groovy LDAP will take these parameters into account. This enables you to keep your user name and password outside of the script code, for instance.</p>
+<p>Like with JNDI with its <em>InitialContext</em>, calling newInstance will <em>not</em> connect to the LDAP server immediately. This means that an authentication will likely occur later (with the first operation).</p>
+<h2 id="basic-ldap-operations">Basic LDAP operations</h2>
+<p>Groovy LDAP basically supports the operations provided by the native LDAP protocol, with some exceptions:</p>
+<ul>
+<li>It is not necessary to connect explicitly to the server or to <em>bind</em>/<em>unbind</em>. Groovy LDAP performs these operations automatically.</li>
+<li>LDAP controls are not supported yet</li>
+<li>No asynchronous calls are supported yet. Consequently, no <em>abandon</em> operation is available in the API</li>
+</ul>
+<h3 id="ldap-add-operation">LDAP add operation</h3>
+<p>The <em>add</em> operation is used to create a new entry within the directory.</p>
+<p>One option in Groovy LDAP is to define the attribute values of the new entry as a Map. One <em>add</em> operation takes the distinguished name (DN) of the new entry (as a String) and the attributes map as parameters. Here is an example:</p>
+<div class="codehilite"><pre><span class="kr">import</span> <span class="nx">org</span><span class="p">.</span><span class="nx">apache</span><span class="p">.</span><span class="nx">directory</span><span class="p">.</span><span class="nx">groovyldap</span><span class="p">.</span><span class="nx">LDAP</span>
+
+<span class="nx">ldap</span> <span class="o">=</span> <span class="nx">LDAP</span><span class="p">.</span><span class="nx">newInstance</span><span class="p">(</span><span class="s1">'ldap://zanzibar:10389'</span><span class="p">,</span> <span class="s1">'uid=admin,ou=system'</span> <span class="p">,</span><span class="s1">'******'</span><span class="p">)</span>
+
+<span class="nx">assert</span> <span class="o">!</span> <span class="nx">ldap</span><span class="p">.</span><span class="nx">exists</span><span class="p">(</span><span class="s1">'cn=Heather Nova,dc=example,dc=com'</span><span class="p">)</span>
+
+<span class="c1">// define the attributes as a map</span>
+<span class="nx">attrs</span> <span class="o">=</span> <span class="p">[</span>
+ <span class="nx">objectclass</span><span class="o">:</span> <span class="p">[</span><span class="s1">'top'</span><span class="p">,</span> <span class="s1">'person'</span><span class="p">],</span>
+ <span class="nx">sn</span><span class="o">:</span> <span class="s1">'Nova'</span><span class="p">,</span>
+ <span class="nx">cn</span><span class="o">:</span> <span class="s1">'Heather Nova'</span>
+<span class="p">]</span>
+<span class="nx">ldap</span><span class="p">.</span><span class="nx">add</span><span class="p">(</span><span class="s1">'cn=Heather Nova,dc=example,dc=com'</span><span class="p">,</span> <span class="nx">attrs</span><span class="p">)</span>
+
+<span class="nx">assert</span> <span class="nx">ldap</span><span class="p">.</span><span class="nx">exists</span><span class="p">(</span><span class="s1">'cn=Heather Nova,dc=example,dc=com'</span><span class="p">)</span>
+</pre></div>
+
+
+<p>In the <em>assert</em> expressions, the <em>exists</em> method of Groovy LDAP is used. It checks whether an entry with this DN already exists (see below). </p>
+<p>If no error occurs, the script adds the following entry to the directory:</p>
+<div class="codehilite"><pre><span class="err">dn:</span> <span class="err">cn=Heather</span> <span class="err">Nova,dc=example,dc=com</span>
+<span class="err">cn:</span> <span class="err">Heather</span> <span class="err">Nova</span>
+<span class="err">sn:</span> <span class="err">Nova</span>
+<span class="err">objectClass:</span> <span class="err">person</span>
+<span class="err">objectClass:</span> <span class="err">top</span>
+</pre></div>
+
+
+<h3 id="ldap-delete-operation">LDAP delete operation</h3>
+<p>The <em>delete</em> operation is used to delete an existing entry within the directory. As in the original LDAP protocol, only the deletion of leaf entries is allowed. Deletion of a subtree of entries (for instance with the <em>Tree Delete Control</em>) is not supported yet.</p>
+<p>Here is an example script which uses the <em>delete</em> method from Groovy LDAP.</p>
+<div class="codehilite"><pre><span class="kr">import</span> <span class="nx">org</span><span class="p">.</span><span class="nx">apache</span><span class="p">.</span><span class="nx">directory</span><span class="p">.</span><span class="nx">groovyldap</span><span class="p">.</span><span class="nx">LDAP</span>
+
+<span class="nx">ldap</span> <span class="o">=</span> <span class="nx">LDAP</span><span class="p">.</span><span class="nx">newInstance</span><span class="p">(</span><span class="s1">'ldap://zanzibar:10389'</span><span class="p">,</span> <span class="s1">'uid=admin,ou=system'</span> <span class="p">,</span><span class="s1">'******'</span><span class="p">)</span>
+
+<span class="nx">assert</span> <span class="nx">ldap</span><span class="p">.</span><span class="nx">exists</span><span class="p">(</span><span class="s1">'cn=Heather Nova,dc=example,dc=com'</span><span class="p">)</span>
+
+<span class="c1">// delete the entry with the given DN</span>
+<span class="nx">ldap</span><span class="p">.</span><span class="k">delete</span><span class="p">(</span><span class="s1">'cn=Heather Nova,dc=example,dc=com'</span><span class="p">)</span>
+
+<span class="nx">assert</span> <span class="o">!</span><span class="nx">ldap</span><span class="p">.</span><span class="nx">exists</span><span class="p">(</span><span class="s1">'cn=Heather Nova,dc=example,dc=com'</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Note that if the given entry does not exist, calling <em>delete</em> throws a javax.naming.NameNotFoundException. This is different to JNDI, where no error will occur in this case. The behavior here imitates the original LDAP delete operation. In the example script, this will not occur due to the <em>assert</em> statements.</p>
+<h3 id="ldap-search-operation">LDAP search operation</h3>
+<div class="codehilite"><pre><span class="kr">import</span> <span class="nx">org</span><span class="p">.</span><span class="nx">apache</span><span class="p">.</span><span class="nx">directory</span><span class="p">.</span><span class="nx">groovyldap</span><span class="p">.</span><span class="o">*</span>
+
+<span class="nx">ldap</span> <span class="o">=</span> <span class="nx">LDAP</span><span class="p">.</span><span class="nx">newInstance</span><span class="p">(</span><span class="s1">'ldap://zanzibar:10389/'</span><span class="p">)</span>
+
+<span class="c1">// search op</span>
+<span class="nx">results</span> <span class="o">=</span> <span class="nx">ldap</span><span class="p">.</span><span class="nx">search</span><span class="p">(</span><span class="s1">'(objectClass=*)'</span><span class="p">,</span> <span class="s1">'dc=example,dc=com'</span><span class="p">,</span> <span class="nx">SearchScope</span><span class="p">.</span><span class="nx">ONE</span> <span class="p">)</span>
+<span class="nx">println</span> <span class="s2">"${results.size} entries found:"</span>
+<span class="k">for</span> <span class="p">(</span><span class="nx">entry</span> <span class="k">in</span> <span class="nx">results</span><span class="p">)</span> <span class="p">{</span>
+ <span class="nx">println</span> <span class="nx">entry</span><span class="p">.</span><span class="nx">dn</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>The output looks like:</p>
+<div class="codehilite"><pre><span class="mi">3</span> <span class="n">entries</span> <span class="n">found:</span>
+<span class="n">cn</span><span class="o">=</span><span class="n">Tori</span> <span class="n">Amos</span><span class="p">,</span><span class="n">dc</span><span class="o">=</span><span class="n">example</span><span class="p">,</span><span class="n">dc</span><span class="o">=</span><span class="n">com</span>
+<span class="n">cn</span><span class="o">=</span><span class="n">Kate</span> <span class="n">Bush</span><span class="p">,</span><span class="n">dc</span><span class="o">=</span><span class="n">example</span><span class="p">,</span><span class="n">dc</span><span class="o">=</span><span class="n">com</span>
+<span class="n">cn</span><span class="o">=</span><span class="n">Heather</span> <span class="n">Nova</span><span class="p">,</span><span class="n">dc</span><span class="o">=</span><span class="n">example</span><span class="p">,</span><span class="n">dc</span><span class="o">=</span><span class="n">com</span>
+</pre></div>
+
+
+<p>Learn more about options on how to search within a directory in the [Reference|5. Groovy LDAP Reference]</p>
+<h3 id="ldap-compare-operation">LDAP compare operation</h3>
+<p>The <em>compare</em> operation is used to check attribute value assertions.</p>
+<p>The following script adds an entry and uses <em>compare</em> several times to demonstrate the different matching rules for attribute type <em>cn</em> (case insensitive) and <em>userPassword</em> (case sensitive). </p>
+<div class="codehilite"><pre><span class="kr">import</span> <span class="nx">org</span><span class="p">.</span><span class="nx">apache</span><span class="p">.</span><span class="nx">directory</span><span class="p">.</span><span class="nx">groovyldap</span><span class="p">.</span><span class="nx">LDAP</span>
+
+<span class="nx">ldap</span> <span class="o">=</span> <span class="nx">LDAP</span><span class="p">.</span><span class="nx">newInstance</span><span class="p">(</span><span class="s1">'ldap://zanzibar:10389'</span><span class="p">,</span> <span class="s1">'uid=admin,ou=system'</span> <span class="p">,</span><span class="s1">'******'</span><span class="p">)</span>
+
+<span class="nx">assert</span> <span class="o">!</span> <span class="nx">ldap</span><span class="p">.</span><span class="nx">exists</span><span class="p">(</span><span class="s1">'cn=Heather Nova,dc=example,dc=com'</span><span class="p">)</span>
+
+<span class="c1">// define an entry for compare ops</span>
+<span class="nx">attrs</span> <span class="o">=</span> <span class="p">[</span>
+ <span class="nx">objectclass</span><span class="o">:</span> <span class="p">[</span><span class="s1">'top'</span><span class="p">,</span> <span class="s1">'person'</span><span class="p">],</span>
+ <span class="nx">sn</span><span class="o">:</span> <span class="s1">'Nova'</span><span class="p">,</span>
+ <span class="nx">cn</span><span class="o">:</span> <span class="s1">'Heather Nova'</span><span class="p">,</span>
+ <span class="nx">userPassword</span><span class="o">:</span> <span class="s1">'secret'</span>
+<span class="p">]</span>
+<span class="nx">ldap</span><span class="p">.</span><span class="nx">add</span><span class="p">(</span><span class="s1">'cn=Heather Nova,dc=example,dc=com'</span><span class="p">,</span> <span class="nx">attrs</span><span class="p">)</span>
+
+<span class="nx">assert</span> <span class="nx">ldap</span><span class="p">.</span><span class="nx">exists</span><span class="p">(</span><span class="s1">'cn=Heather Nova,dc=example,dc=com'</span><span class="p">)</span>
+
+<span class="nx">assert</span> <span class="nx">ldap</span><span class="p">.</span><span class="nx">compare</span><span class="p">(</span><span class="s1">'cn=Heather Nova,dc=example,dc=com'</span><span class="p">,</span> <span class="p">[</span><span class="nx">cn</span><span class="o">:</span> <span class="s1">'Heather Nova'</span><span class="p">]</span> <span class="p">)</span>
+<span class="nx">assert</span> <span class="nx">ldap</span><span class="p">.</span><span class="nx">compare</span><span class="p">(</span><span class="s1">'cn=Heather Nova,dc=example,dc=com'</span><span class="p">,</span> <span class="p">[</span><span class="nx">cn</span><span class="o">:</span> <span class="s1">'HEATHER NOVA'</span><span class="p">]</span> <span class="p">)</span>
+
+<span class="nx">assert</span> <span class="nx">ldap</span><span class="p">.</span><span class="nx">compare</span><span class="p">(</span><span class="s1">'cn=Heather Nova,dc=example,dc=com'</span><span class="p">,</span> <span class="p">[</span><span class="nx">userPassword</span><span class="o">:</span> <span class="s1">'secret'</span><span class="p">]</span> <span class="p">)</span>
+<span class="nx">assert</span> <span class="o">!</span> <span class="nx">ldap</span><span class="p">.</span><span class="nx">compare</span><span class="p">(</span><span class="s1">'cn=Heather Nova,dc=example,dc=com'</span><span class="p">,</span> <span class="p">[</span><span class="nx">userPassword</span><span class="o">:</span> <span class="s1">'SECRET'</span><span class="p">]</span> <span class="p">)</span>
+
+<span class="nx">ldap</span><span class="p">.</span><span class="k">delete</span><span class="p">(</span><span class="s1">'cn=Heather Nova,dc=example,dc=com'</span><span class="p">)</span>
+</pre></div>
+
+
+<h3 id="ldap-modify-operation">LDAP modify operation</h3>
+<p>I am not perfectly happy with the syntax for modify yet. Here are two calls that perform modifications against the entry added above:</p>
+<div class="codehilite"><pre><span class="kr">import</span> <span class="nx">org</span><span class="p">.</span><span class="nx">apache</span><span class="p">.</span><span class="nx">directory</span><span class="p">.</span><span class="nx">groovyldap</span><span class="p">.</span><span class="o">*</span>
+
+<span class="nx">ldap</span> <span class="o">=</span> <span class="nx">LDAP</span><span class="p">.</span><span class="nx">newInstance</span><span class="p">(</span><span class="s1">'ldap://zanzibar:10389'</span><span class="p">,</span> <span class="s1">'uid=admin,ou=system'</span> <span class="p">,</span><span class="s1">'secret'</span><span class="p">)</span>
+
+<span class="nx">dn</span> <span class="o">=</span> <span class="s1">'cn=Heather Nova,dc=example,dc=com'</span>
+
+<span class="c1">// Adding a single attribute</span>
+<span class="nx">descr</span> <span class="o">=</span> <span class="p">[</span> <span class="nx">description</span><span class="o">:</span> <span class="s1">'a singer-songwriter'</span> <span class="p">]</span>
+<span class="nx">ldap</span><span class="p">.</span><span class="nx">modify</span><span class="p">(</span><span class="nx">dn</span><span class="p">,</span> <span class="s1">'ADD'</span><span class="p">,</span> <span class="nx">descr</span><span class="p">)</span>
+
+<span class="c1">// performing two operations atomically</span>
+<span class="nx">mods</span> <span class="o">=</span> <span class="p">[</span>
+ <span class="p">[</span> <span class="s1">'REPLACE'</span><span class="p">,</span> <span class="p">[</span><span class="nx">description</span><span class="o">:</span> <span class="s1">'a singer-songwriter, born in Bermuda'</span><span class="p">]</span> <span class="p">],</span>
+ <span class="p">[</span> <span class="s1">'ADD'</span><span class="p">,</span> <span class="p">[</span><span class="nx">userPassword</span><span class="o">:</span> <span class="s1">'secret'</span><span class="p">]</span> <span class="p">]</span>
+<span class="p">]</span>
+<span class="nx">ldap</span><span class="p">.</span><span class="nx">modify</span><span class="p">(</span><span class="nx">dn</span><span class="p">,</span> <span class="nx">mods</span><span class="p">)</span>
+</pre></div>
+
+
+<p>The second call uses a list <em>mods</em> of modifications as an argument; each modification consists of a list of two elements (a pair): the modification type and a map with the attribute(s). </p>
+<p>Afterwards, the entry looks like this in the directory</p>
+<div class="codehilite"><pre><span class="err">dn:</span> <span class="err">cn=Heather</span> <span class="err">Nova,dc=example,dc=com</span>
+<span class="err">cn:</span> <span class="err">Heather</span> <span class="err">Nova</span>
+<span class="err">sn:</span> <span class="err">Nova</span>
+<span class="err">objectClass:</span> <span class="err">person</span>
+<span class="err">objectClass:</span> <span class="err">top</span>
+<span class="err">userpassword:</span> <span class="err">secret</span>
+<span class="err">description:</span> <span class="err">a</span> <span class="err">singer-songwriter,</span> <span class="err">born</span> <span class="err">in</span> <span class="err">Bermuda</span>
+</pre></div>
+
+
+<h2 id="additions-to-the-original-ldap-api">Additions to the original LDAP API</h2>
+<h3 id="ldapexists-checking-whether-an-entry-exist">LDAP.exists(...): Checking whether an entry exist</h3>
+<p>implemented, but not documented yet</p>
+<h3 id="ldapread-reading-an-entry-by-its-distinguished-name">LDAP.read(...): Reading an entry by its distinguished name</h3>
+<p>I have included a <em>read</em> operation as in the Netscape API -- note that there is nothing like that in LDAP (you have to perform a search for it). Nevertheless, it is quite handy to have it. In this example I have use an anonymous LDAP connection. My LDAP server allows me to read entries without user and password (which is quite common). </p>
+<div class="codehilite"><pre><span class="kr">import</span> <span class="nx">org</span><span class="p">.</span><span class="nx">apache</span><span class="p">.</span><span class="nx">directory</span><span class="p">.</span><span class="nx">groovyldap</span><span class="p">.</span><span class="nx">LDAP</span>
+
+<span class="nx">ldap</span> <span class="o">=</span> <span class="nx">LDAP</span><span class="p">.</span><span class="nx">newInstance</span><span class="p">(</span><span class="s2">"ldap://zanzibar:10389"</span><span class="p">)</span>
+
+<span class="c1">// Simple entry lookup via dn</span>
+<span class="nx">heather</span> <span class="o">=</span> <span class="nx">ldap</span><span class="p">.</span><span class="nx">read</span><span class="p">(</span><span class="s1">'cn=Heather Nova,dc=example,dc=com'</span><span class="p">)</span>
+
+<span class="nx">print</span> <span class="s2">"""</span>
+<span class="s2">DN: ${heather.dn}</span>
+<span class="s2">Common name: ${heather.cn}</span>
+<span class="s2">Object classes: ${heather.objectclass}</span>
+<span class="s2">"""</span>
+</pre></div>
+
+
+<p>The output (if this entry exists) is:</p>
+<div class="codehilite"><pre><span class="err">DN:</span> <span class="err">cn=Heather</span> <span class="err">Nova,dc=example,dc=com</span>
+<span class="err">Common</span> <span class="err">name:</span> <span class="err">Heather</span> <span class="err">Nova</span>
+<span class="err">Object</span> <span class="kd">class</span><span class="err">es:</span> <span class="err">["person",</span> <span class="err">"top"]</span>
+</pre></div>
+
+
+<h2 id="ldap-the-groovy-way">LDAP the Groovy way</h2>
+<h3 id="performing-searches-with-closures">Performing searches with closures</h3>
+<p>There is a search variant in the <em>LDAP</em> class comparable to <em>eachRow</em> in GSQL. It takes a closure as parameter. I have added the search base to the ldap URL. There is also a variant which takes the base and a scope (defaults to subtree). </p>
+<div class="codehilite"><pre><span class="kr">import</span> <span class="nx">org</span><span class="p">.</span><span class="nx">apache</span><span class="p">.</span><span class="nx">directory</span><span class="p">.</span><span class="nx">groovyldap</span><span class="p">.</span><span class="nx">LDAP</span>
+
+<span class="nx">ldap</span> <span class="o">=</span> <span class="nx">LDAP</span><span class="p">.</span><span class="nx">newInstance</span><span class="p">(</span><span class="s1">'ldap://zanzibar:10389/dc=example,dc=com'</span><span class="p">)</span>
+
+<span class="nx">ldap</span><span class="p">.</span><span class="nx">eachEntry</span> <span class="p">(</span><span class="s1">'(objectClass=person)'</span><span class="p">)</span> <span class="p">{</span> <span class="nx">person</span> <span class="o">-></span>
+ <span class="nx">println</span> <span class="nx">person</span><span class="p">.</span><span class="nx">cn</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>The output looks like:</p>
+<div class="codehilite"><pre><span class="n">Tori</span> <span class="n">Amos</span>
+<span class="n">Kate</span> <span class="n">Bush</span>
+<span class="n">Heather</span> <span class="n">Nova</span>
+</pre></div>
+
+ </div><!-- rightColumn -->
+ <div id="endContent"></div>
+ </div><!-- content -->
+ <div id="footer">© 2003-2012, <a href="http://www.apache.org">The Apache Software Foundation</a> - <a href="privacy-policy.html">Privacy Policy</a><br />
+ Apache Directory, ApacheDS, Apache Directory Server, Apache Directory Studio, Apache LDAP API, Apache Triplesec, Triplesec, Apache, the Apache feather logo, and the Apache Directory project logos are trademarks of The Apache Software Foundation.
+ </div>
+ </div><!-- container -->
+ </body>
+</html>
\ No newline at end of file
Added: websites/staging/directory/trunk/content/api/groovy-ldap.html
==============================================================================
--- websites/staging/directory/trunk/content/api/groovy-ldap.html (added)
+++ websites/staging/directory/trunk/content/api/groovy-ldap.html Tue Oct 2 16:40:18 2012
@@ -0,0 +1,199 @@
+<!DOCTYPE html>
+<!--
+ 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.
+-->
+<html>
+ <head>
+ <title>Five Minutes Tutorial — Apache Directory</title>
+
+ <link href="./../css/common.css" rel="stylesheet" type="text/css">
+ <link href="./../css/brown.css" rel="stylesheet" type="text/css">
+
+ </head>
+ <body>
+ <div id="container">
+ <div id="header">
+ <div id="subProjectsNavBar">
+ <a href="./../">
+
+ Apache Directory Project
+
+ </a>
+ |
+ <a href="./../apacheds">
+
+ ApacheDS
+
+ </a>
+ |
+ <a href="./../studio">
+
+ Apache Directory Studio
+
+ </a>
+ |
+ <a href="./../api">
+
+ <STRONG>Apache LDAP API</STRONG>
+
+ </a>
+ </div><!-- subProjectsNavBar -->
+ </div><!-- header -->
+ <div id="content">
+ <div id="leftColumn">
+
+<div id="navigation">
+
+ <h5>Latest Downloads</h5>
+ <ul>
+ <li><a href="./../api/downloads.html">Version 1.0.0-M11</a> <IMG src="./../images/new_badge.gif" alt="" style="margin-bottom:-3px;" border="0"></li>
+ </ul>
+ <h5>Getting Started</h5>
+ <ul>
+ <li><a href="./../api/vision.html">Vision</a></li>
+ <li><a href="./../api/java-api.html">Java API</a></li>
+ <li><a href="./../api/groovy-ldap.html">Groovy API</a></li>
+ </ul>
+ <h5>Documentation</h5>
+ <ul>
+ <li><a href="./../api/five-minutes-tutorial.html">Five minutes tutorial</a></li>
+ <li><a href="./../api/user-guide.html">User Guide</a></li>
+ <li><a href="./../api/gen-docs/latest/apidocs/">JavaDocs</a></li>
+ <li><a href="./../api/gen-docs/latest/">Generated Reports</a></li>
+ <li><a href="./../api/developer-guide.html">Developer Guide</a></li>
+ </ul>
+
+
+ <h5>Community</h5>
+ <ul>
+ <li><a href="./../contribute.html">How to Contribute</a></li>
+ <li><a href="./../team.html">Team</a></li>
+ <li><a href="./../original-project-proposal.html">Original Project Proposal</a></li>
+ </ul>
+ <h5>About Apache</h5>
+ <ul>
+ <li><a href="http://www.apache.org/">Apache</a></li>
+ <li><a href="http://www.apache.org/licenses/">License</a></li>
+ <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
+ <li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+ <li><a href="http://www.apache.org/security/">Security</a></li>
+ </ul>
+
+</div><!-- navigation -->
+
+ </div><!-- leftColumn -->
+ <div id="rightColumn">
+
+<h1>Groovy LDAP</h1>
+
+<p>Learn about an attempt to make LDAP available from Groovy scripts in a way, LDAP people would expect. </p>
+<div class="toc">
+<ul>
+<li><a href="#mission-statement">Mission Statement</a></li>
+<li><a href="#how-it-looks-like-in-groovy">How it looks like in Groovy</a><ul>
+<li><a href="#adding-an-entry">Adding an entry</a></li>
+<li><a href="#performing-an-ldap-search-with-a-closure">Performing an LDAP search with a closure</a></li>
+</ul>
+</li>
+<li><a href="#current-status">Current status</a><ul>
+<li><a href="#get-involved">Get involved</a></li>
+<li><a href="#alternatives">Alternatives</a></li>
+</ul>
+</li>
+<li><a href="#where-to-go-from-here">Where to go from here</a></li>
+</ul>
+</div>
+<p>Feel free to provide feedback: <a href="mailto:dev@directory.apache.org">dev@directory.apache.org</a></p>
+<blockquote>
+<p><strong>Note:</strong> 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.</p>
+</blockquote>
+<h2 id="mission-statement">Mission Statement</h2>
+<p>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. </p>
+<ul>
+<li>Why this? Learn more about the origin of this attempt <a href="6. Groovy LDAP Origin">here</a>. </li>
+</ul>
+<h2 id="how-it-looks-like-in-groovy">How it looks like in Groovy</h2>
+<p>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 <a href="2. Groovy LDAP User Guide">User Guide</a>.</p>
+<h3 id="adding-an-entry">Adding an entry</h3>
+<p>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:</p>
+<div class="codehilite"><pre><span class="nb">import</span> <span class="n">org</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">directory</span><span class="o">.</span><span class="n">groovyldap</span><span class="o">.</span><span class="n">LDAP</span>
+
+<span class="n">ldap</span> <span class="o">=</span> <span class="n">LDAP</span><span class="o">.</span><span class="n">newInstance</span><span class="p">(</span><span class="s">'ldap://zanzibar:10389'</span><span class="p">,</span> <span class="s">'uid=admin,ou=system'</span><span class="p">,</span> <span class="s">'******'</span><span class="p">)</span>
+
+<span class="n">heather</span> <span class="o">=</span> <span class="p">[</span>
+ <span class="n">objectclass:</span> <span class="p">[</span><span class="s">'top'</span><span class="p">,</span> <span class="s">'person'</span><span class="p">],</span>
+ <span class="n">sn:</span> <span class="s">'Nova'</span><span class="p">,</span>
+ <span class="n">cn:</span> <span class="s">'Heather Nova'</span>
+<span class="p">]</span>
+
+<span class="n">ldap</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s">'cn=Heather Nova,dc=example,dc=com'</span><span class="p">,</span> <span class="n">heather</span><span class="p">)</span>
+</pre></div>
+
+
+<p>In LDIF format, the entry in the directory looks like this afterwards.</p>
+<div class="codehilite"><pre><span class="err">dn:</span> <span class="err">cn=Heather</span> <span class="err">Nova,dc=example,dc=com</span>
+<span class="err">cn:</span> <span class="err">Heather</span> <span class="err">Nova</span>
+<span class="err">sn:</span> <span class="err">Nova</span>
+<span class="err">objectClass:</span> <span class="err">person</span>
+<span class="err">objectClass:</span> <span class="err">top</span>
+</pre></div>
+
+
+<h3 id="performing-an-ldap-search-with-a-closure">Performing an LDAP search with a closure</h3>
+<p>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:</p>
+<div class="codehilite"><pre>import org.apache.directory.groovyldap.LDAP
+
+ldap = LDAP.newInstance('ldap://zanzibar:10389/dc=example,dc=com')
+
+ldap.eachEntry (filter: '(objectClass=person)') { entry ->
+ println "<span class="cp">${</span><span class="n">entry</span><span class="o">.</span><span class="n">cn</span><span class="cp">}</span> (<span class="cp">${</span><span class="n">entry</span><span class="o">.</span><span class="n">dn</span><span class="cp">}</span>)"
+}
+</pre></div>
+
+
+<p>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:</p>
+<div class="codehilite"><pre><span class="n">Tori</span> <span class="n">Amos</span> <span class="p">(</span><span class="n">cn</span><span class="o">=</span><span class="n">Tori</span> <span class="n">Amos</span><span class="p">,</span><span class="n">dc</span><span class="o">=</span><span class="n">example</span><span class="p">,</span><span class="n">dc</span><span class="o">=</span><span class="n">com</span><span class="p">)</span>
+<span class="n">Kate</span> <span class="n">Bush</span> <span class="p">(</span><span class="n">cn</span><span class="o">=</span><span class="n">Kate</span> <span class="n">Bush</span><span class="p">,</span><span class="n">dc</span><span class="o">=</span><span class="n">example</span><span class="p">,</span><span class="n">dc</span><span class="o">=</span><span class="n">com</span><span class="p">)</span>
+<span class="n">Heather</span> <span class="n">Nova</span> <span class="p">(</span><span class="n">cn</span><span class="o">=</span><span class="n">Heather</span> <span class="n">Nova</span><span class="p">,</span><span class="n">dc</span><span class="o">=</span><span class="n">example</span><span class="p">,</span><span class="n">dc</span><span class="o">=</span><span class="n">com</span><span class="p">)</span>
+<span class="o">...</span>
+</pre></div>
+
+
+<h2 id="current-status">Current status</h2>
+<p>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. </p>
+<h3 id="get-involved">Get involved</h3>
+<p>Feel free to ask questions and provide feedback! Use the <a href="../mailing-lists-and-irc.html">Apache Directory mailing lists</a> for this purpose.</p>
+<p>For issue tracking, Groovy LDAP has a project within the <a href="http://issues.apache.org/jira/browse/DIRGROOVY">JIRA</a> installation of the Apache Software Foundation.</p>
+<h3 id="alternatives">Alternatives</h3>
+<p>There are other efforts to bring the Groovy and the LDAP World together.
+An interesting alternative to Groovy LDAP is Gldapo (<a href="http://gldapo.codehaus.org/">http://gldapo.codehaus.org/</a>)</p>
+<h2 id="where-to-go-from-here">Where to go from here</h2>
+<ul>
+<li><a href="1. Download Groovy LDAP">Download</a> a binary version including the source code</li>
+<li>Read the <a href="2. Groovy LDAP User Guide">User Guide</a> in order to understand which operations are already implemented, and how to use them</li>
+<li>Learn more about the <a href="3. Groovy LDAP Implementation">implementation</a></li>
+<li>Learn how to <a href="4. Groovy LDAP Building the software">build the software</a> on your own</li>
+</ul>
+
+ </div><!-- rightColumn -->
+ <div id="endContent"></div>
+ </div><!-- content -->
+ <div id="footer">© 2003-2012, <a href="http://www.apache.org">The Apache Software Foundation</a> - <a href="privacy-policy.html">Privacy Policy</a><br />
+ Apache Directory, ApacheDS, Apache Directory Server, Apache Directory Studio, Apache LDAP API, Apache Triplesec, Triplesec, Apache, the Apache feather logo, and the Apache Directory project logos are trademarks of The Apache Software Foundation.
+ </div>
+ </div><!-- container -->
+ </body>
+</html>
\ No newline at end of file