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

[sm...@apache.org]

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!