content/api/internal-design-guide/2-general-structure.mdtext

Title: 2 - General Structure
NavPrev: 1-introduction.html
NavPrevText: 1 - Introduction
NavUp: ../internal-design-guide.html
NavUpText: Internal Design 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 **Apache LDAP API** is split into many modules. Here is their hierarchy :

![Modules](images/ldap-api-modules.png)

* The **all** module is just a packaging module, gathering all the other modules in one single jar to simplify the work for 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 :

![LdapConnection](images/ldap-connection.png)

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 :

![LDAP API Architecture](images/architecture.png)