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

[bu...@apache.org]

Author: buildbot
Date: Thu Mar 29 08:48:12 2018
New Revision: 1027547

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 Thu Mar 29 08:48:12 2018
@@ -1 +1 @@
-1825469
+1827964

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 Thu Mar 29 08:48:12 2018
@@ -185,6 +185,71 @@
 }
 h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
 <h1 id="5-network">5 - Network<a class="headerlink" href="#5-network" title="Permanent link">&para;</a></h1>
+<h1 id="content">Content<a class="headerlink" href="#content" title="Permanent link">&para;</a></h1>
+<ul>
+<li><a href="class-hierarchy">Class hierarchy</a></li>
+<li><a href="mina-usage">MINA usage</a></li>
+<li>
+<ul>
+<li><a href="initialization">Initialization</a></li>
+</ul>
+</li>
+<li>
+<ul>
+<li>
+<ul>
+<li><a href="example-using-a-ldapconnectionconfig">Example : using a LdapConnectionConfig</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li>
+<ul>
+<li><a href="mina-events-processing">MINA Events processing</a></li>
+</ul>
+</li>
+<li>
+<ul>
+<li>
+<ul>
+<li><a href="events-processing">Events processing</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li>
+<ul>
+<li>
+<ul>
+<li><a href="sending-a-message">Sending a message</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li>
+<ul>
+<li>
+<ul>
+<li><a href="receiving-a-message">Receiving a message</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li>
+<ul>
+<li>
+<ul>
+<li><a href="encoding-decoding">Encoding/decoding</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li>
+<ul>
+<li><a href="startts-handling">StartTLS handling</a></li>
+</ul>
+</li>
+</ul>
 <p>The <strong>Apache LDAP AP</strong> is built on top of <a href="http://mina.apache.org">**Apache MINA</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>
@@ -276,7 +341,7 @@ h2:hover > .headerlink, h3:hover > .head
 <li>receiving a message</li>
 <li>encoding/decoding</li>
 </ul>
-<h3 id="events-processing">Events processing<a class="headerlink" href="#events-processing" title="Permanent link">&para;</a></h3>
+<h4 id="events-processing">Events processing<a class="headerlink" href="#events-processing" title="Permanent link">&para;</a></h4>
 <p><strong>MINA</strong> is an asynchronous framework, which means it's event based : you will receive events when something 'happens' (like, a message is received, etc). The events have to be processed by the <strong>LDAP API</strong>, and the <strong>IoHandler</strong> interface is listing all the events we have to process. Here they are :</p>
 <ul>
 <li><em>messageReceived</em> : When a message has been fully received from the remote peer</li>
@@ -292,7 +357,7 @@ h2:hover > .headerlink, h3:hover > .head
 <p>So the <em>LdapNetworkConnection</em> class must implement those methods.</p>
 <p>Regarding the <em>messageReceived/messageSent</em> methods, it's important to know that we are talking about <strong>FULL</strong> <strong>LDAP</strong> messages, even if <strong>TCP</strong> does not guarantee that messages can't be fragmented : <strong>MINA</strong> deal with fragmentation.</p>
 <p>Actually, we only implement the <em>messageReceived</em>, <em>exceptionCaught</em>, <em>inputClose</em>, <em>sessionCreated</em> and <em>sessionClosed</em> methods, the other are handled by the <em>IoHandlerAdpater</em> methods (which does nothing with it).</p>
-<h3 id="sending-a-message">Sending a message<a class="headerlink" href="#sending-a-message" title="Permanent link">&para;</a></h3>
+<h4 id="sending-a-message">Sending a message<a class="headerlink" href="#sending-a-message" title="Permanent link">&para;</a></h4>
 <p>There are two modes : <strong>Synchronous</strong> and <strong>Asyncrhonous</strong>. The methods are respectively described in the <em>LdapConnection</em> interface and <em>LdapAsyncConnection</em> interface. Actually, <em>synchronous</em> methods are calling <em>asynchronous</em> methods, which returns a <em>Future</em> :</p>
 <div class="codehilite"><pre><span class="cm">/**</span>
 <span class="cm"> * {@inheritDoc}</span>
@@ -384,10 +449,10 @@ h2:hover > .headerlink, h3:hover > .head
 
 <p>Here, we first create a connection if we don't have one yet, and then we try to write the message to the remote server, and wait for the message to be sent. That means sending message is synchronous, while receiving is aysnchronous by default. (NOTE : This may change in the next version.)</p>
 <p>Once the request has been written, we do a <em>get</em> on the returned <em>Future</em>. Either we get an <em>AddResponse</em>, or an error/timeout.</p>
-<h3 id="receiving-a-message">Receiving a message<a class="headerlink" href="#receiving-a-message" title="Permanent link">&para;</a></h3>
+<h4 id="receiving-a-message">Receiving a message<a class="headerlink" href="#receiving-a-message" title="Permanent link">&para;</a></h4>
 <p>Once the <em>IoSession.write()</em> method is called, we can assume the message has been sent to the remote server (sort of). The response will come as an event : <em>messageReceived()</em>, which is implemented in <em>LdapNetworkConnection</em>.</p>
 <p>Each <strong>LDAP</strong> message has a unique <strong>ID</strong>, and every sent message is associated with a <em>Future</em>. When the message is sent, we store a tuple &lt;<strong>ID</strong>, <strong>Future</strong>&gt; in a map, so when the response arrives, we just have to pull the <em>Future</em> from the map using teh message <strong>ID</strong>. This is what we do in the <em>messageReceived()</em> implementation. The response is enqueued in the <em>Future</em> (we may have more than one, typically for <strong>Search</strong> operations).</p>
-<h3 id="encodingdecoding">Encoding/decoding<a class="headerlink" href="#encodingdecoding" title="Permanent link">&para;</a></h3>
+<h4 id="encodingdecoding">Encoding/decoding<a class="headerlink" href="#encodingdecoding" title="Permanent link">&para;</a></h4>
 <p>Messages are encoded and decoded when we send or receive them. This is done by <strong>MINA</strong>, using a callback in the <strong>LDAP API</strong>. That means we configured <strong>MINA</strong> to process <strong>LDAP</strong> messages. </p>
 <p>The codec is inserted in <strong>MINA</strong> chain while connecting :</p>
 <div class="codehilite"><pre><span class="cm">/** The Ldap codec protocol filter */</span>