directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r1023791 - in /websites/staging/directory/trunk/content: ./ api/dev-guide/4.1-asn1-tlv.html
Date Sat, 13 Jan 2018 13:08:16 GMT
Author: buildbot
Date: Sat Jan 13 13:08:16 2018
New Revision: 1023791

Log:
Staging update by buildbot for directory

Modified:
    websites/staging/directory/trunk/content/   (props changed)
    websites/staging/directory/trunk/content/api/dev-guide/4.1-asn1-tlv.html

Propchange: websites/staging/directory/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Sat Jan 13 13:08:16 2018
@@ -1 +1 @@
-1821060
+1821061

Modified: websites/staging/directory/trunk/content/api/dev-guide/4.1-asn1-tlv.html
==============================================================================
--- websites/staging/directory/trunk/content/api/dev-guide/4.1-asn1-tlv.html (original)
+++ websites/staging/directory/trunk/content/api/dev-guide/4.1-asn1-tlv.html Sat Jan 13 13:08:16
2018
@@ -183,7 +183,7 @@
   visibility: hidden;
 }
 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="4-asn1-tlv">4 - ASN/1 TLV<a class="headerlink" href="#4-asn1-tlv" title="Permanent
link">&para;</a></h1>
+<h1 id="41-asn1-tlv">4.1 - ASN/1 TLV<a class="headerlink" href="#41-asn1-tlv" title="Permanent
link">&para;</a></h1>
 <h2 id="what-are-tlvs">What are TLVs ?<a class="headerlink" href="#what-are-tlvs"
title="Permanent link">&para;</a></h2>
 <p>The acronym <strong>TLV</strong> stands for <strong>T</strong>ag,
<strong>L</strong>ength and <strong>V</strong>alue. It's a way to
encode a piece of information with a type, a length followed by the information itself. Three
points must be known:</p>
 <ul>
@@ -193,7 +193,7 @@ h2:hover > .headerlink, h3:hover > .head
 </ul>
 <h3 id="a-quick-sample">A quick sample<a class="headerlink" href="#a-quick-sample"
title="Permanent link">&para;</a></h3>
 <p>Let's begin with a simple example, without too many explanations. This is the <strong>PDU</strong>
(<strong>P</strong>acket <strong>D</strong>ata <strong>U</strong>nit)
of a LDAP <em>BindRequest</em>:</p>
-<p><img alt="TLV" src="../images/TLVs.png" /></p>
+<p><img alt="TLV" src="images/TLVs.png" /></p>
 <p>We can see in this picture that you have what is called a first level <strong>TLV</strong>.
It encapsulates other <strong>TLV</strong>s. It's basically a stream of bytes.</p>
 <h3 id="type">Type<a class="headerlink" href="#type" title="Permanent link">&para;</a></h3>
 <p>Each <strong>Type</strong> contains information about the <strong>Value</strong>
part of the <strong>TLV</strong>. It tells if the <strong>Value</strong>
is a primitive or a constructed one, which type of primitive is the value, gives some contextual
information. A <strong>Type</strong> can be coded on more than one byte. The first
3 bits give some contextual information about the <strong>Type</strong>, and the
5 following bits are either a label or the beginning of a multi-bytes label.</p>
@@ -262,6 +262,241 @@ h2:hover > .headerlink, h3:hover > .head
 
 
 <p>So the <em>Container</em> must contain the grammar, and the current
