directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r1034164 - in /websites/staging/directory/trunk/content: ./ api/internal-design-guide/5-network.html api/internal-design-guide/images/ldap-connection-factory.graphml api/internal-design-guide/images/ldap-connection-factory.png
Date Sun, 19 Aug 2018 09:32:56 GMT
Author: buildbot
Date: Sun Aug 19 09:32:55 2018
New Revision: 1034164

Staging update by buildbot for directory

  (with props)
  (with props)
    websites/staging/directory/trunk/content/   (props changed)

Propchange: websites/staging/directory/trunk/content/
--- cms:source-revision (original)
+++ cms:source-revision Sun Aug 19 09:32:55 2018
@@ -1 +1 @@

Modified: websites/staging/directory/trunk/content/api/internal-design-guide/5-network.html
--- websites/staging/directory/trunk/content/api/internal-design-guide/5-network.html (original)
+++ websites/staging/directory/trunk/content/api/internal-design-guide/5-network.html Sun
Aug 19 09:32:55 2018
@@ -204,13 +204,18 @@ h2:hover > .headerlink, h3:hover > .head
 <li><a href="#encoding-decoding">Encoding/decoding</a></li>
+<li><a href="#ssl-handling">SSL handling</a></li>
 <li><a href="#startts-handling">StartTLS handling</a></li>
-<p>The <strong>Apache LDAP AP</strong> is built on top of <a href="">**Apache
MINA</a> which is a <strong>NIO</strong> framework. </p>
+<p>The <strong>Apache LDAP AP</strong> is built on top of <a href=""><strong>Apache
MINA</strong></a> which is a <strong>NIO</strong> framework. </p>
 <p>As <strong>MINA</strong> is fully asynchronous, it has some impact on
the design of the <strong>LDAP API</strong>. Basically, we send requests, and
we don't wait for responses, we get informed when the response is there. Most of the time,
the <strong>API</strong> users will want to wait for a response, instead of leveraging
the asyncrhonous aspect of the <strong>API</strong>: this is the reason we have
a blocking <strong>API</strong>, based on the non-blocking implementation. We
will explain the whole thing here.</p>
 <p>NOTE : <strong>LDAP</strong> protocol is based on <strong>TCP</strong>,
we are not dealing with <strong>UDP</strong> at all.</p>
 <h2 id="class-hierarchy">Class hierarchy<a class="headerlink" href="#class-hierarchy"
title="Permanent link">&para;</a></h2>
+<p>The <strong>LdapConnection</strong> interface and its implementations
are the entry point for any code that wants to communicate using the <strong>LDAP</strong>
protocol. There are many flavors, but one usually want to instanciate a <strong>LdapNetworkConnection</strong>.
Her eis the complete class hierarchy:</p>
 <p><img alt="LdapConnection hierarchy" src="images/ldapconnection.png" /></p>
+<p>Creating a new <strong>LdapConnection</strong> is all about calling
the appropriate constructor with the required parameters, or to create a <strong>LdapConnectionConfig</strong>
and call the <strong>LdapConnection</strong> implementation constructor.</p>
+<p>It's also possible to use a <strong>LdapConnectionFactory</strong> implementation
+<p><img alt="LdapConnection factory hierarchy" src="images/ldap-connection-factory.png"
 <h2 id="mina-usage">MINA usage<a class="headerlink" href="#mina-usage" title="Permanent
 <p><strong>MINA</strong> handles all the complexity of managing sockets
and transfering messages in and out. An application based on this framework just have to implement
a few interfaces :</p>
@@ -221,7 +226,7 @@ h2:hover > .headerlink, h3:hover > .head
 <p>We also have to create a <em>Connector</em>, which is the instance in
charge of managing the communication with the remote peer. That implies we properly set the
filter chain it uses, especially the <strong>SSL/TLS</strong> part.</p>
 <p>Currently, we have a dedicated <strong>MINA* module that covers a part of
that, but the <em>Connector</em> creation and initialization is done in the <em>LdapNetworkConnection</em>
class - which is a mistake, it should be delegated to a class in the </strong>MINA**
 <h3 id="initialization">Initialization<a class="headerlink" href="#initialization"
title="Permanent link">&para;</a></h3>
-<p>The initialization is done in the <em>LdapnetworkConnection.connect</em>
method :</p>
+<p>The initialization is done in the <em>LdapnetworkConnection.connect()</em>
method :</p>
 <div class="codehilite"><pre><span class="kd">public</span> <span
