directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From smckin...@apache.org
Subject svn commit: r1776664 - in /directory/site/trunk/content/api/user-guide: 1.2-ldap-in-a-few-words.mdtext 1.3-apache-ldap-api-rational.mdtext 1.4-preparation-to-code.mdtext
Date Sat, 31 Dec 2016 00:12:44 GMT
Author: smckinney
Date: Sat Dec 31 00:12:44 2016
New Revision: 1776664

URL: http://svn.apache.org/viewvc?rev=1776664&view=rev
Log:
more proofs

Modified:
    directory/site/trunk/content/api/user-guide/1.2-ldap-in-a-few-words.mdtext
    directory/site/trunk/content/api/user-guide/1.3-apache-ldap-api-rational.mdtext
    directory/site/trunk/content/api/user-guide/1.4-preparation-to-code.mdtext

Modified: directory/site/trunk/content/api/user-guide/1.2-ldap-in-a-few-words.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/1.2-ldap-in-a-few-words.mdtext?rev=1776664&r1=1776663&r2=1776664&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/1.2-ldap-in-a-few-words.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/1.2-ldap-in-a-few-words.mdtext Sat Dec 31
00:12:44 2016
@@ -24,26 +24,26 @@ Notice: Licensed to the Apache Software
 
 # 1.2 - LDAP in a few words
 
-**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 technlology. It's been around since the 90's to mitigate **X.500**
complexities. 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 created and X.500
became obsolete.
 
-We will now use the term **LDAP** and **LDAP** server for respectively the protocole and
the server.
+We'll use the term **LDAP** to represent the protocol and **LDAP** server to represent the
server that implements it.
 
 ## 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.
+An **LDAP** server provides access to entries stored in a backend database. It provides a
mechanism for fast searching and retrieval of entries. Its data structure is hierarchical,
and uses a schema to manage the definition of the entry's data formats.
 
-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.
+An **LDAP** client must first connect to a server and disconnect when finished. Some operations
may be performed on the data itself, e.g. searches, modifications and deletions, along with
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 request to interact with them. This API is an exemple of what **LDAP** is very good
at : it access data in a fast way, across servers.
 
 ## 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.
+**LDAP** servers are fast for retrievals : having been designed specifically for this purpose.
But modifications can be costly. These characteristics must be understood when writing applications
using an **LDAP** server for data storage.
 
