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/08/19 09:32:47 UTC

svn commit: r1838371 - in /directory/site/trunk/content/api/internal-design-guide: 5-network.mdtext images/ldap-connection-factory.graphml images/ldap-connection-factory.png

Author: elecharny
Date: Sun Aug 19 09:32:47 2018
New Revision: 1838371

URL: http://svn.apache.org/viewvc?rev=1838371&view=rev
Log:
Added some API content

Added:
    directory/site/trunk/content/api/internal-design-guide/images/ldap-connection-factory.graphml
    directory/site/trunk/content/api/internal-design-guide/images/ldap-connection-factory.png   (with props)
Modified:
    directory/site/trunk/content/api/internal-design-guide/5-network.mdtext

Modified: directory/site/trunk/content/api/internal-design-guide/5-network.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/internal-design-guide/5-network.mdtext?rev=1838371&r1=1838370&r2=1838371&view=diff
==============================================================================
--- directory/site/trunk/content/api/internal-design-guide/5-network.mdtext (original)
+++ directory/site/trunk/content/api/internal-design-guide/5-network.mdtext Sun Aug 19 09:32:47 2018
@@ -37,10 +37,11 @@ Notice: Licensed to the Apache Software
     * [Sending a message](#sending-a-message)
     * [Receiving a message](#receiving-a-message)
     * [Encoding/decoding](#encoding-decoding)
+  * [SSL handling](#ssl-handling)
   * [StartTLS handling](#startts-handling)
 
 
-The **Apache LDAP AP** is built on top of [**Apache MINA](http://mina.apache.org) which is a **NIO** framework. 
+The **Apache LDAP AP** is built on top of [**Apache MINA**](http://mina.apache.org) which is a **NIO** framework. 
 
 As **MINA** is fully asynchronous, it has some impact on the design of the **LDAP API**. Basically, we send requests, and we don't wait for responses, we get informed when the response is there. Most of the time, the **API** users will want to wait for a response, instead of leveraging the asyncrhonous aspect of the **API**: this is the reason we have a blocking **API**, based on the non-blocking implementation. We will explain the whole thing here.
 
@@ -48,8 +49,15 @@ NOTE : **LDAP** protocol is based on **T
 
 ## Class hierarchy
 
+The **LdapConnection** interface and its implementations are the entry point for any code that wants to communicate using the **LDAP** protocol. There are many flavors, but one usually want to instanciate a **LdapNetworkConnection**. Her eis the complete class hierarchy:
+
 ![LdapConnection hierarchy](images/ldapconnection.png)
 
+Creating a new **LdapConnection** is all about calling the appropriate constructor with the required parameters, or to create a **LdapConnectionConfig** and call the **LdapConnection** implementation constructor.
+
+It's also possible to use a **LdapConnectionFactory** implementation :
+
+![LdapConnection factory hierarchy](images/ldap-connection-factory.png)
 
 ## MINA usage
 
@@ -65,7 +73,7 @@ Currently, we have a dedicated **MINA* m
 
 ### Initialization
 
-The initialization is done in the _LdapnetworkConnection.connect_ method :
+The initialization is done in the _LdapnetworkConnection.connect()_ method :
 
     :::Java
     public boolean connect() throws LdapException
@@ -78,7 +86,7 @@ The initialization is done in the _Ldapn
              createConnector();
          }
 
-and the private _createConnector_ method does all the work :
+and the private _createConnector()_ method does all the work :
 
     :::Java
     private void createConnector() throws LdapException
@@ -117,6 +125,8 @@ A few things :
 
 This private class should be moved to another class in the **MINA** module.
 
+Note : We could share the _Connector_ between many **LdapConnections**, using less threads.
+
 #### Example : using a LdapConnectionConfig
 
 Here is an example on how we can create and use a _LdapConnectionConfig_ to set up a secured connection :
@@ -138,7 +148,7 @@ Here is an example on how we can create
 
 ### MINA Events processing
 
-There are two aspects we need to consider when it comes to use **MINA** :
+There are many aspects we need to consider when it comes to use **MINA** :
 
 * events processing
 * sending a message
@@ -157,6 +167,7 @@ There are two aspects we need to conside
 * _sessionCreated_ : When a Session is created
 * _sessionIdle_ : When a Session is idle
 * _sessionOpened_ : When a Session is opened
+* _event_ : when the session receives a specific event
 
 The _session_ is created when you connect for the first time, it's atcive until it's closed. We are talking about a **TCP** session, not a **LDAP** session.
 
@@ -294,6 +305,12 @@ This class, which is part of the _mina_
 What is important to remember is that **TCP** is not dealing with **LDAP** messages, but with bytes. The decoder must be able to start decoding a message, even if it does not have all the necessary bytes to decode a full **LDAP** message. It should also be able to decode more than one message if the bytes it received contains more than the bytes necessary to hold a message. All of this is handle by MINA anyway, but we must provide a way for the decoder to keep the current state. Check the [codec](codec.html) page for more explainations.
 
 
+## SSL Handling
+
+**LDAPS** is a **LDAP** connection secured with **SSL/TLS** (we still use **SSL** as a name, when actually **TLS** is used, as **SSL** is not anymore safe. The currrent version of the protocol is **TLS V.12**, but **TLS v1.3** has just been released.)
+
+A **LDAPS** connection is a standard **TCP** connection which has a secured layer installed before it can be used. 
+
 ## StartTLS Handling
 
 The **StartTLS** extended operation is a bit specific, as it is set over an existing connection, and based on a **LDAP** message being sent to the remote server. The big plus is that it uses the standard **LDAP** port, so there is no need to declare a dedicated port for a secured connection (aka **LDAPS**).

Added: directory/site/trunk/content/api/internal-design-guide/images/ldap-connection-factory.graphml
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/internal-design-guide/images/ldap-connection-factory.graphml?rev=1838371&view=auto
==============================================================================
--- directory/site/trunk/content/api/internal-design-guide/images/ldap-connection-factory.graphml (added)
+++ directory/site/trunk/content/api/internal-design-guide/images/ldap-connection-factory.graphml Sun Aug 19 09:32:47 2018
@@ -0,0 +1,117 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:java="http://www.yworks.com/xml/yfiles-common/1.0/java" xmlns:sys="http://www.yworks.com/xml/yfiles-common/markup/primitives/2.0" xmlns:x="http://www.yworks.com/xml/yfiles-common/markup/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:y="http://www.yworks.com/xml/graphml" xmlns:yed="http://www.yworks.com/xml/yed/3" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://www.yworks.com/xml/schema/graphml/1.1/ygraphml.xsd">
+  <!--Created by yEd 3.17-->
+  <key attr.name="Description" attr.type="string" for="graph" id="d0"/>
+  <key for="port" id="d1" yfiles.type="portgraphics"/>
+  <key for="port" id="d2" yfiles.type="portgeometry"/>
+  <key for="port" id="d3" yfiles.type="portuserdata"/>
+  <key attr.name="url" attr.type="string" for="node" id="d4"/>
+  <key attr.name="description" attr.type="string" for="node" id="d5"/>
+  <key for="node" id="d6" yfiles.type="nodegraphics"/>
+  <key for="graphml" id="d7" yfiles.type="resources"/>
+  <key attr.name="url" attr.type="string" for="edge" id="d8"/>
+  <key attr.name="description" attr.type="string" for="edge" id="d9"/>
+  <key for="edge" id="d10" yfiles.type="edgegraphics"/>
+  <graph edgedefault="directed" id="G">
+    <data key="d0"/>
+    <node id="n0">
+      <data key="d6">
+        <y:GenericNode configuration="ShinyPlateNodeWithShadow">
+          <y:Geometry height="30.0" width="181.04207932514942" x="985.0" y="419.5"/>
+          <y:Fill color="#FFCC99" transparent="false"/>
+          <y:BorderStyle hasColor="false" type="line" width="1.0"/>
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="18.1328125" horizontalTextPosition="center" iconTextGap="4" modelName="custom" textColor="#000000" verticalTextPosition="bottom" visible="true" width="140.552734375" x="20.24467247507482" y="5.93359375">LdapConnectionFactory<y:LabelModel>
+              <y:SmartNodeLabelModel distance="4.0"/>
+            </y:LabelModel>
+            <y:ModelParameter>
+              <y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/>
+            </y:ModelParameter>
+          </y:NodeLabel>
+        </y:GenericNode>
+      </data>
+    </node>
+    <node id="n1">
+      <data key="d6">
+        <y:GenericNode configuration="ShinyPlateNodeWithShadow">
+          <y:Geometry height="30.0" width="181.04207932514942" x="985.0" y="512.0"/>
+          <y:Fill color="#CCFFCC" transparent="false"/>
+          <y:BorderStyle hasColor="false" type="line" width="1.0"/>
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="18.1328125" horizontalTextPosition="center" iconTextGap="4" modelName="custom" textColor="#000000" verticalTextPosition="bottom" visible="true" width="182.669921875" x="-0.8139212749251783" y="5.93359375">DefaultLdapConnectionFactory<y:LabelModel>
+              <y:SmartNodeLabelModel distance="4.0"/>
+            </y:LabelModel>
+            <y:ModelParameter>
+              <y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/>
+            </y:ModelParameter>
+          </y:NodeLabel>
+        </y:GenericNode>
+      </data>
+    </node>
+    <node id="n2">
+      <data key="d6">
+        <y:GenericNode configuration="ShinyPlateNodeWithShadow">
+          <y:Geometry height="30.0" width="181.04207932514942" x="803.9579206748506" y="606.0"/>
+          <y:Fill color="#CCFFCC" transparent="false"/>
+          <y:BorderStyle hasColor="false" type="line" width="1.0"/>
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="18.1328125" horizontalTextPosition="center" iconTextGap="4" modelName="custom" textColor="#000000" verticalTextPosition="bottom" visible="true" width="171.419921875" x="4.811078725074822" y="5.93359375">MockLdapConnectionFactory<y:LabelModel>
+              <y:SmartNodeLabelModel distance="4.0"/>
+            </y:LabelModel>
+            <y:ModelParameter>
+              <y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/>
+            </y:ModelParameter>
+          </y:NodeLabel>
+        </y:GenericNode>
+      </data>
+    </node>
+    <node id="n3">
+      <data key="d6">
+        <y:GenericNode configuration="ShinyPlateNodeWithShadow">
+          <y:Geometry height="30.0" width="213.04207932514942" x="1157.0420793251492" y="616.0"/>
+          <y:Fill color="#CCFFCC" transparent="false"/>
+          <y:BorderStyle hasColor="false" type="line" width="1.0"/>
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="18.1328125" horizontalTextPosition="center" iconTextGap="4" modelName="custom" textColor="#000000" verticalTextPosition="bottom" visible="true" width="191.236328125" x="10.902875600074822" y="5.93359375">TrackingLdapConnectionFactory<y:LabelModel>
+              <y:SmartNodeLabelModel distance="4.0"/>
+            </y:LabelModel>
+            <y:ModelParameter>
+              <y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/>
+            </y:ModelParameter>
+          </y:NodeLabel>
+        </y:GenericNode>
+      </data>
+    </node>
+    <edge id="e0" source="n1" target="n0">
+      <data key="d10">
+        <y:PolyLineEdge>
+          <y:Path sx="0.0" sy="0.0" tx="0.0" ty="0.0"/>
+          <y:LineStyle color="#000000" type="line" width="1.0"/>
+          <y:Arrows source="none" target="transparent_circle"/>
+          <y:BendStyle smoothed="false"/>
+        </y:PolyLineEdge>
+      </data>
+    </edge>
+    <edge id="e1" source="n2" target="n1">
+      <data key="d9"/>
+      <data key="d10">
+        <y:PolyLineEdge>
+          <y:Path sx="0.0" sy="0.0" tx="0.0" ty="0.0"/>
+          <y:LineStyle color="#000000" type="line" width="1.0"/>
+          <y:Arrows source="none" target="white_delta"/>
+          <y:BendStyle smoothed="false"/>
+        </y:PolyLineEdge>
+      </data>
+    </edge>
+    <edge id="e2" source="n3" target="n1">
+      <data key="d9"/>
+      <data key="d10">
+        <y:PolyLineEdge>
+          <y:Path sx="0.0" sy="0.0" tx="0.0" ty="0.0"/>
+          <y:LineStyle color="#000000" type="line" width="1.0"/>
+          <y:Arrows source="none" target="white_delta"/>
+          <y:BendStyle smoothed="false"/>
+        </y:PolyLineEdge>
+      </data>
+    </edge>
+  </graph>
+  <data key="d7">
+    <y:Resources/>
+  </data>
+</graphml>

Added: directory/site/trunk/content/api/internal-design-guide/images/ldap-connection-factory.png
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/internal-design-guide/images/ldap-connection-factory.png?rev=1838371&view=auto
==============================================================================
Binary file - no diff available.

Propchange: directory/site/trunk/content/api/internal-design-guide/images/ldap-connection-factory.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream