svn commit: r1024164 - in /websites/staging/directory/trunk/content: ./ api/internal-design-guide/5-network.html

[bu...@apache.org]

Author: buildbot
Date: Tue Jan 23 00:08:59 2018
New Revision: 1024164

Log:
Staging update by buildbot for directory

Modified:
    websites/staging/directory/trunk/content/   (props changed)
    websites/staging/directory/trunk/content/api/internal-design-guide/5-network.html

Propchange: websites/staging/directory/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Tue Jan 23 00:08:59 2018
@@ -1 +1 @@
-1821949
+1821950

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 Tue Jan 23 00:08:59 2018
@@ -191,6 +191,84 @@ h2:hover > .headerlink, h3:hover > .head
 <h2 id="class-hierarchy">Class hierarchy<a class="headerlink" href="#class-hierarchy" title="Permanent link">&para;</a></h2>
 <p><img alt="LdapConnection hierarchy" src="images/ldapconnection.png" /></p>
 <h2 id="mina-usage">MINA usage<a class="headerlink" href="#mina-usage" title="Permanent link">&para;</a></h2>
+<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>
+<ul>
+<li><em>IoHandler</em> which is the part of the application that receives or sends messages, and manage the connection to the remote peer</li>
+<li><em>ProtocolDecoder</em> and <em>ProtoclEncoder</em> which is responsible for encoding a meassage to a <em>byte[]</em> ready to be sent or to produce a message from a received <em>byte[]</em></li>
+<li><em>ProtocolCodecFactory</em> which is the factory that instanciates the encoder and decoder</li>
+</ul>
+<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** module-.</p>
+<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>
+<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>
+
+     <span class="c1">// Create the connector if needed</span>
+     <span class="k">if</span> <span class="o">(</span> <span class="n">connector</span> <span class="o">==</span> <span class="kc">null</span> <span class="o">)</span>
+     <span class="o">{</span>
+         <span class="n">createConnector</span><span class="o">();</span>
+     <span class="o">}</span>
+</pre></div>
+
+
+<p>and the private <em>createConnector</em> method does all the work :</p>
+<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>
+    <span class="n">connector</span> <span class="o">=</span> <span class="k">new</span> <span class="n">NioSocketConnector</span><span class="o">(</span> <span class="mi">1</span> <span class="o">);</span>
+
+    <span class="k">if</span> <span class="o">(</span> <span class="n">connectionConfig</span> <span class="o">!=</span> <span class="kc">null</span> <span class="o">)</span>
+    <span class="o">{</span>
+        <span class="o">(</span> <span class="o">(</span> <span class="n">SocketSessionConfig</span> <span class="o">)</span> <span class="n">connector</span><span class="o">.</span><span class="na">getSessionConfig</span><span class="o">()</span> <span class="o">).</span><span class="na">setAll</span><span class="o">(</span> <span class="n">connectionConfig</span> <span class="o">);</span>
+    <span class="o">}</span>
+    <span class="k">else</span>
+    <span class="o">{</span>
+        <span class="o">(</span> <span class="o">(</span> <span class="n">SocketSessionConfig</span> <span class="o">)</span> <span class="n">connector</span><span class="o">.</span><span class="na">getSessionConfig</span><span class="o">()</span> <span class="o">).</span><span class="na">setReuseAddress</span><span class="o">(</span> <span class="kc">true</span> <span class="o">);</span>
+    <span class="o">}</span>
+
+    <span class="c1">// Add the codec to the chain</span>
+    <span class="n">connector</span><span class="o">.</span><span class="na">getFilterChain</span><span class="o">().</span><span class="na">addLast</span><span class="o">(</span> <span class="s">&quot;ldapCodec&quot;</span><span class="o">,</span> <span class="n">ldapProtocolFilter</span> <span class="o">);</span>
+
+    <span class="c1">// If we use SSL, we have to add the SslFilter to the chain</span>
+    <span class="k">if</span> <span class="o">(</span> <span class="n">config</span><span class="o">.</span><span class="na">isUseSsl</span><span class="o">()</span> <span class="o">)</span>
+    <span class="o">{</span>
+        <span class="n">addSslFilter</span><span class="o">();</span>
+    <span class="o">}</span>
+
+    <span class="c1">// Inject the protocolHandler</span>
+    <span class="n">connector</span><span class="o">.</span><span class="na">setHandler</span><span class="o">(</span> <span class="k">this</span> <span class="o">);</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>A few things :</p>
+<ul>
+<li>We use one thread as a default to handle the communication with the server, it's enough as we are only talking to one server anyawy. This is the reason we use '1' as a parameter to the <em>Connector</em> constructor.</li>
+<li>We may have a SocketSessionConfig instance, as soon as one is passed to the <em>LdapNetworkConnection</em> instance before the first call to the <em>connect</em> method is done. By default, we just set the <em>SO_REUSE</em> flag.</li>
+<li>We add one or two filters to the chain : the <strong>codec</strong> and the <strong>SSL</strong> filter, if needed. The <strong>SSL</strong> filter requires that a <em>LdapConnectionConfig</em> instance is passed to the constructor.</li>
+<li>As we can see, the <em>LdapNetwworkConnection</em> class is the <em>IoHandler</em> implementation.</li>
+</ul>
+<p>This private class should be moved to another class in the <strong>MINA</strong> module.</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 class="o">();</span>
+<span class="n">sslConfig</span><span class="o">.</span><span class="na">setLdapHost</span><span class="o">(</span> <span class="n">Network</span><span class="o">.</span><span class="na">LOOPBACK_HOSTNAME</span> <span class="o">);</span>
+<span class="n">sslConfig</span><span class="o">.</span><span class="na">setUseSsl</span><span class="o">(</span> <span class="kc">true</span> <span class="o">);</span>
+<span class="n">sslConfig</span><span class="o">.</span><span class="na">setLdapPort</span><span class="o">(</span> <span class="n">getLdapServer</span><span class="o">().</span><span class="na">getPortSSL</span><span class="o">()</span> <span class="o">);</span>
+<span class="n">sslConfig</span><span class="o">.</span><span class="na">setTrustManagers</span><span class="o">(</span> <span class="k">new</span> <span class="n">NoVerificationTrustManager</span><span class="o">()</span> <span class="o">);</span>
+<span class="n">sslConfig</span><span class="o">.</span><span class="na">setBinaryAttributeDetector</span><span class="o">(</span> <span class="k">new</span> <span class="n">SchemaBinaryAttributeDetector</span><span class="o">(</span>
+        <span class="n">ldapServer</span><span class="o">.</span><span class="na">getDirectoryService</span><span class="o">().</span><span class="na">getSchemaManager</span><span class="o">()</span> <span class="o">)</span> <span class="o">);</span>
+
+<span class="k">try</span> <span class="o">(</span> <span class="n">LdapNetworkConnection</span> <span class="n">connection</span> <span class="o">=</span> <span class="k">new</span> <span class="n">LdapNetworkConnection</span><span class="o">(</span> <span class="n">sslConfig</span> <span class="o">)</span> <span class="o">)</span>
+    <span class="o">{</span>
+        <span class="n">connection</span><span class="o">.</span><span class="na">bind</span><span class="o">(</span> <span class="s">&quot;uid=admin,ou=system&quot;</span><span class="o">,</span> <span class="s">&quot;secret&quot;</span> <span class="o">);</span>
+        <span class="o">...</span>
+</pre></div>
+
+
+<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>
 <ul>
 <li>events processing</li>
@@ -325,6 +403,8 @@ 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> module.</p>
+<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>
 
 
     <div class="nav">