svn commit: r1024163 - in /websites/staging/directory/trunk/content: ./ api/internal-design-guide/ api/internal-design-guide/images/

[bu...@apache.org]

Author: buildbot
Date: Tue Jan 23 00:08:49 2018
New Revision: 1024163

Log:
Staging update by buildbot for directory

Added:
    websites/staging/directory/trunk/content/api/internal-design-guide/images/extended-request-decorator.graphml   (with props)
    websites/staging/directory/trunk/content/api/internal-design-guide/images/extended-request-decorator.png   (with props)
Modified:
    websites/staging/directory/trunk/content/   (props changed)
    websites/staging/directory/trunk/content/api/internal-design-guide/14-extended-operations.html

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

Modified: websites/staging/directory/trunk/content/api/internal-design-guide/14-extended-operations.html
==============================================================================
--- websites/staging/directory/trunk/content/api/internal-design-guide/14-extended-operations.html (original)
+++ websites/staging/directory/trunk/content/api/internal-design-guide/14-extended-operations.html Tue Jan 23 00:08:49 2018
@@ -185,7 +185,91 @@
 }
 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="14-extended-operations">14 - Extended Operations<a class="headerlink" href="#14-extended-operations" title="Permanent link">&para;</a></h1>
-<p>TODO...</p>
+<p><strong>Extended Operation</strong> is a <strong>LDAP</strong> message which may content a payload. It is generally sent by the clinet, but the server can send a <em>ExtendedResponse</em> as a response to any operation : the <strong>Notice of Disconnection</strong>. </p>
+<p>Here is the syntax for the extended Operation :</p>
+<div class="codehilite"><pre>ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
+    requestName      [0] LDAPOID,
+    requestValue     [1] OCTET STRING OPTIONAL }
+
+ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
+    COMPONENTS OF LDAPResult,
+    responseName     [10] LDAPOID OPTIONAL,
+    responseValue    [11] OCTET STRING OPTIONAL }
+</pre></div>
+
+
+<p>(the payload is the <em>requestValue</em> or <em>responseValue</em> part, which may be <strong>BER</strong> encoded).</p>
+<p>This message is routinely decoded as is by the standard <strong>LDAP</strong> message decoder, but the payload has to be decoded on its own. </p>
+<h2 id="supported-extended-operations">Supported extended operations<a class="headerlink" href="#supported-extended-operations" title="Permanent link">&para;</a></h2>
+<p>Currently, the <strong>LDAP API</strong> support the following extended operations :</p>
+<ul>
+<li><em>Cancel</em> request and response (<a href="https://tools.ietf.org/html/rfc3909">RFC 3909</a>)</li>
+<li><em>CertGenerationRequest</em> request and response, an <strong>ApacheDS</strong> specific operation in charge of generating a certificate</li>
+<li><em>GracefulDisconnect</em> response,  an <strong>ApacheDS</strong> specific operation used when the server is shutdown properly</li>
+<li><em>GracefulShutdown</em> request and response, an <strong>ApacheDS</strong> specific operation used to shutdown the remote server properly</li>
+<li><em>PasswordModify</em> request and response (<a href="https://tools.ietf.org/html/rfc3062">RFC 3062</a>)</li>
+<li><em>StartTls</em> request and response (<a href="https://tools.ietf.org/html/rfc4511">RFC 4511</a>)</li>
+<li><em>StoredProcedure</em> request and response, an <strong>ApacheDS</strong> specific operation used to execute a stored procedure on the server</li>
+<li><em>WhoAmI</em> request and response (<a href="https://tools.ietf.org/html/rfc4532">RFC 4532</a>)</li>
+</ul>
+<h2 id="encoding-and-decoding">Encoding and decoding<a class="headerlink" href="#encoding-and-decoding" title="Permanent link">&para;</a></h2>
+<p>When the <em>requestValue</em> part is present, it has to be encoded (when the client sends the request to the srrver) or decoded ( when the client receives the response from the server).</p>
+<h3 id="decoding-a-request">Decoding a request<a class="headerlink" href="#decoding-a-request" title="Permanent link">&para;</a></h3>
+<p>The payload is decoded on the fly when the request is processed during the <em>extendedRequest</em> is being decoded. The <em>StoreExtendedRequestValue</em> will store the <em>byte[]</em> - if any - and depending on the operation, the specific request will decode the value. Here is the <em>action</em> method for the <em>StoreExtendedRequestValue</em> class :</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span class="kt">void</span> <span class="nf">action</span><span class="o">(</span> <span class="n">LdapMessageContainer</span><span class="o">&lt;</span><span class="n">ExtendedRequestDecorator</span><span class="o">&lt;?&gt;&gt;</span> <span class="n">container</span> <span class="o">)</span> <span class="kd">throws</span> <span class="n">DecoderException</span>
+<span class="o">{</span>
+    <span class="c1">// We can allocate the ExtendedRequest Object</span>
+    <span class="n">ExtendedRequestDecorator</span><span class="o">&lt;?&gt;</span> <span class="n">extendedRequest</span> <span class="o">=</span> <span class="n">container</span><span class="o">.</span><span class="na">getMessage</span><span class="o">();</span>
+
+    <span class="c1">// Get the Value and store it in the ExtendedRequest</span>
+    <span class="n">TLV</span> <span class="n">tlv</span> <span class="o">=</span> <span class="n">container</span><span class="o">.</span><span class="na">getCurrentTLV</span><span class="o">();</span>
+
+    <span class="c1">// We have to handle the special case of a 0 length matched</span>
+    <span class="c1">// value</span>
+    <span class="k">if</span> <span class="o">(</span> <span class="n">tlv</span><span class="o">.</span><span class="na">getLength</span><span class="o">()</span> <span class="o">==</span> <span class="mi">0</span> <span class="o">)</span>
+    <span class="o">{</span>
+        <span class="n">extendedRequest</span><span class="o">.</span><span class="na">setRequestValue</span><span class="o">(</span> <span class="n">Strings</span><span class="o">.</span><span class="na">EMPTY_BYTES</span> <span class="o">);</span>
+    <span class="o">}</span>
+    <span class="k">else</span>
+    <span class="o">{</span>
+        <span class="n">extendedRequest</span><span class="o">.</span><span class="na">setRequestValue</span><span class="o">(</span> <span class="n">tlv</span><span class="o">.</span><span class="na">getValue</span><span class="o">().</span><span class="na">getData</span><span class="o">()</span> <span class="o">);</span>
+    <span class="o">}</span>
+</pre></div>
+
+
+<p>Each implementaion may have a <em>setRequestValue</em> methd, overloading the parentclass. In this case, the value is decoded by the method.</p>
+<p>Here is an example of <em>setRequestValue</em> implementation (for the <em>PasswordModifyRequest</em> class) :</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span class="kt">void</span> <span class="nf">setRequestValue</span><span class="o">(</span> <span class="kt">byte</span><span class="o">[]</span> <span class="n">requestValue</span> <span class="o">)</span>
+<span class="o">{</span>
+    <span class="n">PasswordModifyRequestDecoder</span> <span class="n">decoder</span> <span class="o">=</span> <span class="k">new</span> <span class="n">PasswordModifyRequestDecoder</span><span class="o">();</span>
+
+    <span class="k">try</span>
+    <span class="o">{</span>
+        <span class="k">if</span> <span class="o">(</span> <span class="n">requestValue</span> <span class="o">!=</span> <span class="kc">null</span> <span class="o">)</span>
+        <span class="o">{</span>
+            <span class="n">passwordModifyRequest</span> <span class="o">=</span> <span class="n">decoder</span><span class="o">.</span><span class="na">decode</span><span class="o">(</span> <span class="n">requestValue</span> <span class="o">);</span>
+
+            <span class="k">this</span><span class="o">.</span><span class="na">requestValue</span> <span class="o">=</span> <span class="k">new</span> <span class="kt">byte</span><span class="o">[</span><span class="n">requestValue</span><span class="o">.</span><span class="na">length</span><span class="o">];</span>
+            <span class="n">System</span><span class="o">.</span><span class="na">arraycopy</span><span class="o">(</span> <span class="n">requestValue</span><span class="o">,</span> <span class="mi">0</span><span class="o">,</span> <span class="k">this</span><span class="o">.</span><span class="na">requestValue</span><span class="o">,</span> <span class="mi">0</span><span class="o">,</span> <span class="n">requestValue</span><span class="o">.</span><span class="na">length</span> <span class="o">);</span>
+        <span class="o">}</span>
+        <span class="k">else</span>
+        <span class="o">{</span>
+            <span class="k">this</span><span class="o">.</span><span class="na">requestValue</span> <span class="o">=</span> <span class="kc">null</span><span class="o">;</span>
+        <span class="o">}</span>
+    <span class="o">}</span>
+    <span class="k">catch</span> <span class="o">(</span> <span class="n">DecoderException</span> <span class="n">e</span> <span class="o">)</span>
+    <span class="o">{</span>
+        <span class="n">LOG</span><span class="o">.</span><span class="na">error</span><span class="o">(</span> <span class="n">I18n</span><span class="o">.</span><span class="na">err</span><span class="o">(</span> <span class="n">I18n</span><span class="o">.</span><span class="na">ERR_04165</span> <span class="o">),</span> <span class="n">e</span> <span class="o">);</span>
+        <span class="k">throw</span> <span class="k">new</span> <span class="nf">RuntimeException</span><span class="o">(</span> <span class="n">e</span> <span class="o">);</span>
+    <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>As we can see, the decoder is invoked if the <em>requestValye</em> bytes is not null. It instanciate a <em>PasswordModifyRequest</em>.</p>
+<p>If there is no payload, the parent's method is invoked (which basically does nothing).</p>
+<p>Here is a schema showing which operation as a payload that needs to be decoded :</p>
+<p><img alt="Extended Operations Payload" src="images/extended-request-decorator.png" /></p>
 
 
     <div class="nav">

Added: websites/staging/directory/trunk/content/api/internal-design-guide/images/extended-request-decorator.graphml
==============================================================================
Binary file - no diff available.

Propchange: websites/staging/directory/trunk/content/api/internal-design-guide/images/extended-request-decorator.graphml
------------------------------------------------------------------------------
    svn:mime-type = application/xml

Added: websites/staging/directory/trunk/content/api/internal-design-guide/images/extended-request-decorator.png
==============================================================================
Binary file - no diff available.

Propchange: websites/staging/directory/trunk/content/api/internal-design-guide/images/extended-request-decorator.png
------------------------------------------------------------------------------
    svn:mime-type = image/png