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/12 13:58:47 UTC
svn commit: r1023741 - in /websites/staging/directory/trunk/content: ./
api/dev-guide/ api/dev-guide/images/
Author: buildbot
Date: Fri Jan 12 13:58:47 2018
New Revision: 1023741
Log:
Staging update by buildbot for directory
Added:
websites/staging/directory/trunk/content/api/dev-guide/3-building.mdtext.html
websites/staging/directory/trunk/content/api/dev-guide/4-asn1.html
websites/staging/directory/trunk/content/api/dev-guide/images/asn1-codec.graphml (with props)
websites/staging/directory/trunk/content/api/dev-guide/images/asn1-codec.png (with props)
websites/staging/directory/trunk/content/api/dev-guide/images/sm-transition.graphml (with props)
websites/staging/directory/trunk/content/api/dev-guide/images/sm-transition.png (with props)
Modified:
websites/staging/directory/trunk/content/ (props changed)
websites/staging/directory/trunk/content/api/dev-guide/1-introduction.html
websites/staging/directory/trunk/content/api/dev-guide/2-general-structure.html
Propchange: websites/staging/directory/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Fri Jan 12 13:58:47 2018
@@ -1 +1 @@
-1820958
+1820987
Modified: websites/staging/directory/trunk/content/api/dev-guide/1-introduction.html
==============================================================================
--- websites/staging/directory/trunk/content/api/dev-guide/1-introduction.html (original)
+++ websites/staging/directory/trunk/content/api/dev-guide/1-introduction.html Fri Jan 12 13:58:47 2018
@@ -184,7 +184,7 @@
}
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="1-introduction">1 - Introduction<a class="headerlink" href="#1-introduction" title="Permanent link">¶</a></h1>
-<p>This Developer Guide teaches developers about the inner logic of the API. It can be useful to those interested in the project, giving them some clues about how it all works and its design, and also to those who want to extend the *<em>LDAP API</em> by adding <em>Controls</em>, <em>Extended Operations</em>, or schema elements like <em>SyntaxCheckers</em>, <em>Comparators</em>, etc.</p>
+<p>This Developer Guide teaches developers about the inner logic of the <strong>LDAP API</strong>. It can be useful to those interested in the project, giving them some clues about how it all works and its design, and also to those who want to extend the <strong>LDAP API</strong> by adding <em>Controls</em>, <em>Extended Operations</em>, or schema elements like <em>SyntaxCheckers</em>, <em>Comparators</em>, etc.</p>
<h2 id="content">Content<a class="headerlink" href="#content" title="Permanent link">¶</a></h2>
<ul>
<li><a href="2-general-structure.html">2 - General structure</a></li>
Modified: websites/staging/directory/trunk/content/api/dev-guide/2-general-structure.html
==============================================================================
--- websites/staging/directory/trunk/content/api/dev-guide/2-general-structure.html (original)
+++ websites/staging/directory/trunk/content/api/dev-guide/2-general-structure.html Fri Jan 12 13:58:47 2018
@@ -255,7 +255,7 @@ LDAP API root
<ul>
<li>
-<p>The <em>all</em> module is just a packaging module, gathering all the other modules in one single jar to simplify the work o those who want to use the API. One can import each module speparately, or the <em>all</em> module only. Note that it does not include the tests and integration modules (<strong>integ</strong>, <strong>integ-osgi</strong> and <strong>distribution</strong>)</p>
+<p>The <strong>all</strong> module is just a packaging module, gathering all the other modules in one single jar to simplify the work for those who want to use the API. One can import each module speparately, or the <strong>all</strong> module only. Note that it does not include the tests and integration modules (<strong>integ</strong>, <strong>integ-osgi</strong> and <strong>distribution</strong>)</p>
</li>
<li>
<p>The <strong>asn1</strong> module contains the code needed to handle <em>ASN/1</em> encoding/decoding.</p>
Added: websites/staging/directory/trunk/content/api/dev-guide/3-building.mdtext.html
==============================================================================
--- websites/staging/directory/trunk/content/api/dev-guide/3-building.mdtext.html (added)
+++ websites/staging/directory/trunk/content/api/dev-guide/3-building.mdtext.html Fri Jan 12 13:58:47 2018
@@ -0,0 +1,246 @@
+<!DOCTYPE html>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<html>
+ <head>
+ <title>3 - Building — Apache Directory</title>
+
+ <link href="./../../css/common.css" rel="stylesheet" type="text/css">
+ <link href="./../../css/brown.css" rel="stylesheet" type="text/css">
+
+
+ <link rel="shortcut icon" href="./../../images/api-icon_16x16.png">
+
+ <!-- Google Analytics -->
+ <script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
+ <script type="text/javascript">
+ _uacct = "UA-1358462-1";
+ urchinTracker();
+ </script>
+ </head>
+ <body>
+ <div id="container">
+ <div id="header">
+ <div id="subProjectsNavBar">
+ <a href="./../../">
+
+ Main
+
+ </a>
+ |
+ <a href="./../../apacheds">
+
+ ApacheDS
+
+ </a>
+ |
+ <a href="./../../studio">
+
+ Studio
+
+ </a>
+ |
+ <a href="./../../api">
+
+ <STRONG>LDAP API</STRONG>
+
+ </a>
+ |
+ <a href="./../../mavibot">
+
+ Mavibot
+
+ </a>
+ |
+ <a href="./../../escimo">
+
+ eSCIMo
+
+ </a>
+ |
+ <a href="./../../fortress">
+
+ Fortress
+
+ </a>
+ |
+ <a href="./../../kerby">
+
+ Kerby
+
+ </a>
+ </div><!-- subProjectsNavBar -->
+ </div><!-- header -->
+ <div id="content">
+ <div id="leftColumn">
+
+<div id="navigation">
+
+ <!--ul>
+ <li>
+ <a href="http://bit.ly/1n9YlQT" target="_blank">
+ <img src="./../../images/ApacheConBudapest.png" width="125" height="125" alt="I'm Speaking at ApacheCon Europe 2014! Join me!" title="I'm Speaking at ApacheCon Europe 2014! Join me!" border="0" style="margin-bottom:-3px;"/>
+ </a>
+ </li>
+ </ul-->
+ <h5>LDAP API 1.0</h5>
+ <ul>
+ <li><a href="./../../api/">Home</a></li>
+ <li><a href="./../../api/news.html">News</a></li>
+ </ul>
+ <h5>Downloads</h5>
+ <ul>
+ <li><a href="./../../api/downloads.html">Version 1.0.0</a> <IMG src="./../../images/new_badge.gif" alt="" style="margin-bottom:-3px;" border="0"></li>
+ <li><a href="./../../api/download-old-versions.html">Older versions</a></li>
+ </ul>
+ <h5>Getting Started</h5>
+ <ul>
+ <li><a href="./../../api/vision.html">Vision</a></li>
+ <li><a href="./../../api/java-api.html">Java API</a></li>
+ </ul>
+ <h5>Documentation</h5>
+ <ul>
+ <li><a href="./../../api/five-minutes-tutorial.html">Five minutes tutorial</a></li>
+ <li><a href="./../../api/user-guide.html">User Guide</a></li>
+ <li><a href="./../../api/gen-docs/latest/apidocs/">JavaDocs</a></li>
+ <li><a href="./../../api/gen-docs/latest/xref/">Cross-Reference</a></li>
+ <!--li><a href="./../../api/gen-docs/latest/">Generated Reports</a></li-->
+ <li><a href="./../../api/developer-guide.html">Developer Guide</a></li>
+ </ul>
+
+
+ <h5>Support</h5>
+ <ul>
+ <li><a href="./../../mailing-lists-and-irc.html">Mailing Lists & IRC</a></li>
+ <li><a href="./../../sources.html">Sources</a></li>
+ <li><a href="./../../issue-tracking.html">Issue Tracking</a></li>
+ <li><a href="./../../commercial-support.html">Commercial Support</a></li>
+ </ul>
+ <h5>Community</h5>
+ <ul>
+ <li><a href="./../../contribute.html">How to Contribute</a></li>
+ <li><a href="./../../team.html">Team</a></li>
+ <li><a href="./../../original-project-proposal.html">Original Project Proposal</a></li>
+ <li><a href="./../../special-thanks.html" class="external-link" rel="nofollow">Special Thanks</a></li>
+ </ul>
+ <h5>About Apache</h5>
+ <ul>
+ <li><a href="http://www.apache.org/">Apache</a></li>
+ <li><a href="http://www.apache.org/licenses/">License</a></li>
+ <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
+ <li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+ <li><a href="http://www.apache.org/security/">Security</a></li>
+ </ul>
+
+</div><!-- navigation -->
+
+ </div><!-- leftColumn -->
+ <div id="rightColumn">
+
+
+ <div class="nav">
+ <div class="nav_prev">
+
+ <a href="2-general-structure.html">2 - General Structure</a>
+
+ </div>
+ <div class="nav_up">
+
+ <a href="../dev-guide.html">Developer Guide</a>
+
+ </div>
+ <div class="nav_next">
+
+ <a href="4-asn1.html">4 - ASN/1</a>
+
+ </div>
+ <div class="clearfix"></div>
+ </div>
+
+
+<style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ 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="3-building">3 - Building<a class="headerlink" href="#3-building" title="Permanent link">¶</a></h1>
+<p>The project is based on <strong>Apache Maven</strong> (version 3.x), so you'll have to install it first.</p>
+<p>That being said, building the <strong>LDAP API</strong> is pretty straightforward :</p>
+<div class="codehilite"><pre>$ <span class="n">mvn</span> <span class="n">clean</span> <span class="n">install</span>
+<span class="n">Java</span> <span class="n">HotSpot</span><span class="p">(</span><span class="n">TM</span><span class="p">)</span> 64<span class="o">-</span><span class="n">Bit</span> <span class="n">Server</span> <span class="n">VM</span> <span class="n">warning</span><span class="p">:</span> <span class="n">ignoring</span> <span class="n">option</span> <span class="n">MaxPermSize</span><span class="p">=</span>256<span class="n">M</span><span class="p">;</span> <span class="n">support</span> <span class="n">was</span> <span class="n">removed</span> <span class="n">in</span> 8<span class="p">.</span>0
+<span class="p">[</span><span class="n">INFO</span><span class="p">]</span> <span class="n">Scanning</span> <span class="k">for</span> <span class="n">projects</span><span class="p">...</span>
+<span class="p">[</span><span class="n">INFO</span><span class="p">]</span> <span class="o">------------------------------------------------------------------------</span>
+<span class="p">[</span><span class="n">INFO</span><span class="p">]</span> <span class="n">Reactor</span> <span class="n">Build</span> <span class="n">Order</span><span class="p">:</span>
+<span class="p">[</span><span class="n">INFO</span><span class="p">]</span>
+<span class="p">[</span><span class="n">INFO</span><span class="p">]</span> <span class="n">Apache</span> <span class="n">Directory</span> <span class="n">LDAP</span> <span class="n">API</span>
+<span class="p">[</span><span class="n">INFO</span><span class="p">]</span> <span class="n">Apache</span> <span class="n">Directory</span> <span class="n">LDAP</span> <span class="n">API</span> <span class="n">I18n</span>
+<span class="p">[</span><span class="n">INFO</span><span class="p">]</span> <span class="n">Apache</span> <span class="n">Directory</span> <span class="n">LDAP</span> <span class="n">API</span> <span class="n">Utilities</span>
+<span class="p">...</span>
+<span class="p">[</span><span class="n">INFO</span><span class="p">]</span> <span class="n">Apache</span> <span class="n">Directory</span> <span class="n">LDAP</span> <span class="n">API</span> <span class="n">Model</span>
+<span class="p">[</span><span class="n">INFO</span><span class="p">]</span> <span class="n">Apache</span> <span class="n">Directory</span> <span class="n">LDAP</span> <span class="n">API</span> <span class="n">Codec</span> <span class="n">Parent</span>
+<span class="p">[</span><span class="n">INFO</span><span class="p">]</span> <span class="n">Apache</span> <span class="n">Directory</span> <span class="n">API</span> <span class="n">Integration</span> <span class="n">Tests</span>
+<span class="p">[</span><span class="n">INFO</span><span class="p">]</span> <span class="n">Apache</span> <span class="n">Directory</span> <span class="n">API</span> <span class="n">OSGi</span> <span class="n">Integration</span> <span class="n">Tests</span>
+<span class="p">[</span><span class="n">INFO</span><span class="p">]</span> <span class="n">Apache</span> <span class="n">Directory</span> <span class="n">LDAP</span> <span class="n">API</span> <span class="n">Distribution</span>
+<span class="p">[</span><span class="n">INFO</span><span class="p">]</span>
+<span class="p">[</span><span class="n">INFO</span><span class="p">]</span> <span class="o">------------------------------------------------------------------------</span>
+<span class="p">[</span><span class="n">INFO</span><span class="p">]</span> <span class="n">Building</span> <span class="n">Apache</span> <span class="n">Directory</span> <span class="n">LDAP</span> <span class="n">API</span> 2<span class="p">.</span>0<span class="p">.</span>0<span class="p">.</span><span class="n">AM1</span><span class="o">-</span><span class="n">SNAPSHOT</span>
+<span class="p">[</span><span class="n">INFO</span><span class="p">]</span> <span class="o">------------------------------------------------------------------------</span>
+<span class="p">...</span>
+</pre></div>
+
+
+<p>It takes around 1 min to build it all (a bit longer the first time, as some dependencies wil have to be pulled from the net).</p>
+<p>The top level <em>pom.xml</em> depends on teh special <em>project</em> 'project', which is used by all the <strong>ApacheDS</strong> projects. It gathers information about maven plugin dependenies and someother things. You don't really need to touch it anyway...</p>
+<p>Remember to use <strong>Java 8</strong> !!</p>
+
+
+ <div class="nav">
+ <div class="nav_prev">
+
+ <a href="2-general-structure.html">2 - General Structure</a>
+
+ </div>
+ <div class="nav_up">
+
+ <a href="../dev-guide.html">Developer Guide</a>
+
+ </div>
+ <div class="nav_next">
+
+ <a href="4-asn1.html">4 - ASN/1</a>
+
+ </div>
+ <div class="clearfix"></div>
+ </div>
+
+
+ </div><!-- rightColumn -->
+ <div id="endContent"></div>
+ </div><!-- content -->
+ <div id="footer">© 2003-2015, <a href="http://www.apache.org">The Apache Software Foundation</a> - <a href="./../../privacy-policy.html">Privacy Policy</a><br />
+ Apache Directory, ApacheDS, Apache Directory Server, Apache Directory Studio, Apache LDAP API, Apache Triplesec, Triplesec, Apache Mavibot, Mavibot, Apache eSCIMo, eSCIMo, Fortress, Apache Fortress, EnMasse, Apache EnMasse, Apache Kerby, Kerby
+ Apache, the Apache feather logo, and the Apache Directory project logos are trademarks of The Apache Software Foundation.
+ </div>
+ </div><!-- container -->
+ </body>
+</html>
\ No newline at end of file
Added: websites/staging/directory/trunk/content/api/dev-guide/4-asn1.html
==============================================================================
--- websites/staging/directory/trunk/content/api/dev-guide/4-asn1.html (added)
+++ websites/staging/directory/trunk/content/api/dev-guide/4-asn1.html Fri Jan 12 13:58:47 2018
@@ -0,0 +1,271 @@
+<!DOCTYPE html>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<html>
+ <head>
+ <title>4 - ASN/1 — Apache Directory</title>
+
+ <link href="./../../css/common.css" rel="stylesheet" type="text/css">
+ <link href="./../../css/brown.css" rel="stylesheet" type="text/css">
+
+
+ <link rel="shortcut icon" href="./../../images/api-icon_16x16.png">
+
+ <!-- Google Analytics -->
+ <script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
+ <script type="text/javascript">
+ _uacct = "UA-1358462-1";
+ urchinTracker();
+ </script>
+ </head>
+ <body>
+ <div id="container">
+ <div id="header">
+ <div id="subProjectsNavBar">
+ <a href="./../../">
+
+ Main
+
+ </a>
+ |
+ <a href="./../../apacheds">
+
+ ApacheDS
+
+ </a>
+ |
+ <a href="./../../studio">
+
+ Studio
+
+ </a>
+ |
+ <a href="./../../api">
+
+ <STRONG>LDAP API</STRONG>
+
+ </a>
+ |
+ <a href="./../../mavibot">
+
+ Mavibot
+
+ </a>
+ |
+ <a href="./../../escimo">
+
+ eSCIMo
+
+ </a>
+ |
+ <a href="./../../fortress">
+
+ Fortress
+
+ </a>
+ |
+ <a href="./../../kerby">
+
+ Kerby
+
+ </a>
+ </div><!-- subProjectsNavBar -->
+ </div><!-- header -->
+ <div id="content">
+ <div id="leftColumn">
+
+<div id="navigation">
+
+ <!--ul>
+ <li>
+ <a href="http://bit.ly/1n9YlQT" target="_blank">
+ <img src="./../../images/ApacheConBudapest.png" width="125" height="125" alt="I'm Speaking at ApacheCon Europe 2014! Join me!" title="I'm Speaking at ApacheCon Europe 2014! Join me!" border="0" style="margin-bottom:-3px;"/>
+ </a>
+ </li>
+ </ul-->
+ <h5>LDAP API 1.0</h5>
+ <ul>
+ <li><a href="./../../api/">Home</a></li>
+ <li><a href="./../../api/news.html">News</a></li>
+ </ul>
+ <h5>Downloads</h5>
+ <ul>
+ <li><a href="./../../api/downloads.html">Version 1.0.0</a> <IMG src="./../../images/new_badge.gif" alt="" style="margin-bottom:-3px;" border="0"></li>
+ <li><a href="./../../api/download-old-versions.html">Older versions</a></li>
+ </ul>
+ <h5>Getting Started</h5>
+ <ul>
+ <li><a href="./../../api/vision.html">Vision</a></li>
+ <li><a href="./../../api/java-api.html">Java API</a></li>
+ </ul>
+ <h5>Documentation</h5>
+ <ul>
+ <li><a href="./../../api/five-minutes-tutorial.html">Five minutes tutorial</a></li>
+ <li><a href="./../../api/user-guide.html">User Guide</a></li>
+ <li><a href="./../../api/gen-docs/latest/apidocs/">JavaDocs</a></li>
+ <li><a href="./../../api/gen-docs/latest/xref/">Cross-Reference</a></li>
+ <!--li><a href="./../../api/gen-docs/latest/">Generated Reports</a></li-->
+ <li><a href="./../../api/developer-guide.html">Developer Guide</a></li>
+ </ul>
+
+
+ <h5>Support</h5>
+ <ul>
+ <li><a href="./../../mailing-lists-and-irc.html">Mailing Lists & IRC</a></li>
+ <li><a href="./../../sources.html">Sources</a></li>
+ <li><a href="./../../issue-tracking.html">Issue Tracking</a></li>
+ <li><a href="./../../commercial-support.html">Commercial Support</a></li>
+ </ul>
+ <h5>Community</h5>
+ <ul>
+ <li><a href="./../../contribute.html">How to Contribute</a></li>
+ <li><a href="./../../team.html">Team</a></li>
+ <li><a href="./../../original-project-proposal.html">Original Project Proposal</a></li>
+ <li><a href="./../../special-thanks.html" class="external-link" rel="nofollow">Special Thanks</a></li>
+ </ul>
+ <h5>About Apache</h5>
+ <ul>
+ <li><a href="http://www.apache.org/">Apache</a></li>
+ <li><a href="http://www.apache.org/licenses/">License</a></li>
+ <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
+ <li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+ <li><a href="http://www.apache.org/security/">Security</a></li>
+ </ul>
+
+</div><!-- navigation -->
+
+ </div><!-- leftColumn -->
+ <div id="rightColumn">
+
+
+ <div class="nav">
+ <div class="nav_prev">
+
+ <a href="3-building.html">3 - Building</a>
+
+ </div>
+ <div class="nav_up">
+
+ <a href="../dev-guide.html">Developer Guide</a>
+
+ </div>
+ <div class="nav_next">
+
+ <a href="5-network.html">5 - Network</a>
+
+ </div>
+ <div class="clearfix"></div>
+ </div>
+
+
+<style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ 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">4 - ASN/1<a class="headerlink" href="#4-asn1" title="Permanent link">¶</a></h1>
+<p>To be completed...</p>
+<p>The <strong>LDAP</strong> protocol is based on an <strong>ASN/1</strong> description. We will notexplain in detail what is <strong>ASN/1</strong> about, you would rather check <a href="https://en.wikipedia.org/wiki/Abstract_Syntax_Notation_One">This page</a> for a very limited introduction, or if you feel teh need to understand what is <strong>ASN/1</strong> in detail, just read the <a href="http://www.oss.com/asn1/resources/books-whitepapers-pubs/dubuisson-asn1-book.PDF">Olivier Dubuisson's book on ASN.1</a> (This is probably the best reference !)</p>
+<p>Anyway, we use a subset of <strong>ASN/1</strong>, as what we have to deal with is the <strong>BER/DER</strong> encoding. (<strong>BER</strong> or <strong>DER</strong> stands for <strong>B</strong>asic <strong>E</strong>ncoding <strong>R</strong>ule and <strong>D</strong>istinguished <strong>E</strong>ncoding <strong>R</strong>ule. There are other possible encoding, like <strong>PER</strong>, <strong>XER</strong>, <strong>CER</strong>, but they are irrelevant for <strong>LDAP</strong>)</p>
+<p>What is needed to know is that <strong>ASN/1</strong> is just a notation used to describe the messages being exchanged between a client and a server, and in order to use it, we need an encoder and a decoder on both sides :</p>
+<p><img alt="Client/Server communication" src="images/asn1-codec.png" /></p>
+<h2 id="asn1-implementation-in-apache-ldap-api">ASN/1 implementation in Apache LDAP API<a class="headerlink" href="#asn1-implementation-in-apache-ldap-api" title="Permanent link">¶</a></h2>
+<p>It took a long time to get it right ! And it's not perfect :-)</p>
+<p>The very first iteration was using a proprietary library (<strong>IBM SNACC</strong>), but that was before <strong>ApacheDS</strong> became a <strong>TLP</strong> ! The next iteration was based on a rewriting system, which was pretty slow. Then came <strong>Snicker</strong>, a <em>State Machine</em> based decoder, which is currently what we use. We might change for a faster implementation, like what <strong>Kerby</strong> is using...</p>
+<h3 id="asn1-messages">ASN/1 messages<a class="headerlink" href="#asn1-messages" title="Permanent link">¶</a></h3>
+<p>Let's start with the basic information.</p>
+<p>An encoded ASN/1 message is a tuple contianing two or three elements : a <strong>T</strong>ype, a <strong>L</strong>ength and optionally - ie if the length is not 0 - a <strong>V</strong>alue. This tuple is called a <strong>TLV</strong>. Every message is a <strong>TLV</strong>. </p>
+<p>But a message can be have complex structure, so a <strong>TLV</strong> itself can encapsulate some <strong>TLV</strong>s. Actually the <strong>V</strong> part can be a list of <strong>TLV</strong>s. This is recursive...</p>
+<p>A typical encoded message can therefore represented this way : </p>
+<div class="codehilite"><pre><span class="p">[</span><span class="n">TL</span> <span class="p">[</span><span class="n">TLV</span><span class="p">]</span> <span class="p">[</span><span class="n">TL</span> <span class="p">[</span><span class="n">TLV</span><span class="p">]</span> <span class="p">[</span><span class="n">TLV</span><span class="p">]]]</span>
+</pre></div>
+
+
+<p>Here, the message <strong>TLV</strong> value is a set of two <strong>TLV</strong>s, teh second one being itself a composition of 2 <strong>TLV</strong>s.</p>
+<p>The <strong>T</strong> describe the type of value, the <strong>L</strong> gives the length of this value (can be 0) and of course the <strong>V</strong> is the value, which can itself be a <strong>TLV</strong>.</p>
+<h3 id="encoderdecoder">Encoder/Decoder<a class="headerlink" href="#encoderdecoder" title="Permanent link">¶</a></h3>
+<p>There are two aspects we have to deal with : </p>
+<ul>
+<li>encoding messages</li>
+<li>decoding messages</li>
+</ul>
+<p>Those are two different things, and we don't use the same mechanism. <strong>Encoding</strong> is done using a <em>State Machine</em>, and <strong>Decoding</strong> which is hard wired in each class implementing a message.</p>
+<p>As we said, it's not perfect, first because it's complex to implement, complex to add a new message, and complex to test. We don't have a compiler that generates the stubs to encode or decode messages.</p>
+<h3 id="decoder">Decoder<a class="headerlink" href="#decoder" title="Permanent link">¶</a></h3>
+<p>The <em>Decoder</em> work is to take a <strong>byte[]</strong> and transform it into an instance of a jave object. When we receive the <strong>byte[]</strong>, we don't know yet what kind of message we are dealing with, so the creation of the instance is differed.</p>
+<p>We have built a generic decoder that takes some imputs and produces the result, based on those elements :</p>
+<ul>
+<li>A <em>Grammar</em></li>
+<li>A <em>Container</em></li>
+<li>A <em>StateEnum</em></li>
+<li>A <em>Decorator</em></li>
+<li>and optionally a <em>Factory</em></li>
+</ul>
+<p>The <em>Grammar</em> describes the transitions and actions of the state machine used to decode a message. Note that the actions can be stored in separate classes.</p>
+<p>The <em>Container</em> is a wrapper around a message that is fed by the State Machine and that will contain the Java instance once fully decoded. It's initally empty.</p>
+<p>The <em>StateEnum</em> is a Java enumeration listing all the possible <em>Grammar</em> states.</p>
+<p>The <em>Decorator</em> is a wrapper used to store a decoded message.</p>
+<p>The <em>Factory</em> is used to create the message instance (it's optional)</p>
+<p>And of course, you have the messsage class that will be created and stored in the <em>Decorator</em></p>
+<p>So what we have is based on a <strong>State Engine</strong>, which means you have to describe </p>
+<h3 id="encoder">Encoder<a class="headerlink" href="#encoder" title="Permanent link">¶</a></h3>
+<p>It's slightly simpler : we use the <em>Decorator</em> to implement the encoding of a message. Two methods are necessary :</p>
+<ul>
+<li><em>int computeLength()</em> : compute the <em>ByteBuffer</em> size necessary to stored the encoded message</li>
+<li><em>ByteBuffer encode( ByteBuffer )</em> : actually encode the message into a <em>ByteBuffer</em></li>
+</ul>
+<h3 id="the-state-machine">The state machine<a class="headerlink" href="#the-state-machine" title="Permanent link">¶</a></h3>
+<p>So we decode a message using a state machine, which basically transit from one state to another, and optionally execute an action in between :</p>
+<p><img alt="State Machine transition" src="images/sm-transition.png" /></p>
+
+
+ <div class="nav">
+ <div class="nav_prev">
+
+ <a href="3-building.html">3 - Building</a>
+
+ </div>
+ <div class="nav_up">
+
+ <a href="../dev-guide.html">Developer Guide</a>
+
+ </div>
+ <div class="nav_next">
+
+ <a href="5-network.html">5 - Network</a>
+
+ </div>
+ <div class="clearfix"></div>
+ </div>
+
+
+ </div><!-- rightColumn -->
+ <div id="endContent"></div>
+ </div><!-- content -->
+ <div id="footer">© 2003-2015, <a href="http://www.apache.org">The Apache Software Foundation</a> - <a href="./../../privacy-policy.html">Privacy Policy</a><br />
+ Apache Directory, ApacheDS, Apache Directory Server, Apache Directory Studio, Apache LDAP API, Apache Triplesec, Triplesec, Apache Mavibot, Mavibot, Apache eSCIMo, eSCIMo, Fortress, Apache Fortress, EnMasse, Apache EnMasse, Apache Kerby, Kerby
+ Apache, the Apache feather logo, and the Apache Directory project logos are trademarks of The Apache Software Foundation.
+ </div>
+ </div><!-- container -->
+ </body>
+</html>
\ No newline at end of file
Added: websites/staging/directory/trunk/content/api/dev-guide/images/asn1-codec.graphml
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/directory/trunk/content/api/dev-guide/images/asn1-codec.graphml
------------------------------------------------------------------------------
svn:mime-type = application/xml
Added: websites/staging/directory/trunk/content/api/dev-guide/images/asn1-codec.png
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/directory/trunk/content/api/dev-guide/images/asn1-codec.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: websites/staging/directory/trunk/content/api/dev-guide/images/sm-transition.graphml
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/directory/trunk/content/api/dev-guide/images/sm-transition.graphml
------------------------------------------------------------------------------
svn:mime-type = application/xml
Added: websites/staging/directory/trunk/content/api/dev-guide/images/sm-transition.png
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/directory/trunk/content/api/dev-guide/images/sm-transition.png
------------------------------------------------------------------------------
svn:mime-type = image/png