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 17:32:45 UTC
svn commit: r1776803 - in /directory/site/trunk/content/api/user-guide:
6.12-entry.mdtext 6.27-oid.mdtext 6.35-value.mdtext
7-requests-responses.mdtext 7.1-abandon-request.mdtext 8-ldap-rfcs.mdtext
Author: smckinney
Date: Sat Dec 31 17:32:45 2016
New Revision: 1776803
URL: http://svn.apache.org/viewvc?rev=1776803&view=rev
Log:
the last
Modified:
directory/site/trunk/content/api/user-guide/6.12-entry.mdtext
directory/site/trunk/content/api/user-guide/6.27-oid.mdtext
directory/site/trunk/content/api/user-guide/6.35-value.mdtext
directory/site/trunk/content/api/user-guide/7-requests-responses.mdtext
directory/site/trunk/content/api/user-guide/7.1-abandon-request.mdtext
directory/site/trunk/content/api/user-guide/8-ldap-rfcs.mdtext
Modified: directory/site/trunk/content/api/user-guide/6.12-entry.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/6.12-entry.mdtext?rev=1776803&r1=1776802&r2=1776803&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/6.12-entry.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/6.12-entry.mdtext Sat Dec 31 17:32:45 2016
@@ -24,21 +24,21 @@ Notice: Licensed to the Apache Software
# 6.12 - Entry
-The _Entry_ class is one of the most important one in the _API_. It describes the base element stored into a *LDAP* server, and it associates a _Dn_ and some _Attributes_.
+The _Entry_ class is one of the most important ones in the _API_. It describes the base element stored into a *LDAP* server, and it associates a _Dn_ and some _Attributes_.
We have two kinds of _Entry_ in the _API_, depending on the presence of a _SchemaManager_ in the _Entry_, or not.
We also provide a few extended classes, like the _ImmutableEntry_, an immutable version of the _Entry_.
-## What is an entry ?
+## What an entry?
-An entry is an object containing a _Dn_ and some _Attributes_. The following schema shows what's inside an _entry_ :
+An entry is an object containing a _Dn_ and some _Attributes_. The following schema shows what's inside an _entry_:
## Creating an Entry
-We have many ways to create an _Entry_. Basically, an _Entry_ has a _Dn_ and some _Attributes_. It can be schema aware, or not. We provide constructors to allow a user to create the kind of _Entry_ he wants.
+We have many ways to create an _Entry_. Basically, an _Entry_ has a _Dn_ and some _Attributes_. It can be schema aware, or not. We provide constructors to allow a user to create the kind of _Entry_ wanted.
The simplest way to create an _Entry_ is to call the default constructor. The created entry will have no attributes, and no _Dn_. We can also make it schema aware by passing a _SchemaManager_. Here is an example:
@@ -88,7 +88,7 @@ We can also create an entry by copying a
entry.clear();
-Last, not least, it's possible to create an _Entry_ using a list of LDIF formated attributes. An example worth ten lines of documentation, so let's see what it means.
+Last, but not least, it's possible to create an _Entry_ using a list of LDIF formated attributes. An example worth ten lines of documentation, so let's see what it means.
First, we will create a schema agnostic entry:
@@ -142,7 +142,7 @@ We have six methods available that modif
### Adding Attributes
-Two methods can be used to add some attribute into an _Entry_. The first one will add a complete _Attribute_, the second one will add some values to an existing _Attribute_.
+Two methods can be used to add attribute into an _Entry_. The first one will add a completed _Attribute_, the second one will add some values into an existing _Attribute_.
In any case, we can add either an empty attribute, or an attribute with some values. Those values can be _Strings_, _byte[]_ or _Values_. The added attributes can be schema aware, and we can also provide a user provided name for the attribute type.
@@ -211,7 +211,7 @@ For a schema agnostic entry :
entry.add( "cn", "A second test" );
-As you can see, there is no real difference between those two methods, except that we pass the _schemaManager_ in the first one.
+As you can see, there is no real difference between those two methods, except that we pass the _schemaManager_ into the first one.
##### put() methods
@@ -236,7 +236,7 @@ The big difference with the _add_ method
We can remove either an attribute having a specific value, or an entire attribute. In order to remove a complete attribute, you just have to provide the attribute's name, and use the _removeAttributes_ method.
-Here are some example for both usages :
+Here are examples for both usages :
:::Java
Entry entry = new DefaultEntry(
@@ -262,7 +262,7 @@ It's also possible to store a new _Dn_ i
### Clearing the Entry
-You can remove all the _Attribute_ from the entry, using the _clear()_ method :
+You can remove all the _Attribute_s from the entry, using the _clear()_ method :
:::Java
Entry entry = new DefaultEntry(
@@ -282,7 +282,7 @@ The _Dn_ will still be around though.
## Attribute data access methods
-The *API* provides convenient methods to access the _Entry_ content, and to check if it contains some attributes or some values. We will shortly expose those methods in the following paragraphs.
+The *API* provides convenient methods to access the _Entry_ content, and to check if it contains some attributes or some values. We will show these methods in the paragraphs that follow.
### Contains method
@@ -412,7 +412,7 @@ Returns the number of _Attribute_ stored
#### equals(Object)
-Check if two *Entries* are equal or not. It's important to understand that depending on whether the entry is schema aware or not, the comparison will be processed differently. Typically, the attribute's name must be equals when they have been trimmed and lower cased if the entry is not schema aware, and we can't compare an attribute named 'cn' with another one named '2.5.4.3' in this case (the _Entry_ must be schema aware to allow such comparison). More important, the values *must* be identical (same casing, same spaces) in this case.
+Check if two *Entries* are equal or not. It's important to understand that depending on whether the entry is schema aware or not, the comparison will be processed differently. Typically, the attribute's name must be equivilent after being trimmed and set to lowercase. If the entry is not schema aware, and we can't compare an attribute named 'cn' with another one named '2.5.4.3' in this case (the _Entry_ must be schema aware to allow such comparison). More important, the values *must* be identical (same casing, same spaces) in this case.
The attribute's values order is irrelevant.
Here are one example with a schema agnostic _Entry_:
Modified: directory/site/trunk/content/api/user-guide/6.27-oid.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/6.27-oid.mdtext?rev=1776803&r1=1776802&r2=1776803&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/6.27-oid.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/6.27-oid.mdtext Sat Dec 31 17:32:45 2016
@@ -26,7 +26,7 @@ Notice: Licensed to the Apache Software
## Introduction
-An *OID* stands for *Object* *ID*entifier. It's a part of the *ASN/1* standard. Basically, it's a hierarchy, named a 'registration tree'. It's a list of 'arcs', which values start at '0', and each arc is separated with a dot ( '.' ).
+An *OID* stands for *Object* *ID*entifier. It's part of the *ASN/1* standard. Basically, it's a hierarchy, named a 'registration tree'. It's a list of 'arcs', which values start at '0', and each arc is separated with a dot ( '.' ).
There are three defined root arcs :
@@ -34,23 +34,23 @@ There are three defined root arcs :
* iso (1)
* joint-iso-itu-t (2)
-There is some places on the internet where one can have a look at the existing OIDs. Here is one : [OID repository](http://www.oid-info.com/cgi-bin/display?tree=&see=all).
+There are some places on the internet where one can look at the existing OIDs. Here is one: [OID repository](http://www.oid-info.com/cgi-bin/display?tree=&see=all).
## Syntax
-The OID syntax is pretty simple : some numbers with dots between them, like 0.1.245
+The OID syntax is pretty simple. Numbers are separated with periods between them, e.g. 0.1.245
-There are a few extra rules :
+There are a few extra rules:
* The first number must be 0, 1 or 2
* If it's 0 or 1, then the second number must be between 0 and 39
- * A dot must be preceded and followed by a number
- * A 0 at first position is never followed by any other digit
- * There is no limit for the number of digits otherwise : 2.25.81407072025111374527560065493494091452 is legit
+ * A period must be preceded and followed by a number
+ * A 0 at first position is never followed by another digit
+ * There is no limit for the number of digits. For example, 2.25.81407072025111374527560065493494091452, is a legitimate OID value.
## API
-The *Apache LDAP API* offers a few functions which can be used to manipulate an OID. In any case, we don't have a constructor for an OID.
+The *Apache LDAP API* offers a few functions that can be used to manipulate an OID. In any case, there is not a constructor for an OID.
The class to use is *org.apache.directory.api.asn1.util.Oid*. It creates immutable instances.
@@ -76,6 +76,6 @@ Return the *byte[]* representation of an
## OID parsing
-We use a *FSA* (Finite State Automaton) to parse a String to get an internal representation of an OID. Here is a picture showing the *FSA* we are using :
+We use a *FSA* (Finite State Automaton) to parse a String to get an internal representation of an OID. Here is a picture showing the *FSA* we are using:
Modified: directory/site/trunk/content/api/user-guide/6.35-value.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/6.35-value.mdtext?rev=1776803&r1=1776802&r2=1776803&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/6.35-value.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/6.35-value.mdtext Sat Dec 31 17:32:45 2016
@@ -24,9 +24,9 @@ Notice: Licensed to the Apache Software
# 6.35 - Value
-The _Value_ class is used to store an attribute's value. Such a value can be either a String or a byte[], depending on the nature of the AttributeType (the default is that the _Value_ is a String). Each value is associated to an AttributeType, and is used in an Antry or a DN.
+The _Value_ class is used to store an attribute's value. Such a value can be either a String or a byte[], depending on the nature of the AttributeType (the default is that the _Value_ is a String). Each value is associated to an AttributeType, and is used in an Entry or a DN.
-We can create schema aware _Value_, or just plain _Value_. Having a schema aware _Value_ allows further controls to be made on the value we inject : its syntax will be checked against the _AttributeType_ syntax.
+We can create a schema aware _Value_, or just a plain _Value_. Having a schema aware _Value_ allows further controls to be made on the value injected : its syntax will be checked against the _AttributeType_ syntax.
_Value_ is also a _Externalizable_ class.
@@ -34,11 +34,11 @@ _Value_ instances are immutable.
## Creating a value
-There are two ways to create a value :
+There are two ways to create a value:
- using a constructor
- using a static factory (useful for deserialization)
-You can create the value passing it an *AttributeType*, or without it. Here are the possible constructors :
+You can create the value passing it an *AttributeType*, or without it. Here are the possible constructors:
<CENTER>
| With an AttributeType | Without an attributeType | Description |
@@ -48,11 +48,11 @@ You can create the value passing it an *
| Value( AttributeType, Value ) | - | Create a new Value from an existing one, applying the SchemaManager on it |
</CENTER>
-The third constructor is quite specific : as _Value_ is immutable, it allows you to associate a SchemaManager to a _Value_ instance (creating a new _Value_ in the process). The new _Value_ instance will be schema aware.
+The third constructor is quite specific, as _Value_ is immutable, and it allows you to associate a SchemaManager to a _Value_ instance (creating a new _Value_ in the process). The new _Value_ instance will be schema aware.
## Operations on a Value
-You mostly can consult the content of the _Value_, and its status. Here is the list of common operations :
+There are ways to consult the content of the _Value_, and its status. Here is the list of common operations:
<CENTER>
| Operation | Description |
Modified: directory/site/trunk/content/api/user-guide/7-requests-responses.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/7-requests-responses.mdtext?rev=1776803&r1=1776802&r2=1776803&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/7-requests-responses.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/7-requests-responses.mdtext Sat Dec 31 17:32:45 2016
@@ -24,20 +24,20 @@ Notice: Licensed to the Apache Software
# 7 - Requests and Responses (...)
-We will describe all the Java structure we use for each LDAP message (Requests and Responses). This can be useful when one want to send a message or process a response, using all the possible options.
+Here we will describe all the Java structures used to process LDAP message (Requests and Responses). This can be useful whenever one wants to send a message or process a response, using all possible options.
## Inherited classes
-All the messages inherit from a few classes that are describe here. They gather the common fields that can be used by most of the specific messages.
+All the messages inherit from a few classes that are described here. They gather the common fields used across most message types.
### The Message interface
-This is the mother of all the hierarchy. A message has a few characteristics that are available to all the inherited classes :
+This is the parent of the message hierarchy. Every message has a few characteristics that are available across all of its inherited classes:
* Id : the message ID which is generated by the server or the client. You should never add it
* Controls : The list of controls you add to a request or that get added by the response
-Here is the Message interface :
+Here is the Message interface:
:::Java
/**
Modified: directory/site/trunk/content/api/user-guide/7.1-abandon-request.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/7.1-abandon-request.mdtext?rev=1776803&r1=1776802&r2=1776803&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/7.1-abandon-request.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/7.1-abandon-request.mdtext Sat Dec 31 17:32:45 2016
@@ -24,7 +24,7 @@ Notice: Licensed to the Apache Software
# 7.1 AbandonRequest
-This request is used to tell the server that a given previous request must be abandonned. The only needed parameter is the *ID* of the request you want to stop.
+This request is used to tell the server that a given request (sent previously) has been abandoned. The only required parameter is the *ID* field of a request you want to stop.
:::Java
public interface AbandonRequest extends Request
@@ -46,7 +46,7 @@ This request is used to tell the server
AbandonRequest setAbandoned( int requestId );
}
-There are two existing implementations you can use :
+There are two existing implementations that can used:
* _AbandonRequestImpl_ : The default implementation.
* _AbandonRequestDsml_ : An implementation used when you want to generate a DSML request
@@ -55,16 +55,16 @@ The _AbandonRequest_ message does not ha
## Usage
-It's pretty easy. You just have inject the ID of the request you want to abandon :
+It's pretty easy to do. You just to inject the ID of the request you want to abandon:
:::Java
connection.abandon( messageId );
-This will interrupt the request which ID is _messageId_.
+This will interrupt the request whose ID equals _messageId_.
### Adding some controls
-You can add a control in the _AbandonRequest_, as soon as you create an instance of _AbandonRequestImpl :
+You can add a control in the _AbandonRequest_, once you create an instance of _AbandonRequestImpl:
:::Java
@@ -75,4 +75,4 @@ You can add a control in the _AbandonReq
// Send the request
connection.abandon( abandonRequest );
-_
\ No newline at end of file
+_
Modified: directory/site/trunk/content/api/user-guide/8-ldap-rfcs.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/8-ldap-rfcs.mdtext?rev=1776803&r1=1776802&r2=1776803&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/8-ldap-rfcs.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/8-ldap-rfcs.mdtext Sat Dec 31 17:32:45 2016
@@ -24,7 +24,7 @@ Notice: Licensed to the Apache Software
# 8 - LDAP Related RFCs
-**LDAP** and **X.500** are specified through many **RFCs**. Here is the list of available **RFCs** within some category (there are around 100 RFCs available, some of them are now deprecated, some other are obsolete.
+**LDAP** and **X.500** are specified through its many **RFCs**. Here is the list of available **RFCs** by category (there are about 100 RFCs available, some now deprecated, other obsolete.
This page list all the existing **RFCs**, obsolete or not.