You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by sm...@apache.org on 2016/12/31 02:55:46 UTC
svn commit: r1776679 - in /directory/site/trunk/content/api: ./ user-guide/
Author: smckinney
Date: Sat Dec 31 02:55:46 2016
New Revision: 1776679
URL: http://svn.apache.org/viewvc?rev=1776679&view=rev
Log:
more proofread
Modified:
directory/site/trunk/content/api/user-guide.mdtext
directory/site/trunk/content/api/user-guide/2.1-connection-disconnection.mdtext
directory/site/trunk/content/api/user-guide/2.2-binding-unbinding.mdtext
directory/site/trunk/content/api/user-guide/2.3-searching.mdtext
directory/site/trunk/content/api/user-guide/2.4-adding.mdtext
directory/site/trunk/content/api/user-guide/2.5-deleting.mdtext
directory/site/trunk/content/api/user-guide/2.6-modifying.mdtext
Modified: directory/site/trunk/content/api/user-guide.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide.mdtext?rev=1776679&r1=1776678&r2=1776679&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide.mdtext (original)
+++ directory/site/trunk/content/api/user-guide.mdtext Sat Dec 31 02:55:46 2016
@@ -20,10 +20,9 @@ Notice: Licensed to the Apache Software
<DIV class="note" markdown="1">
<strong>Work in progress</strong>
-
- * Pages with a (e) at the end of the title are empty pages.
- * Pages with a (...) at the end of the title are not yet completed.
- * Other pages are finished (but may be reviewed)
+Pages with a (e) at the end of the title are empty pages.
+Pages with a (...) at the end of the title are not yet completed.
+Other pages are finished (but may be reviewed).
</DIV>
This document is about the LDAP API, developed at the Apache Software Foundation. It's a replacement for outdated Java/LDAP libraries like ([jLdap](http://www.openldap.org/jldap/), [Mozilla LDAP SDK](http://www.mozilla.org/directory/) and [JNDI](http://www.oracle.com/technetwork/java/jndi/index.html)).
Modified: directory/site/trunk/content/api/user-guide/2.1-connection-disconnection.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/2.1-connection-disconnection.mdtext?rev=1776679&r1=1776678&r2=1776679&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/2.1-connection-disconnection.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/2.1-connection-disconnection.mdtext Sat Dec 31 02:55:46 2016
@@ -24,7 +24,7 @@ Notice: Licensed to the Apache Software
# 2.1 - Connection and disconnection
-**LDAP** is a protocol which requires the user to be connected - and likely identified - in order to be able to send requests to the server. We maintain this connection potentially forever. What make the **LDAP** protocol different from, say, the **HTTP** protocol is that the connection must be issued explicitly. Let's see how we do that.
+**LDAP** is a protocol which requires users to be connected - and likely identified (authenticated) - before sending requests to the server. This connection can potentially be maintained forever. What makes the **LDAP** protocol different from, say, the **HTTP** protocol is that the connections are issued explicitly. Here's we'll see how that is done.
## Opening a connection
@@ -32,18 +32,18 @@ We can open a secure or a standard conne
### Standard connection
-We can first establish a standard connection, where the data are sent and received in clear text (encoded in ASN.1 BER, but still not encrypted). This example expose the way it's done :
+We can first establish a standard connection, where the data is sent and received in clear text (encoded in ASN.1 BER, but not encrypted). This example shows how it's done:
:::Java
LdapConnection connection = new LdapNetworkConnection( "localhost", 389 );
-Here, we just created an unsafe connection locally, using the 389 port. Quite simple...
+Here we created an unsafe connection locally using the 389 port. Which is quite simple to do but not safe because data is not encrypted.
### Secure connection
-Although the **LDAPS** (**LDAP** over **SSL**) is now considered as deprecated, many people continue to use it. The big advantage of not using **LDAPS** is that you don't need to setup two different listening ports (one for **LDAP** -389- and another one for **LDAPS** -636- ).
+Although the **LDAPS** (**LDAP** over **SSL**) is now considered as deprecated, many people still use it. The big advantage of not using **LDAPS** is that you don't need two different listening ports (one for **LDAP** -389- and another one for **LDAPS** -636- ).
-The only difference with the previous example is that we have to tell the connection that it has to use **SSL**, by passing **_true_** as a third parameter (incidentally, passing **_false_** set a unsafe connection).
+The only difference with the previous example is that we tell the connection to use **SSL**, by passing **_true_** as a third parameter (incidentally, passing **_false_** sets an unsafe connection).
Here is an example
@@ -52,7 +52,7 @@ Here is an example
## Maintaining the connection opened
-We keep the connection opened for a limited period of time, defaulting to 30 seconds. This might be not long enough, so one can change this delay by calling the _setTimeOut()_ method :
+We keep the connection open for a limited period of time, defaulting to 30 seconds. This might be not long enough, so one can change this delay by calling the _setTimeOut()_ method :
:::Java
LdapConnection connection = new LdapNetworkConnection( "localhost", 389 );
@@ -60,11 +60,11 @@ We keep the connection opened for a limi
...
connection.close();
->**Note:** Setting a value equal or below 0 will keep the connection opened for ever (or a soon as the connection is not explicitly closed).
+>**Note:** Setting a value equal or below 0 will keep the connection open forever (assuming the connection is not explicitly closed by the client).
## Closing the connection
-Once you don't need to use the connection anymore (remember that hodling a connection keeps a session opened on the server, and a socket opened between the client and the server), then you have to close it. This is done by calling the _close()_ method :
+Once the connection is no longer needed (remember that holding a connection keeps the session open on the server and a socket is held open between the client and the server), then you must close it. This is done by calling the _close()_ method :
:::Java
LdapConnection connection = new LdapNetworkConnection( "localhost", 389 );
@@ -106,9 +106,9 @@ This process is slightly more complex gi
LdapConnectionPool pool = new LdapConnectionPool(
new DefaultPoolableLdapConnectionFactory( factory ), poolConfig ) );
-This will create a pool of connections that will be pre-authenticated. If you do not setName and setCredentials, then the pool will contain unauthenticated connections.
+This creates a pool of connections that are pre-authenticated. If you don't setName and setCredentials, then the pool will contain unauthenticated connections.
-The DefaultPoolableLdapConnectionFactory is sufficient for many cases. However, certain operations result in modifications to the connection itself. For example, when the pool is created, a bind operation will occur with the credentials supplied as part of the config. If you borrow a connection and perform a bind yourself, that would result in the connection being re-bound as a different user. The next time that connection gets borrowed, things are likely to break. If you perform any operation that results in a modification of the connection, you should instead use ValidatingPoolableLdapConnectionFactory:
+The DefaultPoolableLdapConnectionFactory is sufficient for many cases. However some operations result in modifications to the connection itself. For example, when the pool is created, a bind operation will occur with the credentials supplied as part of the config. If you borrow a connection and perform a bind yourself, that would result in the connection being re-bound as a different user. The next time that connection gets borrowed, things are likely to break. If you perform any operation that results in a modification of the connection, you should instead use ValidatingPoolableLdapConnectionFactory:
:::Java
...
@@ -116,4 +116,4 @@ The DefaultPoolableLdapConnectionFactory
new ValidatingPoolableLdapConnectionFactory( factory ), poolConfig ) );
...
-A connection pool using this factory will unbind and rebind any connection that was modified while it was borrowed (_see the javadoc for more detail_). This will be slower due to the additional operations, but not too significantly.
+A connection pool using this factory will unbind and rebind any connection that was modified while it was borrowed (_see the javadoc for more detail_). This will be slower due to the additional operations, but not significantly.
Modified: directory/site/trunk/content/api/user-guide/2.2-binding-unbinding.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/2.2-binding-unbinding.mdtext?rev=1776679&r1=1776678&r2=1776679&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/2.2-binding-unbinding.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/2.2-binding-unbinding.mdtext Sat Dec 31 02:55:46 2016
@@ -24,38 +24,38 @@ Notice: Licensed to the Apache Software
# 2.2 - Binding and unbinding
-In **LDAP**, if one wants to access the data in the base, the common way to do it is to bind on the server. However, it's important to understand that binding is a different beast than connection.
+In **LDAP**, if one wants to access the data in the base, the common way to do it is to bind to the server. However, it's important to understand that binding is a different from connecting.
-Creating a connection to a **LDAP** server is just about opening a socket between the client and the server. You just need to provide the address and the port.
+Creating a connection to an **LDAP** server is opens a socket between the client and the server. You must provide the address and the port in order to do this.
-The **bind** operation, on the other hand, create a _Session_ which will hold some user's information for the time being of the session. Those information are quite limited, they include the user's credentials.
+The **bind** operation, on the other hand, creates a _Session_ which will hold user information for the duration of the session. This information is limited, but includes the user's credentials.
-But it's important to know that it's possible to bind as anonymous, providing no name and password, and still be able to request the server (note though that the server can forbid such anonymous bind).
+But it's important to know that it's possible to bind anonymously, which doesn't require a user or password, and still be able to send requests to the server (although the server can forbid anonymous binds).
-Once the user has finished to request the server, then he can unbind, destroying his session on the server. That does not close the connection, because, one more time, _bind != connection_.
+Once the user has finished interacting with the server, they can unbind, destroying the session held on the server. This operation does not close the connection, because, again _bind != connection_!
## Binding
-You have two possible types of binds in *LDAP* :
+There are two possible types of binds in *LDAP*:
* **Simple**
* **SASL**
-The first one is based on a user/password being send to the server, which check that they are valid. It's also possible to proceed an Anonymous bind explicitly.
+The first one is based on a userid/password sent to the server, which verifies the credentials are valid. It's also possible to proceed with an anonymous bind explicitly.
-The second one is more complex, and is used if you want to proceed an authentication with some specific mechanism, like **DIGEST-MD5**, **Kerberos** or certificate based.
+The second type is more complicated, and is used whenever authentication with a specific mechanism, like **DIGEST-MD5**, **Kerberos** or certificate based is required.
### Simple Bind
-One can issue three kind of Simple bind :
+One can issue three kinds of simple binds:
* _anonymous bind_
* _name/password bind_
* _unauthenticated authentication bind_
-The first one is the easiest one, but depending on the server configuration, it will be accepted or rejected (all the servers don't allow anonymous binds)
+The first one is the easiest, but depending on the server's configuration, will be accepted or rejected (not all servers allow anonymous binds)
-Most of the time, the _bind_ operation will not return anything. You will get bound, or you'll get an _LdapException_ if an error is met.
+Most of the time, the _bind_ operation will not return anything. You either get bound, or will receive an _LdapException_ if an error occurs.
-Issuing an anonymous bind is very simple, you just provide no user name nor any password :
+Issuing an anonymous bind is simple, you neither provide a user or password:
:::Java
@Test
@@ -64,7 +64,7 @@ Issuing an anonymous bind is very simple
connection.bind();
}
-Issuing a user/password bind is just slightly more complex, you just have to provide your user name and its password :
+Issuing a user/password bind is slightly more complex, because those credentials must be included:
:::Java
@Test
@@ -89,7 +89,7 @@ Note that this kind of bind will be supp
### Rebinding
-It's possible to issue a **Bind** on an already bound connection : the existing Ldap session will be terminated, and replaced by a new Ldap session. In any case, the connection is not dropped when doing so. Note that if the connection was encrypted, it will remain encrypted.
+It's possible to issue a **Bind** on an already bound connection and the existing LDAP session will be terminated, and replaced by a new LDAP session. In any case, the connection is not dropped when doing so. Note that if the connection was encrypted, it remains encrypted.
:::Java
@Test
@@ -110,7 +110,7 @@ If you issue a _bind_ on the same connec
This is a trivial operation : you just send an **UnbindRequest** to the server, which will invalidate your session.
-It's important to know that when you issue an **Unbind**, the connection is dropped. You can then do such a thing :
+It's important to know that when you issue an **Unbind**, the connection is dropped. It's done like this:
:::Java
@Test
@@ -127,5 +127,5 @@ It's important to know that when you iss
connection.bind( "uid=admin,ou=system", "secret" );
}
-Last, not least, if you close the connection, then the session will also be terminated.
+Last, but not least, if you close the connection, the session also terminates.
Modified: directory/site/trunk/content/api/user-guide/2.3-searching.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/2.3-searching.mdtext?rev=1776679&r1=1776678&r2=1776679&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/2.3-searching.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/2.3-searching.mdtext Sat Dec 31 02:55:46 2016
@@ -24,13 +24,13 @@ Notice: Licensed to the Apache Software
# 2.3 - Searching (...)
-Searching is the most important operation in **LDAP**. It has to be fast, very fast. On the other hand, as the server does not a lot of processing while looking for entries, the client has to provide many information in order to get some accurate results.
+Searching is the most important operation in **LDAP**. It has to be fast, very fast. On the other hand, as the server does the processing while looking for entries, the client must provide information to get accurate results.
-The idea is to define a search **API** which is easy to use in the simplest cases, but provides all the necessary bolts if you need to send complex search requests.
+The idea is to define a search **API** which is easy to use in the simplest cases, but provides all the capability to send complex search requests.
## Simple search
-Let's first look at a simple search. What we basically need to process a search is a starting point in the tree, a filter, a scope. Here is an example :
+Let's first look at a simple search. To process a search we need a starting point in the tree, a filter, and a scope. Here's an example:
:::java
EntryCursor cursor = connection.search( "ou=system", "(objectclass=*)", SearchScope.ONELEVEL );
@@ -45,19 +45,19 @@ Let's first look at a simple search. Wha
cursor.close();
-In this example, the _connection_ has been previously created. We just search for all the entries starting at *ou=system* and their children, which have an _ObjectClass_ attribute (all the entries have such an attribute, so we should get back all the entries). The scope (_ONELEVEL_) says we just search one level under the starting base.
+In this example, the _connection_ has been previously created. We search for all entries starting at *ou=system* along with its children, which have an _ObjectClass_ attribute (all the entries have such an attribute, so we should get back all the entries). The scope (_ONELEVEL_) searches one level under the starting base.
-We get back a cursor on entries, which can be walked forward. Every call to the _getEntry()_ method will return an entry.
+A cursor of entries is returned, which can be iterated over. Every call to the _getEntry()_ method returns the next entry in the LDAP result set.
-This is pretty much it !
+That's pretty much it!
-But this is not really enough , there are many possible options.
+But this is not really enough, there are many possible options.
->**Note** Don't forget to close the cursor, otherwise the associated data will remain in memory foreever !
+>**Note** Don't forget to close the cursor, otherwise the associated data remains in memory forever (causing a memory leak)!
### Searching using a DN
-In the previous sample, we used a String to define the starting point of the search. Sometime, you will find it more convenient to start a search using a DN (for instance because you got back a DN from an other operation). In this case, no need to transform the DN into a String before doing your search : simply use the DN !
+In the previous sample, we used a String to define the starting point of the search. Sometimes it's convenient to start a search with a DN (i.e. because you got the DN from another operation). In this case, no need to transform the DN into a String before doing your search, simply use the DN!
:::java
DN systemDn = new Dn( "ou=system" );
@@ -73,30 +73,30 @@ In the previous sample, we used a String
cursor.close();
-This is it !
+This is it!
### Scope
-There are three different different scopes you can use to search for data :
- * SearchScope.OBJECT : you will just get back the entry for the given DN, if it exists. Note that you could use a lookup if the filter is irrelevent.
- * SearchScope.ONELEVEL : you will get back all the elements just under the current DN, but not the element associated with the DN.
- * SearchScope.SUBLEVEL : you will get back all the elements starting from the given DN, including the element associated with the DN, whatever the depth of the tree.
+There are three different different scopes you can use to search for data:
+ * SearchScope.OBJECT : return the entry for a given DN, if it exists. Note that you could use a lookup if the filter is irrelevent.
+ * SearchScope.ONELEVEL : return all elements below the current DN, but not the element associated with the DN.
+ * SearchScope.SUBLEVEL : return all the elements starting from the given DN, including the element associated with the DN, whatever the depth of the tree.
### Filter
-The filter is used to define the elements that will be selected. There are various possibilities to construct a filter, using one or more connectors,a nd one or more expression nodes.
+The filter is used to define the elements that are targeted. There are various possibilities to construct a filter, using one or more connectors, and one or more expression nodes.
-Connrectors are using a prefix notation, followed by as many expression node as necessary, like in (& (node1) (node2) ... (nodeN))
+Connrectors use a prefix notation, followed by as many expression nodes as necessary, like in (& (node1) (node2) ... (nodeN))
-Expression nodes are always contane din parenthesis, with a left part - the attributeType and a right part - the value -.
+Expression nodes are always contained within parenthesis, with a left part - the attributeType, and a right part - the value -.
-Here is the list of possible connectors :
+Here is the list of possible connectors:
* & : n-ary AND connector, all the nodes must evaluate to TRUE
* | : n-ary OR connector, at least one of the node must evaluate to true
- * ! : 1-ary NOT connector : the node must evaluate to false
+ * ! : 1-ary NOT connector, the node must evaluate to false
-And here is the list of possible expression nodes, assuming that an expression node :
+And here is the list of possible expression nodes, assuming that an expression node:
* = Equality expression node : the selected entry matches the right part
* =* Presence expression node : tehentry has the Attribute on the left side
@@ -104,19 +104,19 @@ And here is the list of possible express
* <= Inferior expression node : the entry should be superior to the right part
* = [start][*][middle][*][final] Substring expression nose : the entry should match a usbstring
->**Note:** As of Apache DS 2.0, we don't support approx matches not extensible matches.
+>**Note:** As of Apache DS 2.0, we don't support approx matches nor extensible matches.
## More complex searches
-Sometime, you way want to have more control on the search opetation, either on the parameters you want to use, or on the results you get.
+Sometimes, you want to have more control over the search opetation, either with the parameters in use, or the results that are returned.
-A search can return something else than an entry. In fact, you can get three different kind of response
+A search things other than entries. In fact, you can get three different kinds of responses:
* When it's done, you will receive a SearchResultDone
* When the response is a reference to another entry, you will get a SearchResultReference
* In some cases, you may also receive an IntermediateResponse.
-You may also add a Control to the searchRequest, or request some specific AttributeType to be returned. The parameter you can inject into a SearchRequest are the following :
+You may also add a Control to the searchRequest, or request some specific AttributeType to be returned. The parameters that may be injected into a SearchRequest are as follows:
* The base DN
* The filter
@@ -128,7 +128,7 @@ You may also add a Control to the search
* The TypesOnly flag (to get the AttributeTypes but no values)
* The controls
-In both case, you should fill a _SearchRequest_ message and send it to the server :
+In both cases, you should fill the _SearchRequest_ message and send it to the server:
:::Java
// Create the SearchRequest object
@@ -154,5 +154,5 @@ In both case, you should fill a _SearchR
}
}
-As we can see, the response is different : we get back a _SearchCursor_ instance, and we have to check the response type before being able to process it.
+As we can see, the response is different, we are returned a _SearchCursor_ instance, and we must verify the response type before being able to process it.
Modified: directory/site/trunk/content/api/user-guide/2.4-adding.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/2.4-adding.mdtext?rev=1776679&r1=1776678&r2=1776679&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/2.4-adding.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/2.4-adding.mdtext Sat Dec 31 02:55:46 2016
@@ -24,12 +24,12 @@ Notice: Licensed to the Apache Software
# 2.4 - Adding entries
-Adding entries is one of the base operation a user can do on a **LDAP** server. Nevertheless, such an operation implies a lot of checks, and frequently the user gets some weird error messages. We will see how we can add an entry using the **LDAP API**, and then analyze the different error cases we can face.
+Adding entries is one of the base operations a user can do on an **LDAP** server. Nevertheless, it's an operation that implies many checks, and frequently the user receives strange error messages. We will see how to add an entry using the **LDAP API**, and analyze the various error cases that can occur.
## Adding an entry
-We will first see the easiest way to add an entry into the server, assuming that the entry is correct. In order to add an entry, you only have to provide the place where this entry will be stored (its _Dn_) and the list of its _Attributes_.
+Here is the simplest way to add an entry into the server, assuming that the entry is correct. In order to add an entry, you must provide the location where the entry is stored (its _Dn_) and the list of its _Attributes_ contained within it.
-Here is two examples where we inject the entry using **LDIF** :
+Here are two examples where the entry is injected using **LDIF**:
:::Java
@Test
@@ -77,13 +77,13 @@ Note that it is possible to use some var
Down the line, what is important is that the _add()_ operation is taking a full **[Entry](6.12-entry.html)**.
-We can also create the **[Entry](6.12-entry.html)** in a different way, which will be exposed in the following paragraphs.
+We can also create the **[Entry](6.12-entry.html)** in a different way, which is shown in the following paragraphs.
## Sending an _AddRequest_
-Sometimes, we want more control. We can ask the server to add an entry by sending an **[AddRequest]()**, which allows you to send a **[Control]()** at the same time.
+When more control is needed we ask the server to add an entry by sending an **[AddRequest]()**, which allows a **[Control]()** to be included in the request.
-Here is an example (note that the control is just injected to demonstrate the feature, it simply does nothing in this case):
+Here is an example (note that the control is just injected to demonstrate the feature, it doesn't really do anything special in this example):
:::java
@Test
@@ -113,7 +113,7 @@ Here is an example (note that the contro
### Asynchronous addition
-Some may want to add an entry, but will not check the result immediately. It's just a matter of calling the _addAsync()_ method, which will return a _Future_ that can be checked somewhere else in the code:
+Sometimes we need to add an entry, but not check the result immediately. It's just a matter of calling the _addAsync()_ method, which returns a _Future_ that can be checked somewhere else in the code:
:::java
@Test
@@ -143,7 +143,7 @@ Some may want to add an entry, but will
## Do, Don't
-Successfully adding an entry assume that the entry is correct, ie that the attributes and the value are compatible with the schema. There are many things checked by the server. Here is a list of constraints that you should respect in order to get your entry injected:
+Successfully adding an entry assumes that the entry was correct, i.e. the attributes and values are compatible with the LDAP schema. There are many things checked by the server. Here is a list of constraints that you should respect in order to get your entry injected:
* The entry must have at least one **Structural** _ObjectClass_
* If the entry has more than one **Structural** _ObjectClass_, then they must be hierarchically related
@@ -157,7 +157,7 @@ Successfully adding an entry assume that
There are also some other constraints, depending on the server, if it implements _NameForms_, _DITStructureRules_ or _DITContentRules_.
-One other reason your entry can be rejected is that you don't have enough privilege to add it. You have to check that the server configuration allows you to add an entry where you want to add it.
+Another reason an entry can be rejected is that there aren't enough privilege to add it. You must ensure the LDAP server's configuration allows you to add an entry in the correct location.
## Errors
@@ -167,6 +167,6 @@ At first, you might expect to get an exc
In any other case, the server will simply return a **[LdapResult]()** instance containing either **SUCCESS** or the cause of the rejection.
</DIV>
-Usually, if you get an error while adding an entry, the message might be pretty tedious. Most of the cases it's because either your entry already exists, or because your entry has some schema violation.
+Usually, if you get an error while adding an entry, the message is hard to read. Most of the errors occur because the entry already exists, or because the entry has an LDAP schema violation.
-The _LdapResult_ in the response will give you a clue about what going on.
\ No newline at end of file
+The _LdapResult_ in the response will provide helpful clues as to what the root cause is.
Modified: directory/site/trunk/content/api/user-guide/2.5-deleting.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/2.5-deleting.mdtext?rev=1776679&r1=1776678&r2=1776679&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/2.5-deleting.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/2.5-deleting.mdtext Sat Dec 31 02:55:46 2016
@@ -24,11 +24,11 @@ Notice: Licensed to the Apache Software
# 2.5 - Deleting entries
-Deleting an entry is really easy. It's just a matter to know its _DN_. There is one important thing to understand though : if this entry has some children, it won't be deleted.
+Deleting an entry is pretty easy, it just requires the entry's _DN_. There is one important thing to understand though, if the entry has children, the operation will fail.
## Simple entry deletion
-We can ask the deletion by providing the entry's _DN_, like what is done in the following example :
+We request a deletion by providing the entry's _DN_, as in the following example:
:::Java
@Test
@@ -44,7 +44,7 @@ We can ask the deletion by providing the
}
-Trying to delete the parent alone would leads to an error (NOT_ALLOWED_ON_NON_LEAF) :
+Trying to delete a parent node would result in an error (NOT_ALLOWED_ON_NON_LEAF) :
:::Java
@Test
@@ -62,7 +62,7 @@ Trying to delete the parent alone would
## Recursive deletion of entries
-Usually, you can't delete an entry and all of its children. However, some server accept such a request if you send a delete request and a TreeDelete control. This control is a [draft](http://tools.ietf.org/html/draft-armijo-ldap-treedelete-02), which has been implemented by **Microsoft**, **OpenDS**, **OpenDJ**. It will delete all the children and the entry itself. We don't use a normal _delete()_ method, there is a specific method, _deleteTree()_. Here is an example :
+Usually, you can't delete an entry and all of its children in one operation. However, some servers accept such requests if you send a delete request and a TreeDelete control. This control is a [draft](http://tools.ietf.org/html/draft-armijo-ldap-treedelete-02), which has been implemented by **Microsoft**, **OpenDS**, **OpenDJ**. It will delete all the children and the entry itself. We don't use a normal _delete()_ method, there is a specific method, _deleteTree()_. Here is an example :
:::Java
@Test
Modified: directory/site/trunk/content/api/user-guide/2.6-modifying.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/2.6-modifying.mdtext?rev=1776679&r1=1776678&r2=1776679&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/2.6-modifying.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/2.6-modifying.mdtext Sat Dec 31 02:55:46 2016
@@ -24,32 +24,32 @@ Notice: Licensed to the Apache Software
# 2.6 - Modifying entries
-There are several ways an entry can be modified. Mainly, it's about adding or deleting an attribute, or it's about modifying the values associated with an existing attribute.
+There are several ways an entry can be modified. Mainly, it's about adding or deleting an attribute, or modifying the values associated with an existing attribute.
-It's important to understand that many modifications can be applied on a single entry. All those modifications will be applied in a all or none fashion. For instance, if any of the modifications is invalid, then none of the modifications will be applied. Also if the server crashes while applying the modifications, it's guaranteed that the entry will remain consistent.
+It's important to understand that many modifications can be applied on a single entry. All those modifications will be applied in an all or none fashion. i.e., if any of the modifications are invalid, none of them will occur. Also if the server crashes while applying the mods, it's guaranteed that the entry will remain consistent.
## How it works ?
-Each modification to be applied on an entry is encapsulated in an intermediate class : a _Modification_ instance, which can be created as :
+Each modification to be applied on an entry is encapsulated into an intermediate class : a _Modification_ instance, which can be created as :
:::Java
Modification addedGivenName = new DefaultModification( ModificationOperation.ADD_ATTRIBUTE, "givenName", "John", "Peter" );
-Here, the modification instance represents addition of values "John" and "Peter" to the _giveName_ attribute (the _givenName_ attribute can have more than one value).
+Here the modification instance represents addition of values "John" and "Peter" to the _giveName_ attribute (the _givenName_ attribute can have more than one value).
-There are three different kind of modifications :
+There are three different kind of modifications:
-* ModificationOperation.ADD_ATTRIBUTE : add an attribute and values to an entry
-* ModificationOperation.REMOVE_ATTRIBUTE : remove an attribute and values from an entry
-* ModificationOperation.REPLACE_ATTRIBUTE : replace some existing values from an entry
+* ModificationOperation.ADD_ATTRIBUTE: add an attribute and values to an entry
+* ModificationOperation.REMOVE_ATTRIBUTE: remove an attribute and values from an entry
+* ModificationOperation.REPLACE_ATTRIBUTE: replace some existing values from an entry
## Adding or removing full attributes
-The two following operations are dealing with complete addition or removal of attributes.
+The following two operations completely add or remove attributes.
### Adding new attributes
-First of all, let's see how we proceed when it comes to adding an attribute. You need to know the entry you want to modify, which means you have to know its Dn. Then, you have to create the _Modification_ instance that will be applied on the entry. Here is the code that is used to add a _givenName_ attribute to an existing entry :
+First of all, let's learn how to add an attribute. First you must know which entry to modify, which means you must know its Dn. Next, you must create the _Modification_ instance which is applied to the entry. Here is the code that is used to add a _givenName_ attribute to an existing entry :
:::Java
...
@@ -113,16 +113,15 @@ results in :
at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2309)
...
-Here, we have tried to add the _uid_ attribute which already exists, and the error trace says so
-as expected.
+Here, we've tried to add the _uid_ attribute that already exists, and the error trace tells us as much.
-Anothe potential error you can get is when you try to add an attribute that is not allowed in an entry. This can be because the Entry's ObjectClass does not allow such an attribute, or because the server forbid you to modify the entry, due to the ACIs applied on this entry.
+Another potential error occurs when adding an attribute type that isn't allowed on that entry. This occurs because the Entry's ObjectClass does not allow such an attribute (per the schema), or because the server forbids modification of that entry, due to the ACIs applied on this entry.
-Last, not least, but this is quite obvious, the entry *must* exist !
+Last, but not least, and hopefully this is obvious, the entry *must* exist prior to modification!
### Removing an attribute
-Removing an attribute is actually a bit simpler than adding an attribute, as you don't have to specify the values of the attribute to remove. Here is an example where we will remove the _giveName_ attrinute from an entry :
+Removing an attribute is actually a bit simpler than adding one, because the values for the attribute don't need to be specified. Here's an example where the _givenName_ attrinute is removed from an entry:
:::Java
@@ -132,13 +131,13 @@ Removing an attribute is actually a bit
connection.modify( "uid=Doe,dc=acme,dc=com", adeletedivenName );
...
-Here, we have created a modification, specifying that the _givenName_ attribute has to be removed, and we applied the modification on the entry.
+Here, we've created a modification, specifying the _givenName_ attribute must be removed, and we apply the modification request to the entry.
-Again, you can delete more than one attribute from an entry, it's just a matter of creating more than one _Modification_ instances and applying them to the entry.
+Again, more than one attribute may be deleted from an entry. It's a matter of creating more than one _Modification_ instances and applying them to the entry.
#### Errors
-If you try to delete an attribute that does not exist in the entry, you will get this error :
+If you try to delete an attribute that does not exist in the entry, you will get this error:
:::Java
org.apache.directory.api.ldap.model.exception.LdapNoSuchAttributeException: NO_SUCH_ATTRIBUTE: failed for MessageType : MODIFY_REQUEST
@@ -166,17 +165,17 @@ If you try to delete an attribute that d
Here, the entry does not contain the _givenName_ attribute.
-Anothe potential error you can get is when you try to remove an attribute which is a mandatory attribute, per the entry's ObjectClass constraints.
+Another potential error is when you trying to remove a mandatory attribute, per the entry's ObjectClass constraints.
-Otherwise, the server might forbid you to modify the entry, due to the ACIs that are applicable to this entry.
+Otherwise, the server might forbid modification of entry due to the ACIs that are applicable to it.
-Again the entry *must* exist before performing a modification!
+Again the entry *must* exist prior to performing the modification!
## Adding, removing or replacing attribute values
-You can now update an attribute's values themselves, atomically, instead of removing a full attribute, and add it back but with updated values. We use the exact same _Modification_ instance, with the same three _ModificationOperation_, except that the semantics slightly differ.
+You can now update an attribute's values themselves, atomically, instead of removing the full attribute, and add it back but with updated values. We use the exact same _Modification_ instance, with the same three _ModificationOperation_, except that the semantics slightly differ.
-Typically, here is what happens when you use one of the three _ModificationOperation_ on an attribute :
+Typically, this is what happens when using one of the three _ModificationOperation_ on an attribute:
* ModificationOperation.ADD_ATTRIBUTE : add values to an attribute. If the Attribute does not exist, it will be added
* ModificationOperation.REMOVE_ATTRIBUTE : remove values from an attribute.
@@ -184,7 +183,7 @@ Typically, here is what happens when you
### Add values
-Let's see with the addition of values. Here, we will assume we have an entry like :
+Let's see with the addition of values. Here, we will assume we have an entry like:
dn: uid=jDoe,dc=acme,dc=com
objectClass: person
@@ -221,9 +220,9 @@ The entry now has two values for the _gi
#### Errors
-Again, such an operation might fail for many reasons. Let's see what are the possible errors :
+Again, such an operation might fail for many reasons. Let's see what are the possible errors:
-First, the attribute's value already exists. You will get such an error :
+First, if the attribute's value already exists. You will get an error like this:
org.apache.directory.api.ldap.model.exception.LdapAttributeInUseException: ATTRIBUTE_OR_VALUE_EXISTS: failed for MessageType :
MODIFY_REQUEST
@@ -240,9 +239,9 @@ First, the attribute's value already exi
at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2309)
at org.apache.directory.shared.client.api.operations.ClientModifyRequestTest.testModifyRemoveAttribute(ClientModifyRequestTest.java:303)
-Note that depending on the attribute's syntax, you may get such an error because you tried to enter a value with different casing when the syntax is case-insensitive. Typically, if the attribute contains the value 'John' and you try to add the value 'JOHN', you will get this very same error message. Be sure you know wht the attribute syntax allows you to do...
+Note that depending on the attribute's syntax, you may get this type of error because you entered a value with different casing when the syntax is case-insensitive. Typically, if the attribute contains the value 'John' and you try to add the value 'JOHN', you will get this error message. Be sure you know what the attribute syntax allows you to do...
-Second, the attribute is single valued : it's not possible to add a second value in the Attribute. You'll get the following error message :
+Second, if the attribute is single valued, it will not be possible to add another value to it. When this happens you'll get the following error message:
org.apache.directory.api.ldap.model.exception.LdapInvalidAttributeValueException: CONSTRAINT_VIOLATION: failed for MessageType : MODIFY_REQUEST
Message ID : 3
@@ -258,11 +257,11 @@ Second, the attribute is single valued :
at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2309)
at org.apache.directory.shared.client.api.operations.ClientModifyRequestTest.testModifyRemoveAttribute(ClientModifyRequestTest.java:297)
-Third, the ACIs you have set on the server may not allow you to update an entry or an attribute.
+Third, the ACIs set on the server may not allow updating an entry or its attribute.
-### Remove values
+### Removing values
-Removing values follow the same scheme : select the entry, chose the attribute, and list the values you want to be removed from this attribute. Here is an exemple :
+Removing values follow the same pattern. First select the entry, choose its attribute, and list the values to be removed from it. Here is an exemple:
:::Java
...
@@ -271,15 +270,15 @@ Removing values follow the same scheme :
connection.modify( "uid=Doe,dc=acme,dc=com", removedGivenNameValue );
...
-The value 'Tom' we just have added should now be removed from the _givenName_ attribute, but the value 'John' should still be present.
+The value 'Tom' just added should now be removed from the _givenName_ attribute, but the value 'John' should still be present.
-Whet if you remove the last value of an attribute ? That quite simple : the attribute itself will be removed from the entry, if this is allowed (see below).
+How do we remove the last value of an attribute? It's quite simple. The attribute itself must be removed from the entry, if this is allowed (see below).
#### Errors
-There are more potential erros with this operation. let's list all of them.
+There are more potential erros with this operation. Let's list them all.
-First, the value you want to remove does not exist. You will get such an error :
+First, the value you want to remove does not exist. You will get such an error:
org.apache.directory.api.ldap.model.exception.LdapNoSuchAttributeException: NO_SUCH_ATTRIBUTE: failed for MessageType :
MODIFY_REQUEST
@@ -303,7 +302,7 @@ First, the value you want to remove does
at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2309)
at org.apache.directory.shared.client.api.operations.ClientModifyRequestTest.testModifyRemoveAttributeValue(ClientModifyRequestTest.java:327)
-Second, you try to remove the last value of an attribute which is mandatory You will get such an error :
+Second, if you try to remove the last value of an attribute which was declared mandatory (in the schema) the following error will occur:
org.apache.directory.api.ldap.model.exception.LdapSchemaViolationException: OBJECT_CLASS_VIOLATION: failed for MessageType :
MODIFY_REQUEST
@@ -322,7 +321,7 @@ Second, you try to remove the last value
Here, we tried to remove the _sn_ attribute's last value from an entry where it's a required attribute.
-Third, you try to remove a value which is used as the entry's _RDN_ : this is not allowed. Typically, for the 'uid=billyd,ou=users,ou=system' entry, you can't remove the 'billyd' value from the 'uid' attribute. Here is the error you get when you try to apply such a modifcation :
+Third, if you try to remove a value which was used as part of the entry's _RDN_ : which is never allowed. Typically, for the 'uid=billyd,ou=users,ou=system' entry, you can't remove the 'billyd' value from the 'uid' attribute. This is the error that occurs when such a modification is attempted:
org.apache.directory.api.ldap.model.exception.LdapSchemaViolationException: NOT_ALLOWED_ON_RDN: failed for MessageType :
MODIFY_REQUEST
@@ -339,17 +338,17 @@ Third, you try to remove a value which i
at org.apache.directory.ldap.client.api.LdapNetworkConnection.modify(LdapNetworkConnection.java:2309)
at org.apache.directory.shared.client.api.operations.ClientModifyRequestTest.testModifyRemoveAttributeValue(ClientModifyRequestTest.java:314)
-Then you have the classical errors : the ACLs forbids you to remove a velue, or the entry simply does not exist.
+There are also classical errors, when ACLs forbid the removal of a value, or the entry doesn't exist.
### Replace values
Here, what we want to do is to replaces all the values from an attribute with some new values. All in all, this is equivalent to first remove the values, then inject the new values, using modifications, except that in some cases, doing so will not work.
-An exemple where such an operation is mandatory is when you want to replace the value of a mandatory attribute with something different : with two successive operation, that would fail. A replace will work.
+An example where such an operation is mandatory is when replacing the values of a mandatory attribute with something different: with two successive operations, that would fail. A replace will work.
-What is important here is that the operation simply replace *all the existing values* by new ones, removing the previous ones.
+What is important here is that the operation simply replace *all the existing values* with new ones, removing the previous ones.
-Let's see how it works with a simple example, with an entry containing :
+Let's see how it works with a simple example, with an entry containing:
dn: uid=jDoe,dc=acme,dc=com
objectClass: person
@@ -362,7 +361,7 @@ Let's see how it works with a simple exa
givenName: John
givenName: Peter
-We will try to replace the _givenName_ :
+We will try to replace the _givenName_:
Modification replaceGn = new DefaultModification( ModificationOperation.REPLACE_ATTRIBUTE, "givenName",
"Jack" );
@@ -371,14 +370,14 @@ We will try to replace the _givenName_ :
The modified entry will have its _givenName_ value replaced by 'Jack', the two previous values will have been removed.
-There is one corner case with this operation : if you create a _Modification_ instances where you specify an Attribute with no value, then the attribute will be removed from the entry.
+There is one corner case with this operation: creating a _Modification_ instance where the attribute has no value, then the attribute will be removed from the entry.
#### Errors
-You will get the same errors seen in the two previous operation (ADD and REMOVE) for the very same use cases. Be sure you don't :
+You will get the same errors seen in the two previous operation (ADD and REMOVE) for the very same use cases. Here are some more things to watch out for:
-* inject more than one value in a SINGLE_VALUE attribute
-* remove a value which is used by the RDN
-* delete all the values of a mandatory attribute
-* have the right to modify the entry
-* try to update a non existent entry
\ No newline at end of file
+* never inject more than one value in a SINGLE_VALUE attribute
+* never remove a value which is used by the RDN
+* never delete all the values of a mandatory attribute
+* always have the right to modify the entry
+* never try to update a non-existent entry