You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by el...@apache.org on 2018/01/12 08:38:38 UTC
svn commit: r1820955 [1/3] - in /directory/site/trunk/content/api/dev-guide:
./ 1-introduction.mdtext 2-general-structure.mdtext images/
images/architecture.graphml images/architecture.png
images/ldap-connection.graphml images/ldap-connection.png
Author: elecharny
Date: Fri Jan 12 08:38:38 2018
New Revision: 1820955
URL: http://svn.apache.org/viewvc?rev=1820955&view=rev
Log:
Added some pages for developpers. Very preliminary
Added:
directory/site/trunk/content/api/dev-guide/
directory/site/trunk/content/api/dev-guide/1-introduction.mdtext
directory/site/trunk/content/api/dev-guide/2-general-structure.mdtext
directory/site/trunk/content/api/dev-guide/images/
directory/site/trunk/content/api/dev-guide/images/architecture.graphml
directory/site/trunk/content/api/dev-guide/images/architecture.png (with props)
directory/site/trunk/content/api/dev-guide/images/ldap-connection.graphml
directory/site/trunk/content/api/dev-guide/images/ldap-connection.png (with props)
Added: directory/site/trunk/content/api/dev-guide/1-introduction.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/dev-guide/1-introduction.mdtext?rev=1820955&view=auto
==============================================================================
--- directory/site/trunk/content/api/dev-guide/1-introduction.mdtext (added)
+++ directory/site/trunk/content/api/dev-guide/1-introduction.mdtext Fri Jan 12 08:38:38 2018
@@ -0,0 +1,47 @@
+Title: 1 - Introduction
+NavUp: ../dev-guide.html
+NavUpText: User Guide
+NavNext: 2-general-structure.html
+NavNextText: 2 - General structure
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+# 1 - Introduction
+
+This Developer Guide teaches developers about the inner logic of the API. It can be useful to those interested in the project, giving them some clues about how it all works and its design, and also to those who want to extend the API by adding Controls, Extended Operations, or schema elements like SyntaxCheckers, Comparators, etc.
+
+
+## Content
+
+* [2 - General structure](2-general-structure.html)
+* [3 - Building](3-building.html)
+* [4 - ASN/1](4-asn1.html)
+* [5 - Network](5-network.html)
+* [6 - Encoding/Decoding](6-codec.html)
+* [7 - LDAP Messages](7-ldap-messages.html)
+* [8 - Schema](8-schema.html)
+* [9 - Dn](9-dn.html)
+* [10 - Entry](10-entry.html)
+* [11 - Filter](11-filter.html)
+* [12 - Cursor](12-cursor.html)
+* [13 - Controls](13-controls.html)
+* [14 - Extended Operations](14-extended-operations.html)
+* [15 - LDIF](15-ldif.html)
+* [16 - DSML](16-dsml.html)
+* [17 - OSGi](17-osgi.html)
+
+
Added: directory/site/trunk/content/api/dev-guide/2-general-structure.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/dev-guide/2-general-structure.mdtext?rev=1820955&view=auto
==============================================================================
--- directory/site/trunk/content/api/dev-guide/2-general-structure.mdtext (added)
+++ directory/site/trunk/content/api/dev-guide/2-general-structure.mdtext Fri Jan 12 08:38:38 2018
@@ -0,0 +1,136 @@
+Title: 2 - General Structure
+NavPrev: 1-introduction.html
+NavPrevText: 1 - Introduction
+NavUp: ../dev-guide.html
+NavUpText: Developer Guide
+NavNext: 3-building.html
+NavNextText: 3 - Building
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+# 2 - General Structure
+
+The *LDAP API* is split into many modules. Here is their hierarchy :
+
+<pre>
+LDAP API root
+ |
+ +-- all
+ |
+ +-- asn1
+ | |
+ | +-- api
+ | |
+ | +-- ber
+ |
+ +-- distribution
+ |
+ +-- dsml
+ | |
+ | +-- engine
+ | |
+ | +-- parser
+ |
+ +-- i18n
+ |
+ +-- integ
+ |
+ +-- integ-osgi
+ |
+ +-- ldap
+ | |
+ | +-- client
+ | | |
+ | | +-- all
+ | | |
+ | | +-- api
+ | |
+ | +-- codec
+ | | |
+ | | +-- core
+ | | |
+ | | +-- standalone
+ | |
+ | +-- extras
+ | | |
+ | | +-- aci
+ | | |
+ | | +-- codec
+ | | |
+ | | +-- codec-api
+ | | |
+ | | +--sp
+ | | |
+ | | +-- trigger
+ | | |
+ | | +-- util
+ | |
+ | +-- model
+ | |
+ | +-- net
+ | | |
+ | | +-- mina
+ | |
+ | +-- schema
+ | |
+ | +-- converter
+ | |
+ | +-- data
+ |
+ +-- util
+</pre>
+
+* The *all* module is just a packaging module, gathering all the other modules in one single jar to simplify the work o those who want to use the API. One can import each module speparately, or the *all* module only. Note that it does not include the tests and integration modules (_integ_, _integ-osgi_ and _distribution_)
+
+* The *asn1* module contains the code needed to handle *ASN/1* encoding/decoding.
+
+* The *distribution* module just create the packages
+
+* The *dsml* module covers *DSML* features
+
+* The *i18n* module contains all the messages, in various languages (english, french and german at the moment)
+
+* The *integ* module is for integration tests, covering many of the existing modules
+
+* The *integ-osgi* module covers tests related to *OSGi* integration. It checks that we can instanciate some component within an *OSGi* framework.
+
+* The *ldap* modules are the meat of the *API* : they contain all the needed modules related to *LDAP*, and mainly the *model* module. Note that the *net* module should not be part of *ldap*, per se...
+
+* The *util* module contains classes that are shared across the various modules.
+
+
+Anyway, from a developer point of view, that does not tell a lot about the inner struture.
+
+Clearly, the entry point is the *Connection* interface and its inherited class, which reside in the _api-ldap-client-api_ module, in _/ldap/client/.api_. This is the interface - or one of its implementation - that is used to connect to a LDAP server. Here is the full hierarchy :
+
+
+
+The user will need a _LdapNetworkConnection_ most of the time, the wrapper is just used by the connection pool. Note that *ApacheDS* has its own implementation (not represented in this picture), called _LdapCoresSessionConnection_.
+
+So, bottom line, if you want to have a look at how the *API* works, the entry point is the *LdapNetworkConnection class.
+
+## Layers
+
+If you consider a *LdapConnection*, obviously, you will have to connect to a remote server, and you will need a part of the code handling the network. This is done - currently - using *Apache MINA*, which is an *NIO* framework. That means all the communication with the remote *LDAP* server is done asynchroniously.
+
+We also made so the *API* to be *OSGi* compliant. That means some of the parts need to be 'activated'. The idea was to make it possible to extend the *API* easily by adding component that could be loaded dynamically. So far, it's not a completed work, but still, this is a on-going process.
+
+The following pitcure shows for 10 000 feet the *LDAP API* architecture :
+
+
+
+