-Each entry is identified by it's position in the hierarchy, and we use what is called a **D**istinguished
**N**ame (or **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 a location within it's corresponding **D**irectory **I**nformation
**T**ree, and we use what's called a **D**istinguished **N**ame (or **Dn**) to describe its
address within it. The base entry, is known as the suffix, and all entries beneath it are
collectively known as the **DIT**.
 
 ## 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.
+**LDAP** is a part of the **IT** landscape and so it's unavoidable that we must deal with
it. **LDAP** servers are used to manage authentication, authorizations, demographic info and
more. It's very likely that you will have to write some code to access data over **LDAP**,
and existing **API**s aren't quite up to the task. This **LDAP API** has been designed to
simplify usage.
 
 ## 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.
+This was a very short introduction, there's more literature about **LDAP** on the web : [Wikipedia](http://en.wikipedia.org/wiki/LDAP)
provides a good starting point.

Modified: directory/site/trunk/content/api/user-guide/1.3-apache-ldap-api-rational.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/1.3-apache-ldap-api-rational.mdtext?rev=1776664&r1=1776663&r2=1776664&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/1.3-apache-ldap-api-rational.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/1.3-apache-ldap-api-rational.mdtext Sat Dec
31 00:12:44 2016
@@ -22,28 +22,28 @@ Notice: Licensed to the Apache Software
     specific language governing permissions and limitations
     under the License.
 
-# 1.3 - The Apache LDAP API rational
+# 1.3 - 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 :
+When creating a new **LDAP** **API**, we need to consider whether it's a duplication of effort;
there are already some libraries that do this. For example:
 
 * **JNDI** : the default **JDK** **API**
-* **Netscape** [LdapSdk](http://www.mozilla.org/directory/javasdk.html)
+* **Netscape** (a.k.a Mozilla) [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 ?
+What makes the development of this new *LDAP JAVA API* a valid effort, and **[NIH](http://en.wikipedia.org/wiki/Not_Invented_Here)**
syndrom?
 
-There are many reasons why we decided to start to work on such an **API**, and we will expose
them in this chapter.
+There are many reasons why we decided to start to work on this **API**, and we'll discuss
them throughout this chapter.
 
-## 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.
+## History
+The Apache Directory Server project was first using **JNDI**, but many of the internal **LDAP**
structures were developed internally, because **JNDI** was not well suited for **LDAP** usage.
 This meant it wasn't convenient for us to use these 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**.
+At some point, we needed to communicate with other **LDAP** servers without having using
**JNDI**, so we developed our own _LdapConnection_ class. This was the first step toward a
full **Java API** specifically designed for LDAP.
 
-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](https://blogs.oracle.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.
+Strangely enough when we were doing this, back in 2007, **Sun** people working on the **OpenDS**
project contacted us to ask if we'd be interested in helping them with the next version of
**JNDI** ([Resurrecting The Java LDAP Centric API](https://blogs.oracle.com/treydrake/entry/resurrecting_the_java_ldap_centric).
Sadly, this effort stalled, as the need for *JNDI2* was no longer a priority for **Sun**.
We decided to continue with our work but the 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*.
+The work began once again after the **OpenDS** project team's presentation at **LdapCon**
back in 2009 ([Towards a common LDAP API for the Java Platform](http://www.symas.com/ldapcon2009/papers/poitou1.shtml)).
The story repeated itself after **Oracle** bought **Sun** in 2010.
 
-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 :
+Despite these fits and starts, a consensus was reached on the need for a new **API** and
what it should do. We agreed on the key features for a new **LDAP API**:
 
 * A complete coverage of the **LDAP** protocol
 * A schema aware **API**
@@ -51,8 +51,8 @@ At least, we get some kind of convergenc
 * An **API** taking advantage of the new **Java** construction (generics, ellipsis, NIO)
 
 ## Result
-The newly defined **API** fulfill all those aspects. 
+This newly defined **API** fulfills all of these 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 wanted to make sure this **API** was made available to the masses. The Apache Software
Foundation values quality and community over code, which means the code is the result of a
collaborative work, our users being a necessary part of this collaboration. Every bug a user
finds, is an opportunity to provide a better version of the **API** for everyone.
 
-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
+In the end, we're proud to deliver a useful **API** that everyone can use, include our own
projects like the Apache Directory Server, Directory Studio and Fortress. 

Modified: directory/site/trunk/content/api/user-guide/1.4-preparation-to-code.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/1.4-preparation-to-code.mdtext?rev=1776664&r1=1776663&r2=1776664&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/1.4-preparation-to-code.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/1.4-preparation-to-code.mdtext Sat Dec 31
00:12:44 2016
@@ -24,11 +24,11 @@ Notice: Licensed to the Apache Software
 
 # 1.4 - Preparation to code
 
-In order to develop with the **Apache Directory LDAP API**, you first have to use a **Java
6** JDK or higher. 
+The **Apache Directory LDAP API** requires **Java 6** JDK or higher. 
 
-Second, you have to download the **[API](http://directory.apache.org/api/downloads.html)**.
This package contains not only the **LDAP API**, but also all the needed jars (like _commons-lang_,
_slf4j_...).
+Secondly, you must download the **[API](http://directory.apache.org/api/downloads.html)**.
This package contains the **LDAP API** plus all of its dependent jars (like _commons-lang_,
_slf4j_...).
 
-If you are using **Maven**, you don't even have to refer all the libraries that are found
in the package, they will be deduced automatically. You will just have to add a dependency
on _api-all.jar_ :
+If you're using **Maven**, add the following dependency on _api-all.jar_ :
 
     :::XML
     <dependency>
@@ -37,4 +37,4 @@ If you are using **Maven**, you don't ev
     </dependency>
 
 
-This is it, you should be ready to code !
\ No newline at end of file
+and all of its depedent jar files will be included automatically.  That's it, now you should
be ready to code!



Mime
View raw message