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/18 10:06:33 UTC
svn commit: r1023954 [3/5] - in /websites/staging/directory/trunk/content:
./ api/ api/dev-guide/ api/internal-design-guide/
api/internal-design-guide/images/
Added: websites/staging/directory/trunk/content/api/internal-design-guide/2-general-structure.html
==============================================================================
--- websites/staging/directory/trunk/content/api/internal-design-guide/2-general-structure.html (added)
+++ websites/staging/directory/trunk/content/api/internal-design-guide/2-general-structure.html Thu Jan 18 10:06:32 2018
@@ -0,0 +1,326 @@
+<!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>2 - General Structure — 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="1-introduction.html">1 - Introduction</a>
+
+ </div>
+ <div class="nav_up">
+
+ <a href="../internal-design-guide.html">Internal Design Guide</a>
+
+ </div>
+ <div class="nav_next">
+
+ <a href="3-building.html">3 - Building</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="2-general-structure">2 - General Structure<a class="headerlink" href="#2-general-structure" title="Permanent link">¶</a></h1>
+<p>The <strong>Apache LDAP API</strong> is split into many modules. Here is their hierarchy :</p>
+<p><img alt="Modules" src="images/ldap-api-modules.png" />
+<pre>
+LDAP API root
+ |
+ +-- all
+ |
+ +-- asn1
+ | |
+ | +-- api
+ | |
+ | +-- ber
+ |
+ +-- distribution
+ |
+ +-- dsml
+ | |
+ | +-- engine
+ | |
+ | +-- parser
+ |
+ +-- i18n
+ |
+ +-- integ
+ |
+ +-- integ-osgi
+ |
+ +-- ldap
+ | |
+ | +-- client
+ | | |
+ | | +-- all
+ | | |
+ | | +-- api
+ | |
+ | +-- codec
+ | | |
+ | | +-- core
+ | | |
+ | | +-- standalone
+ | |
+ | +-- extras
+ | | |
+ | | +-- aci
+ | | |
+ | | +-- codec
+ | | |
+ | | +-- codec-api
+ | | |
+ | | +--sp
+ | | |
+ | | +-- trigger
+ | | |
+ | | +-- util
+ | |
+ | +-- model
+ | |
+ | +-- net
+ | | |
+ | | +-- mina
+ | |
+ | +-- schema
+ | |
+ | +-- converter
+ | |
+ | +-- data
+ |
+ +-- util
+</pre></p>
+<ul>
+<li>
+<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>
+</li>
+<li>
+<p>The <strong>distribution</strong> module just create the packages</p>
+</li>
+<li>
+<p>The <strong>dsml</strong> module covers <em>DSML</em> features</p>
+</li>
+<li>
+<p>The <strong>i18n</strong> module contains all the messages, in various languages (english, french and german at the moment)</p>
+</li>
+<li>
+<p>The <strong>integ</strong> module is for integration tests, covering many of the existing modules</p>
+</li>
+<li>
+<p>The <strong>integ-osgi</strong> module covers tests related to <strong>OSGi</strong> integration. It checks that we can instanciate some component within an <strong>OSGi</strong> framework.</p>
+</li>
+<li>
+<p>The <strong>ldap</strong> modules are the meat of the <em>API</em> : they contain all the needed modules related to <em>LDAP</em>, and mainly the <em>model</em> module. Note that the <em>net</em> module should not be part of <strong>ldap</strong>, per se...</p>
+</li>
+<li>
+<p>The <strong>util</strong> module contains classes that are shared across the various modules.</p>
+</li>
+</ul>
+<p>Anyway, from a developer point of view, that does not tell a lot about the inner struture.</p>
+<p>Clearly, the entry point is the <em>Connection</em> interface and its inherited class, which reside in the <em>api-ldap-client-api</em> module, in <em>/ldap/client/.api</em>. This is the interface - or one of its implementation - that is used to connect to a LDAP server. Here is the full hierarchy :</p>
+<p><img alt="LdapConnection" src="images/ldap-connection.png" /></p>
+<p>The user will need a <em>LdapNetworkConnection</em> most of the time, the wrapper is just used by the connection pool. Note that <em>ApacheDS</em> has its own implementation (not represented in this picture), called <em>LdapCoresSessionConnection</em>.</p>
+<p>So, bottom line, if you want to have a look at how the <em>API</em> works, the entry point is the *LdapNetworkConnection class.</p>
+<h2 id="layers">Layers<a class="headerlink" href="#layers" title="Permanent link">¶</a></h2>
+<p>If you consider a <em>LdapConnection</em>, obviously, you will have to connect to a remote server, and you will need a part of the code handling the network. This is done - currently - using <em>Apache MINA</em>, which is an <em>NIO</em> framework. That means all the communication with the remote <em>LDAP</em> server is done asynchroniously.</p>
+<p>We also made so the <em>API</em> to be <em>OSGi</em> compliant. That means some of the parts need to be 'activated'. The idea was to make it possible to extend the <em>API</em> easily by adding component that could be loaded dynamically. So far, it's not a completed work, but still, this is a on-going process.</p>
+<p>The following pitcure shows for 10 000 feet the <em>LDAP API</em> architecture :</p>
+<p><img alt="LDAP API Architecture" src="images/architecture.png" /></p>
+
+
+ <div class="nav">
+ <div class="nav_prev">
+
+ <a href="1-introduction.html">1 - Introduction</a>
+
+ </div>
+ <div class="nav_up">
+
+ <a href="../internal-design-guide.html">Internal Design Guide</a>
+
+ </div>
+ <div class="nav_next">
+
+ <a href="3-building.html">3 - Building</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/internal-design-guide/3-building.html
==============================================================================
--- websites/staging/directory/trunk/content/api/internal-design-guide/3-building.html (added)
+++ websites/staging/directory/trunk/content/api/internal-design-guide/3-building.html Thu Jan 18 10:06:32 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="../internal-design-guide.html">Internal Design 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="../internal-design-guide.html">Internal Design 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/internal-design-guide/4-asn1.html
==============================================================================
--- websites/staging/directory/trunk/content/api/internal-design-guide/4-asn1.html (added)
+++ websites/staging/directory/trunk/content/api/internal-design-guide/4-asn1.html Thu Jan 18 10:06:32 2018
@@ -0,0 +1,272 @@
+<!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="../internal-design-guide.html">Internal Design Guide</a>
+
+ </div>
+ <div class="nav_next">
+
+ <a href="4.1-asn1-tlv.html">4.1 - ASN/1 TLV</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>
+<p>Now, let's see a real example.</p>
+
+
+ <div class="nav">
+ <div class="nav_prev">
+
+ <a href="3-building.html">3 - Building</a>
+
+ </div>
+ <div class="nav_up">
+
+ <a href="../internal-design-guide.html">Internal Design Guide</a>
+
+ </div>
+ <div class="nav_next">
+
+ <a href="4.1-asn1-tlv.html">4.1 - ASN/1 TLV</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