Emmanuel Lecharny wrote:
Hi guys,
I have spent my day switching the LDAP API documentation from confluence
to the new system Stefan has tested. It works like a charm !
I have created a PDF from the files you can find in
*https://svn.apache.org/repos/asf/directory
<http://svn.apache.org/viewvc/directory/>/documentation
<http://svn.apache.org/viewvc/directory/documentation/>/ldap-api-manuals
<http://svn.apache.org/viewvc/directory/documentation/ldap-api-manuals/>/trunk*,
and it has also been generated on /www/directory.apache.org/api.
Here is the available PDF :
http://people.apache.org/~elecharny/book.pdf
Ok it's not perfect yet :
- first a hell lot of documentation is missing...
- the links are'nt correctly generated (we have the text twice)
- we have some text larger than the pages
- If we have text after an image, there is a line break between the
image and the text
but the overall result is quite ok...
Feedback welcomed !
Did a quick read thru the first couple sections, fixed some simple typos and
such.
--
-- Howard Chu
CTO, Symas Corp. http://www.symas.com
Director, Highland Sun http://highlandsun.com/hyc/
Chief Architect, OpenLDAP http://www.openldap.org/project/
Index: 2-0-apache-ldap-api.confluence
===================================================================
--- 2-0-apache-ldap-api.confluence (revision 1186532)
+++ 2-0-apache-ldap-api.confluence (working copy)
@@ -1,3 +1,3 @@
h1. Apache LDAP API
-This chapter exposes the rational that drove us to design a new Java LDAP API.
+This chapter exposes the rationale that drove us to design a new Java LDAP API.
Index: chapter-2/2-3-the-apache-ldap-api-rational.confluence
===================================================================
--- chapter-2/2-3-the-apache-ldap-api-rational.confluence (revision
1186532)
+++ chapter-2/2-3-the-apache-ldap-api-rational.confluence (working copy)
@@ -1,32 +1,32 @@
-h2. The Apache LDAP API rational
+h2. The Apache LDAP API rationale
Once we start to think about creating a new *LDAP* *API*, the first thing that
comes to mind is that it could be a duplication of effort : there are already
many libraries offering almost everything needed to write *LDAP* code. Some of
them are :
* *JNDI* : the default *JDK* *API*
* *Netscape* [LdapSdk|http://www.mozilla.org/directory/javasdk.html]
* *OpenLDAP* [JLdap|http://www.openldap.org/jldap/]
-So what makes the development of a new *LDAP JAVA API* a valid effort, and not
another version of *[NIH|http://en.wikipedia.org/wiki/Not_Invented_Here]*
syndrom ?
+So what makes the development of a new *LDAP JAVA API* a valid effort, and not
another version of *[NIH|http://en.wikipedia.org/wiki/Not_Invented_Here]*
syndrome ?
There are many reasons why we decided to start to work on such an *API*, and
we will expose them in this chapter.
h3. history
-The Apache Directory Server project was first built on top of *JNDI*, but many
of the internal *LDAP* structure were developed internally, just because *JNDI*
was not designed specifically for *LDAP*, so it was not convenient for us to
use those structure. Step by step, all of the *LDAP* objects (_Attribute_,
_Entry_, _DN_, ...) were implemented again.
+The Apache Directory Server project was first built on top of *JNDI*, but many
of the internal *LDAP* structures were developed internally, just because
*JNDI* was not designed specifically for *LDAP*, so it was not convenient for
us to use those structures. Step by step, all of the *LDAP* objects
(_Attribute_, _Entry_, _DN_, ...) were implemented again.
At some point, we needed to communicate with another *LDAP* server without
having to go through *JNDI*, so we developed our own _LdapConnection_ class.
This was the last step toward a full *Java API*.
-Strange enough, at the very same time in 2007, the *Sun* people working on
*OpenDS* contacted us to know if we would agree to work on what would have
become the next version of *JNDI* ([Resurrecting The Java LDAP Centric
API|http://blogs.sun.com/treydrake/entry/resurrecting_the_java_ldap_centric]).
Sadly, this effort soon staled, as it seemed that *JNDI2* was not anymore an
urgency for *Sun*. We decided to go on but the pace was slow.
+Strange enough, at the very same time in 2007, the *Sun* people working on
*OpenDS* contacted us to know if we would agree to work on what would have
become the next version of *JNDI* ([Resurrecting The Java LDAP Centric
API|http://blogs.sun.com/treydrake/entry/resurrecting_the_java_ldap_centric]).
Sadly, this effort soon stalled, as it seemed that *JNDI2* was not anymore an
urgency for *Sun*. We decided to go on but the pace was slow.
We started again to work on this API with the *OpenDS* team in 2009, and did a
presentation during the 2009 *LdapCon* ([Towards a common LDAP API for the Java
Platform|http://www.symas.com/ldapcon2009/papers/poitou1.shtml]). The story
repeated itself with *Oracle* buying *Sun* in 2010, after months of valuable
collaboration with *Sun*.
-At least, we get some kind of convergence in many aspects of the *API*. We
agreed on some of the key features the new *LDAP API* should offer :
+At least, we got some kind of convergence in many aspects of the *API*. We
agreed on some of the key features the new *LDAP API* should offer :
* A complete coverage of the *LDAP* protocol
* A schema aware *API*
* An easy to use *API*
* An *API* taking advantage of the new *Java* construction (generics,
ellipsis, NIO)
h3. Result
-The newly defined *API* fulfill all those aspects.
+The newly defined *API* fulfills all those aspects.
-We also wanted to make this *API* available for the masses. The Apache
Software Foundation value quality and community over code, which means we think
that the code is the result of a collaborative work, our users being a part of
this collaboration. Every bug a user find, it's an opportunity to provide a
better version of the *API*.
+We also wanted to make this *API* available for the masses. The Apache
Software Foundation values quality and community over code, which means we
think that the code is the result of a collaborative work, our users being a
part of this collaboration. Every bug a user finds is an opportunity to provide
a better version of the *API*.
-At he end, we are proud to deliver an *API* which is used in the Apache
Directory Server, but also in the Ldap Browser.
\ No newline at end of file
+At the end, we are proud to deliver an *API* which is used in the Apache
Directory Server, but also in the Ldap Browser.
Index: chapter-2/2-2-ldap-in-a-few-words.confluence
===================================================================
--- chapter-2/2-2-ldap-in-a-few-words.confluence (revision 1186532)
+++ chapter-2/2-2-ldap-in-a-few-words.confluence (working copy)
@@ -2,26 +2,26 @@
h3. Introduction
-*LDAP* is not a new technlology. It has been around since mid 1990, as a way
to mitigate the complexity of the *X.500* based servers access. It's name is an
acronym for *L{*}ightweight *D{*}irectory *A{*}ccess *P{*}rotocol. Soon after
the first standard has been issued, the first full *LDAP* server was written
(ie, X.500 was pushed out of the equation).
+*LDAP* is not a new technology. It has been around since the mid 1990s, as a
way to mitigate the complexity of the *X.500* based servers access. Its name is
an acronym for *L{*}ightweight *D{*}irectory *A{*}ccess *P{*}rotocol. Soon
after the first standard was issued, the first full *LDAP* server was written
(i.e., X.500 was pushed out of the equation).
-We will now use the term *LDAP* and *LDAP* server for respectively the
protocole and the server.
+We will now use the term *LDAP* and *LDAP* server for respectively the
protocol and the server.
h3. Features
-A *LDAP* server provides access to entries, stored in a backend. It offers an
interrogation mechanism allowing fast retrieval of entries. The data structure
is hierarchical, and we use a schema to manage the content of entries, plus the
organisation of data.
+A *LDAP* server provides access to data contained in entries, stored in a
backend database. It offers an interrogation mechanism allowing fast retrieval
of entries. The data structure is hierarchical, and we use a schema to manage
the content of entries, plus the organisation of data.
A *LDAP* client first has to connect to the server, and disconnect at the end.
Some operations can be done on data, searches, modification and deletion, among
a few others.
-*LDAP* servers are extensible, but they all use a common protocol which makes
it easy for users to request them. This API is an exemple of what *LDAP* is
very good at : access data in a fast way, across servers.
+*LDAP* servers are extensible, but they all use a common protocol which makes
it easy for users to query them. This API is an example of what *LDAP* is very
good at : accessing data quickly, across servers.
h3. Characteristics
*LDAP* servers are fast for retrievals : they have been designed for this
purpose. On the other hand, modifications can be costly. This has to be
understood when writing an application using a *LDAP* server as a backend.
-Each entry is identified by it's position in the hierarchy, and we use what is
called a *D{*}istinguished *N{*}ame (or *[DIRAPI:Dn]*) to describe this
position in the tree. The base is also named the *DIT*, or *D{*}irectory
*I{*}nformation *T{*}ree.
+Each entry is identified by it's position in the hierarchy, and we use what is
called a *D{*}istinguished *N{*}ame (or *[DIRAPI:Dn]*) to describe this
position in the tree. The database is also named the *DIT*, or *D{*}irectory
*I{*}nformation *T{*}ree.
h3. Programming
-Nowadays, *LDAP* is a part of the *IT* and it's difficult to avoid having to
deal with it. *LDAP* servers are used to manage authentication, mainly, but
also authorization, and more. It's very likely that you will have to write some
code to access such a *LDAP* server, and the existing *API* are a bit
cumbersome. This new *LDAP API* has been defined to facilitate this kind of
tasks.
+Nowadays, *LDAP* is a part of the *IT* and it's difficult to avoid having to
deal with it. *LDAP* servers are used to manage authentication, mainly, but
also authorization, and more. It's very likely that you will have to write some
code to access such a *LDAP* server, and the existing *APIs* are a bit
cumbersome. This new *LDAP API* has been defined to facilitate this kind of
tasks.
h3. Going further
-This was a very short introduction, you can find more literature about *LDAP*
on the web : [Wikipedia|http://en.wikipedia.org/wiki/LDAP] gives you a good
starting point with many valid pointers.
\ No newline at end of file
+This was a very short introduction, you can find more literature about *LDAP*
on the web : [Wikipedia|http://en.wikipedia.org/wiki/LDAP] gives you a good
starting point with many valid pointers.
Index: chapter-2/2-1-java-and-ldap.confluence
===================================================================
--- chapter-2/2-1-java-and-ldap.confluence (revision 1186532)
+++ chapter-2/2-1-java-and-ldap.confluence (working copy)
@@ -1,12 +1,12 @@
h2. Java and LDAP
-Most developer will, at some point, face the tricky task to communicate with a
*LDAP* server. *LDAP* seems to be a very simple technology, but when you get
deep into it, you realize that many aspects are not well known, and not so easy
to deal with.
+Most developers will, at some point, face the tricky task to communicate with
a *LDAP* server. *LDAP* seems to be a very simple technology, but when you get
deep into it, you realize that many aspects are not well known, and not so easy
to deal with.
-Java is most certainly the number one language used in the enterprise, for
around 10 years now. Some even call it the new *Cobol* !
+Java is most certainly the number one language used in the enterprise, for
around 10 years now. Some even call it the new *COBOL* !
-Those two facts make it necessary to be able to communicate with a *LDAP*
server in *Java*. This is ware a convenient *API* is useful, and this is why we
decided to provide this *API*.
+Those two facts make it necessary to be able to communicate with a *LDAP*
server in *Java*. This is where a convenient *API* is useful, and this is why
we decided to provide this *API*.
-Of course, there are alternatives, like *JNDI*. We truly believe that those
alternative aren't helping users to cope with the complexity of *LDAP*, at
least they are not giving a hand to users. For instance, *JNDI* semantic are
far awy from *LDAP semantic. Let's see how different it is :
+Of course, there are alternatives, like *JNDI*. We truly believe that those
alternative aren't helping users to cope with the complexity of *LDAP*, at
least they are not giving a hand to users. For instance, *JNDI* semantics are
far away from *LDAP* semantics. Let's see how different they are :
* _Bind_ : used in *LDAP* to authenticate a user, and to create an entry in
*JNDI*
* _Unbind_ : close the *LDAP* session in *LDAP*, delete an entry in *JNDI*
@@ -14,10 +14,10 @@
* Various properties have to be set in *JNDI* in order to connect or tweak the
_Search_ operation, which is not convenient
* _Attributes_ is case sensitive by default in *JNDI*, and they aren't schema
aware
* _Name_ in *JNDI* are not able to do a valid comparison in *JNDI*
-* _NamingEnumeration_ have to be explcitly closed in *JNDI*, as they aren't
closed when you disconnect, leading to some resource leaks.
+* _NamingEnumeration_ have to be explicitly closed in *JNDI*, as they aren't
closed when you disconnect, leading to some resource leaks.
Some of those problems are also true for the existing *LDAP API*.
-All in all, writing application including some *LDAP* operations in *Java* is
just a painful task for most of the developers.
+All in all, writing applications including some *LDAP* operations in *Java* is
just a painful task for most developers.
-Our target is to provide a better *API*, that will help them getting efficient
with their *LDAP* interaction.
\ No newline at end of file
+Our target is to provide a better *API*, that will help developers get more
efficient with their *LDAP* interaction.
Index: 3-0-basic-ldap-api-usage.confluence
===================================================================
--- 3-0-basic-ldap-api-usage.confluence (revision 1186532)
+++ 3-0-basic-ldap-api-usage.confluence (working copy)
@@ -1,5 +1,5 @@
h1. Basic LDAP API usage
-We provide three different set of methods to send requests to the *LDAP*
server :
+We provide three different sets of methods to send requests to the *LDAP*
server :
* A first set which is the simplest, where the methods don't return a
response, except the _search_ and _compare_ methods
* A second set, for advanced users, giving full control to the user
-* A third set allowing the user to send asynchronous requests.
\ No newline at end of file
+* A third set allowing the user to send asynchronous requests.
Index: 1-0-introduction.confluence
===================================================================
--- 1-0-introduction.confluence (revision 1186532)
+++ 1-0-introduction.confluence (working copy)
@@ -3,11 +3,11 @@
h2. About this guide
Getting started. Learn how to use Apache LDAP API 1.0 to connect to your
favorite LDAP server. See how you can use this API to run tests in
-conjonction with ApacheDS 2.0.
+conjunction with ApacheDS 2.0.
h2. Audience
This guide is primarily for people new to LDAP API, or people who want to
-migrate from JNDO to a new and powerful LDAP API. We do not expect users
+migrate from JNDI to a new and powerful LDAP API. We do not expect users
to have a deep knowledge about LDAP, but this guide is not intended to be
a LDAP tutorial either.