state. We may not have any action to execute, either because none is associated with the current
transition or because we are at the end of the message.</p>
+<h3 id="tlv-implementation">TLV implementation<a class="headerlink" href="#tlv-implementation"
title="Permanent link">&para;</a></h3>
+<p>The <strong>TLV</strong> class stores the <strong>Type</strong>,
<strong>Length</strong> and <strong>Value</strong>, plus some extra
information, like a unique <em>id</em>, a reference to its parent's <strong>TLV</strong>
and the expected length when the included <strong>Value</strong> is a set of <strong>TLV</strong>.</p>
+<p><img alt="TLV/BerValue" src="images/tlv-bervalue.png" /></p>
+<p>You won't have tp manipulate <strong>TLV</strong> frequently, except
in the actions, where you might fetch its <em>Length<strong> and </strong>Value</em>*
content, using <em>getLength()</em> and <em>getValue().getData()</em>
methods respectively.</p>
+<h3 id="action">Action<a class="headerlink" href="#action" title="Permanent link">&para;</a></h3>
+<p>This is quite a simple class and hierarchy :</p>
+<p><img alt="GrammarAction" src="images/grammar-action.png" /></p>
+<p>As we can see, each <strong>Action</strong> has a name (this is only
used for debug purpose) and a <em>action(Asn1Container)</em> method, which does
what it needs. The <em>Asn1Container</em> parameter gives access to the data through
the <em>Asn1Container.getCurrentTLV().getValue().getData()</em> method, and to
the message being processed.</p>
+<p>At this point, an example would be useful.</p>
+<h2 id="example">Example<a class="headerlink" href="#example" title="Permanent link">&para;</a></h2>
+<p>Let say we want to implement a decoder for the following message :</p>
+<div class="codehilite"><pre><span class="n">EntryChangeNotification</span>
<span class="p">::=</span> <span class="n">SEQUENCE</span>
+<span class="p">{</span>
+    <span class="n">changeType</span> <span class="n">ENUMERATED</span>
+    <span class="p">{</span>
+        <span class="n">add</span>             <span class="p">(</span>1<span
class="p">),</span>
+        <span class="n">delete</span>          <span class="p">(</span>2<span
class="p">),</span>
+        <span class="n">modify</span>          <span class="p">(</span>4<span
class="p">),</span>
+        <span class="n">modDN</span>           <span class="p">(</span>8<span
class="p">)</span>
+    <span class="p">},</span>
+    <span class="n">previousDN</span>   <span class="n">LDAPDN</span>
<span class="n">OPTIONAL</span><span class="p">,</span>     <span
class="o">--</span> <span class="n">modifyDN</span> <span class="n">ops</span><span
class="p">.</span> <span class="n">only</span>
+    <span class="n">changeNumber</span> <span class="n">INTEGER</span>
<span class="n">OPTIONAL</span>     <span class="o">--</span> <span
class="k">if</span> <span class="n">supported</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>You don't need to know anything about this message, what is important is how we
will decode it.</p>
+<p>The first thing we need to create is an interface and a implementation for the Java
object that will represent the <strong>EntryChange</strong> object.</p>
+<p>Here is the interface (note that it's a <em>Control</em>, but it's a
irrelevant information here) :</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span
class="kd">interface</span> <span class="nc">EntryChange</span> <span
class="kd">extends</span> <span class="n">Control</span>
+<span class="o">{</span>
+    <span class="cm">/** No defined change number */</span> 
+    <span class="kt">int</span> <span class="n">UNDEFINED_CHANGE_NUMBER</span>
<span class="o">=</span> <span class="o">-</span><span class="mi">1</span><span
class="o">;</span>
+
+    <span class="cm">/** The EntryChange control */</span>
+    <span class="n">String</span> <span class="n">OID</span> <span
class="o">=</span> <span class="s">&quot;2.16.840.1.113730.3.4.7&quot;</span><span
class="o">;</span>
+
+
+    <span class="cm">/**</span>
+<span class="cm">     * @return The ChangeType</span>
+<span class="cm">     */</span>
+    <span class="n">ChangeType</span> <span class="nf">getChangeType</span><span
class="o">();</span>
+
+
+    <span class="cm">/**</span>
+<span class="cm">     * Set the ChangeType</span>
+<span class="cm">     *</span>
+<span class="cm">     * @param changeType Add, Delete; Modify or ModifyDN</span>
+<span class="cm">     */</span>
+    <span class="kt">void</span> <span class="nf">setChangeType</span><span
class="o">(</span> <span class="n">ChangeType</span> <span class="n">changeType</span>
<span class="o">);</span>
+
+
+    <span class="cm">/**</span>
+<span class="cm">     * @return The previous DN</span>
+<span class="cm">     */</span>
+    <span class="n">Dn</span> <span class="nf">getPreviousDn</span><span
class="o">();</span>
+
+
+    <span class="cm">/**</span>
+<span class="cm">     * Sets the previous DN</span>
+<span class="cm">     * </span>
+<span class="cm">     * @param previousDn The previous DN</span>
+<span class="cm">     */</span>
+    <span class="kt">void</span> <span class="nf">setPreviousDn</span><span
class="o">(</span> <span class="n">Dn</span> <span class="n">previousDn</span>
<span class="o">);</span>
+
+
+    <span class="cm">/**</span>
+<span class="cm">     * @return The change number</span>
+<span class="cm">     */</span>
+    <span class="kt">long</span> <span class="nf">getChangeNumber</span><span
class="o">();</span>
+
+
+    <span class="cm">/**</span>
+<span class="cm">     * Sets the ChangeNumber</span>
+<span class="cm">     * </span>
+<span class="cm">     * @param changeNumber The ChanegNumber</span>
+<span class="cm">     */</span>
+    <span class="kt">void</span> <span class="nf">setChangeNumber</span><span
class="o">(</span> <span class="kt">long</span> <span class="n">changeNumber</span>
<span class="o">);</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>What is important is that we declare all the setters and getters for the object
fields that matter : <em>changeType</em>, <em>previousDN</em> and
<em>changeNumber</em></p>
+<p>The implementation is not really complex :</p>
+<div class="codehilite"><pre><span class="cm">/**</span>
+<span class="cm"> * A simple implementation of the EntryChange response control.</span>
+<span class="cm"> *</span>
+<span class="cm"> * @author &lt;a href=&quot;mailto:dev@directory.apache.org&quot;&gt;Apache
Directory Project&lt;/a&gt;</span>
+<span class="cm"> */</span>
+<span class="kd">public</span> <span class="kd">class</span> <span
class="nc">EntryChangeImpl</span> <span class="kd">extends</span> <span
class="n">AbstractControl</span> <span class="kd">implements</span> <span
class="n">EntryChange</span>
+<span class="o">{</span>
+    <span class="cm">/** The changeType */</span>
+    <span class="kd">private</span> <span class="n">ChangeType</span>
<span class="n">changeType</span> <span class="o">=</span> <span
class="n">ChangeType</span><span class="o">.</span><span class="na">ADD</span><span
class="o">;</span>
+
+    <span class="kd">private</span> <span class="kt">long</span>
<span class="n">changeNumber</span> <span class="o">=</span> <span
class="n">UNDEFINED_CHANGE_NUMBER</span><span class="o">;</span>
+
+    <span class="cm">/** The previous Dn */</span>
+    <span class="kd">private</span> <span class="n">Dn</span> <span
class="n">previousDn</span> <span class="o">=</span> <span class="kc">null</span><span
class="o">;</span>
+
+
+    <span class="cm">/**</span>
+<span class="cm">     *</span>
+<span class="cm">     * Creates a new instance of EntryChangeControl.</span>
+<span class="cm">     *</span>
+<span class="cm">     */</span>
+    <span class="kd">public</span> <span class="nf">EntryChangeImpl</span><span
class="o">()</span>
+    <span class="o">{</span>
+        <span class="kd">super</span><span class="o">(</span> <span
class="n">OID</span> <span class="o">);</span>
+    <span class="o">}</span>
+
+
+    <span class="cm">/**</span>
+<span class="cm">     * {@inheritDoc}</span>
+<span class="cm">     */</span>
+    <span class="nd">@Override</span>
+    <span class="kd">public</span> <span class="n">ChangeType</span>
<span class="nf">getChangeType</span><span class="o">()</span>
+    <span class="o">{</span>
+        <span class="k">return</span> <span class="n">changeType</span><span
class="o">;</span>
+    <span class="o">}</span>
+
+
+    <span class="cm">/**</span>
+<span class="cm">     * {@inheritDoc}</span>
+<span class="cm">     */</span>
+    <span class="nd">@Override</span>
+    <span class="kd">public</span> <span class="kt">void</span> <span
class="nf">setChangeType</span><span class="o">(</span> <span class="n">ChangeType</span>
<span class="n">changeType</span> <span class="o">)</span>
+    <span class="o">{</span>
+        <span class="k">this</span><span class="o">.</span><span
class="na">changeType</span> <span class="o">=</span> <span class="n">changeType</span><span
class="o">;</span>
+    <span class="o">}</span>
+
+
+    <span class="cm">/**</span>
+<span class="cm">     * {@inheritDoc}</span>
+<span class="cm">     */</span>
+    <span class="nd">@Override</span>
+    <span class="kd">public</span> <span class="n">Dn</span> <span
class="nf">getPreviousDn</span><span class="o">()</span>
+    <span class="o">{</span>
+        <span class="k">return</span> <span class="n">previousDn</span><span
class="o">;</span>
+    <span class="o">}</span>
+
+
+    <span class="cm">/**</span>
+<span class="cm">     * {@inheritDoc}</span>
+<span class="cm">     */</span>
+    <span class="nd">@Override</span>
+    <span class="kd">public</span> <span class="kt">void</span> <span
class="nf">setPreviousDn</span><span class="o">(</span> <span class="n">Dn</span>
<span class="n">previousDn</span> <span class="o">)</span>
+    <span class="o">{</span>
+        <span class="k">this</span><span class="o">.</span><span
class="na">previousDn</span> <span class="o">=</span> <span class="n">previousDn</span><span
class="o">;</span>
+    <span class="o">}</span>
+
+
+    <span class="cm">/**</span>
+<span class="cm">     * {@inheritDoc}</span>
+<span class="cm">     */</span>
+    <span class="nd">@Override</span>
+    <span class="kd">public</span> <span class="kt">long</span> <span
class="nf">getChangeNumber</span><span class="o">()</span>
+    <span class="o">{</span>
+        <span class="k">return</span> <span class="n">changeNumber</span><span
class="o">;</span>
+    <span class="o">}</span>
+
+
+    <span class="cm">/**</span>
+<span class="cm">     * {@inheritDoc}</span>
+<span class="cm">     */</span>
+    <span class="nd">@Override</span>
+    <span class="kd">public</span> <span class="kt">void</span> <span
class="nf">setChangeNumber</span><span class="o">(</span> <span class="kt">long</span>
<span class="n">changeNumber</span> <span class="o">)</span>
+    <span class="o">{</span>
+        <span class="k">this</span><span class="o">.</span><span
class="na">changeNumber</span> <span class="o">=</span> <span class="n">changeNumber</span><span
class="o">;</span>
+    <span class="o">}</span>
+
+
+    <span class="cm">/**</span>
+<span class="cm">     * @see Object#hashCode()</span>
+<span class="cm">     */</span>
+    <span class="nd">@Override</span>
+    <span class="kd">public</span> <span class="kt">int</span> <span
class="nf">hashCode</span><span class="o">()</span>
+    <span class="o">{</span>
+        <span class="kt">int</span> <span class="n">h</span> <span
class="o">=</span> <span class="kd">super</span><span class="o">.</span><span
class="na">hashCode</span><span class="o">();</span>
+
+        <span class="n">h</span> <span class="o">=</span> <span
class="n">h</span> <span class="o">*</span> <span class="mi">37</span>
<span class="o">+</span> <span class="o">(</span> <span class="kt">int</span>
<span class="o">)</span> <span class="n">changeNumber</span><span
class="o">;</span>
+        <span class="n">h</span> <span class="o">=</span> <span
class="n">h</span> <span class="o">*</span> <span class="mi">37</span>
<span class="o">+</span> <span class="o">(</span> <span class="n">changeType</span>
<span class="o">==</span> <span class="kc">null</span> <span class="o">?</span>
<span class="mi">0</span> <span class="o">:</span> <span class="n">changeType</span><span
class="o">.</span><span class="na">hashCode</span><span class="o">()</span>
<span class="o">);</span>
+        <span class="n">h</span> <span class="o">=</span> <span
class="n">h</span> <span class="o">*</span> <span class="mi">37</span>
<span class="o">+</span> <span class="o">(</span> <span class="n">previousDn</span>
<span class="o">==</span> <span class="kc">null</span> <span class="o">?</span>
<span class="mi">0</span> <span class="o">:</span> <span class="n">previousDn</span><span
class="o">.</span><span class="na">hashCode</span><span class="o">()</span>
<span class="o">);</span>
+
+        <span class="k">return</span> <span class="n">h</span><span
class="o">;</span>
+    <span class="o">}</span>
+
+
+    <span class="cm">/**</span>
+<span class="cm">     * {@inheritDoc}</span>
+<span class="cm">     */</span>
+    <span class="nd">@Override</span>
+    <span class="kd">public</span> <span class="kt">boolean</span>
<span class="nf">equals</span><span class="o">(</span> <span class="n">Object</span>
<span class="n">o</span> <span class="o">)</span>
+    <span class="o">{</span>
+        <span class="k">if</span> <span class="o">(</span> <span
class="o">!</span><span class="kd">super</span><span class="o">.</span><span
class="na">equals</span><span class="o">(</span> <span class="n">o</span>
<span class="o">)</span> <span class="o">)</span>
+        <span class="o">{</span>
+            <span class="k">return</span> <span class="kc">false</span><span
class="o">;</span>
+        <span class="o">}</span>
+
+        <span class="n">EntryChange</span> <span class="n">otherControl</span>
<span class="o">=</span> <span class="o">(</span> <span class="n">EntryChange</span>
<span class="o">)</span> <span class="n">o</span><span class="o">;</span>
+
+        <span class="k">return</span> <span class="o">(</span> <span
class="n">changeNumber</span> <span class="o">==</span> <span class="n">otherControl</span><span
class="o">.</span><span class="na">getChangeNumber</span><span class="o">()</span>
<span class="o">)</span> <span class="o">&amp;&amp;</span>
<span class="o">(</span> <span class="n">changeType</span> <span
class="o">==</span> <span class="n">otherControl</span><span class="o">.</span><span
class="na">getChangeType</span><span class="o">()</span> <span class="o">)</span>
+            <span class="o">&amp;&amp;</span> <span class="o">(</span>
<span class="n">previousDn</span><span class="o">.</span><span
class="na">equals</span><span class="o">(</span> <span class="n">otherControl</span><span
class="o">.</span><span class="na">getPreviousDn</span><span class="o">()</span>
<span class="o">)</span> <span class="o">);</span>
+    <span class="o">}</span>
+
+
+    <span class="cm">/**</span>
+<span class="cm">     * Return a String representing this EntryChangeControl.</span>
+<span class="cm">     */</span>
+    <span class="nd">@Override</span>
+    <span class="kd">public</span> <span class="n">String</span>
<span class="nf">toString</span><span class="o">()</span>
+    <span class="o">{</span>
+        <span class="n">StringBuilder</span> <span class="n">sb</span>
<span class="o">=</span> <span class="k">new</span> <span class="n">StringBuilder</span><span
class="o">();</span>
+
+        <span class="n">sb</span><span class="o">.</span><span
class="na">append</span><span class="o">(</span> <span class="s">&quot;
   Entry Change Control\n&quot;</span> <span class="o">);</span>
+        <span class="n">sb</span><span class="o">.</span><span
class="na">append</span><span class="o">(</span> <span class="s">&quot;
       oid : &quot;</span> <span class="o">).</span><span class="na">append</span><span
class="o">(</span> <span class="n">getOid</span><span class="o">()</span>
<span class="o">).</span><span class="na">append</span><span class="o">(</span>
<span class="sc">&#39;\n&#39;</span> <span class="o">);</span>
+        <span class="n">sb</span><span class="o">.</span><span
class="na">append</span><span class="o">(</span> <span class="s">&quot;
       critical : &quot;</span> <span class="o">).</span><span class="na">append</span><span
class="o">(</span> <span class="n">isCritical</span><span class="o">()</span>
<span class="o">).</span><span class="na">append</span><span class="o">(</span>
<span class="sc">&#39;\n&#39;</span> <span class="o">);</span>
+        <span class="n">sb</span><span class="o">.</span><span
class="na">append</span><span class="o">(</span> <span class="s">&quot;
       changeType   : &#39;&quot;</span> <span class="o">).</span><span
class="na">append</span><span class="o">(</span> <span class="n">changeType</span>
<span class="o">).</span><span class="na">append</span><span class="o">(</span>
<span class="s">&quot;&#39;\n&quot;</span> <span class="o">);</span>
+        <span class="n">sb</span><span class="o">.</span><span
class="na">append</span><span class="o">(</span> <span class="s">&quot;
       previousDN   : &#39;&quot;</span> <span class="o">).</span><span
class="na">append</span><span class="o">(</span> <span class="n">previousDn</span>
<span class="o">).</span><span class="na">append</span><span class="o">(</span>
<span class="s">&quot;&#39;\n&quot;</span> <span class="o">);</span>
+
+        <span class="k">if</span> <span class="o">(</span> <span
class="n">changeNumber</span> <span class="o">==</span> <span class="n">UNDEFINED_CHANGE_NUMBER</span>
<span class="o">)</span>
+        <span class="o">{</span>
+            <span class="n">sb</span><span class="o">.</span><span
class="na">append</span><span class="o">(</span> <span class="s">&quot;
       changeNumber : &#39;&quot;</span> <span class="o">).</span><span
class="na">append</span><span class="o">(</span> <span class="s">&quot;UNDEFINED&quot;</span>
<span class="o">).</span><span class="na">append</span><span class="o">(</span>
<span class="s">&quot;&#39;\n&quot;</span> <span class="o">);</span>
+        <span class="o">}</span>
+        <span class="k">else</span>
+        <span class="o">{</span>
+            <span class="n">sb</span><span class="o">.</span><span
class="na">append</span><span class="o">(</span> <span class="s">&quot;
       changeNumber : &#39;&quot;</span> <span class="o">).</span><span
class="na">append</span><span class="o">(</span> <span class="n">changeNumber</span>
<span class="o">).</span><span class="na">append</span><span class="o">(</span>
<span class="s">&quot;&#39;\n&quot;</span> <span class="o">);</span>
+        <span class="o">}</span>
+
+        <span class="k">return</span> <span class="n">sb</span><span
class="o">.</span><span class="na">toString</span><span class="o">();</span>
+    <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>This is pretty much trivial.</p>
 
 
     <div class="nav">



Mime
View raw message