class="kt">boolean</span> <span class="nf">connect</span><span class="o">()</span>
<span class="kd">throws</span> <span class="n">LdapException</span>
  <span class="o">{</span>
      <span class="o">...</span>
@@ -234,7 +239,7 @@ h2:hover > .headerlink, h3:hover > .head
-<p>and the private <em>createConnector</em> method does all the work :</p>
+<p>and the private <em>createConnector()</em> method does all the work
 <div class="codehilite"><pre><span class="kd">private</span> <span
class="kt">void</span> <span class="nf">createConnector</span><span
class="o">()</span> <span class="kd">throws</span> <span class="n">LdapException</span>
 <span class="o">{</span>
     <span class="c1">// Use only one thread inside the connector</span>
@@ -272,6 +277,7 @@ h2:hover > .headerlink, h3:hover > .head
 <li>As we can see, the <em>LdapNetwworkConnection</em> class is the <em>IoHandler</em>
 <p>This private class should be moved to another class in the <strong>MINA</strong>
+<p>Note : We could share the <em>Connector</em> between many <strong>LdapConnections</strong>,
using less threads.</p>
 <h4 id="example-using-a-ldapconnectionconfig">Example : using a LdapConnectionConfig<a
class="headerlink" href="#example-using-a-ldapconnectionconfig" title="Permanent link">&para;</a></h4>
 <p>Here is an example on how we can create and use a <em>LdapConnectionConfig</em>
to set up a secured connection :</p>
 <div class="codehilite"><pre><span class="n">LdapConnectionConfig</span>
<span class="n">sslConfig</span> <span class="o">=</span> <span
class="k">new</span> <span class="n">LdapConnectionConfig</span><span
@@ -290,7 +296,7 @@ h2:hover > .headerlink, h3:hover > .head
 <h3 id="mina-events-processing">MINA Events processing<a class="headerlink" href="#mina-events-processing"
title="Permanent link">&para;</a></h3>
-<p>There are two aspects we need to consider when it comes to use <strong>MINA</strong>
+<p>There are many aspects we need to consider when it comes to use <strong>MINA</strong>
 <li>events processing</li>
 <li>sending a message</li>
@@ -308,6 +314,7 @@ h2:hover > .headerlink, h3:hover > .head
 <li><em>sessionCreated</em> : When a Session is created</li>
 <li><em>sessionIdle</em> : When a Session is idle</li>
 <li><em>sessionOpened</em> : When a Session is opened</li>
+<li><em>event</em> : when the session receives a specific event</li>
 <p>The <em>session</em> is created when you connect for the first time,
it's atcive until it's closed. We are talking about a <strong>TCP</strong> session,
not a <strong>LDAP</strong> session.</p>
 <p>So the <em>LdapNetworkConnection</em> class must implement those methods.</p>
@@ -426,6 +433,9 @@ h2:hover > .headerlink, h3:hover > .head
 <p>So the <em>ProtocolCodecFilter</em> class is responsible for initializing
the codec (it's a <strong>MINA</strong> class), and here, we use a factory to
inject the encoder and decoder instances. This factory is <em>LdapProtocolCodecFactory</em>.</p>
 <p>This class, which is part of the <em>mina</em> module, instanciate an
instance of the statefull <strong>LDAP</strong> encoder and decoder classes, <em>LdapProtocolEncoder</em>
and <em>LdapProtocolDecoder</em>, which also belongs to the <em>mina</em>
 <p>What is important to remember is that <strong>TCP</strong> is not dealing
with <strong>LDAP</strong> 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 <strong>LDAP</strong> 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 <a href="codec.html">codec</a> page for more explainations.</p>
+<h2 id="ssl-handling">SSL Handling<a class="headerlink" href="#ssl-handling" title="Permanent
+<p><strong>LDAPS</strong> is a <strong>LDAP</strong> connection
secured with <strong>SSL/TLS</strong> (we still use <strong>SSL</strong>
as a name, when actually <strong>TLS</strong> is used, as <strong>SSL</strong>
is not anymore safe. The currrent version of the protocol is <strong>TLS V.12</strong>,
but <strong>TLS v1.3</strong> has just been released.)</p>
+<p>A <strong>LDAPS</strong> connection is a standard <strong>TCP</strong>
connection which has a secured layer installed before it can be used. </p>
 <h2 id="starttls-handling">StartTLS Handling<a class="headerlink" href="#starttls-handling"
title="Permanent link">&para;</a></h2>
 <p>The <strong>StartTLS</strong> extended operation is a bit specific,
as it is set over an existing connection, and based on a <strong>LDAP</strong>
message being sent to the remote server. The big plus is that it uses the standard <strong>LDAP</strong>
port, so there is no need to declare a dedicated port for a secured connection (aka <strong>LDAPS</strong>).</p>
 <p>The logic is the following :</p>

Added: websites/staging/directory/trunk/content/api/internal-design-guide/images/ldap-connection-factory.graphml
Binary file - no diff available.

Propchange: websites/staging/directory/trunk/content/api/internal-design-guide/images/ldap-connection-factory.graphml
    svn:mime-type = application/xml

Added: websites/staging/directory/trunk/content/api/internal-design-guide/images/ldap-connection-factory.png
Binary file - no diff available.

Propchange: websites/staging/directory/trunk/content/api/internal-design-guide/images/ldap-connection-factory.png
    svn:mime-type = image/png

View raw message