You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by bu...@apache.org on 2018/01/13 13:08:16 UTC
svn commit: r1023791 - in /websites/staging/directory/trunk/content: ./
api/dev-guide/4.1-asn1-tlv.html
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">¶</a></h1>
+<h1 id="41-asn1-tlv">4.1 - ASN/1 TLV<a class="headerlink" href="#41-asn1-tlv" title="Permanent link">¶</a></h1>
<h2 id="what-are-tlvs">What are TLVs ?<a class="headerlink" href="#what-are-tlvs" title="Permanent link">¶</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">¶</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">¶</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">¶</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">¶</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">¶</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">"2.16.840.1.113730.3.4.7"</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 <a href="mailto:dev@directory.apache.org">Apache Directory Project</a></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">&&</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">&&</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">" Entry Change Control\n"</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">" oid : "</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">'\n'</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">" critical : "</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">'\n'</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">" changeType : '"</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">"'\n"</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">" previousDN : '"</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">"'\n"</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">" changeNumber : '"</span> <span class="o">).</span><span class="na">append</span><span class="o">(</span> <span class="s">"UNDEFINED"</span> <span class="o">).</span><span class="na">append</span><span class="o">(</span> <span class="s">"'\n"</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">" changeNumber : '"</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">"'\n"</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">