directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Directory Server v1.5 > Codec Subsystem
Date Mon, 31 Jan 2011 05:18:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2036/9/1/_/styles/combined.css?spaceKey=DIRxSRVx11&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/DIRxSRVx11/Codec+Subsystem">Codec
Subsystem</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~akarasulu">Alex
Karasulu</a>
    </h4>
        <br/>
                         <h4>Changes (2)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >      certGeneration/          --&gt;
certificate generation requests <br>      storedProcedure/         --&gt; for stored
procedure operations <br></td></tr>
            <tr><td class="diff-changed-lines" >.../                     --&gt;
many more may come <span class="diff-added-words"style="background-color: #dfd;">...</span>
<br></td></tr>
            <tr><td class="diff-unchanged" >{noformat} <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">
<br>h3. Future <br> <br>In the future it would be nice to have the SPI really
be an annotation library. Users annotate their control interface and this is the only Java
artifact in their extension bundle. The codec on registration of this interface (instead of
the old factory method), reads the annotations to determine how to build the grammar, container,
and decorator. It also generates the simple implementation. This is all done dynamically at
registration time. <br> <br>ASM can be used to create these classes or something
more dynamic can be used to avoid runtime class generation. The annotations can be simple
instructions about the ASN.1 composition of the Control interface properties. With such a
system writing new controls would be very easy to do. <br> <br>Studio can also
provide tooling support for those who want to build and deploy a new control. It can help
them design the control with annotations, and help test the operation of the control to verify
it&#39;s correct definition with round trip tests that are automatically generated. This
can take out the tediousness from the entire process and rapidly speed up enhancements to
the client, the server and even to studio. <br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <div class='panelMacro'><table class='warningMacro'><colgroup><col
width='24'><col></colgroup><tr><td valign='top'><img src="/confluence/images/icons/emoticons/forbidden.gif"
width="16" height="16" align="absmiddle" alt="" border="0"></td><td>This document
at this point represents the end state of the codec subsystem. We are presently trying to
get to this state. The point is this is where we want to be and by documenting it we can all
align towards this end state.</td></tr></table></div>

<h2><a name="CodecSubsystem-FinalConfiguration"></a>Final Configuration</h2>

<p>The codec is an extensible subsystem enabling extension for new controls and extended
operations. It hides internal implementation details as much as possible exposing a very simple
API for using it for embedding purposes. An SPI is provided for those extending it while still
exposing as little as possible, however much more is exposed by the SPI to enable pluggable
controls and extended operations.</p>

<p>The codec is naturally embedded into the client API, studio and the server. Although
we don't foresee many using the API, it helps us keep the embedding interface as small as
possible for our internal projects. Then again others may have a reason for embedding the
codec into their applications. By making this portion of the codec into a separate jar/bundle
and only depending on it in our projects, we can be certain to prevent implementation creep
into the rest of our stack.</p>

<p>The codec exposes much more in its SPI for those wanting to extend it with new controls
and extended operations. This SPI is a separate module in itself. This makes sure more implementation
details do not seep into higher levels in our project yet making sure all necessary details
are exposed to extenders.</p>

<h3><a name="CodecSubsystem-ControlandExtendedOperationModularity"></a>Control
and Extended Operation Modularity</h3>

<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/warning.gif" width="16" height="16"
align="absmiddle" alt="" border="0"></td><td>Although we just talk about controls,
this also applies to extended operations as well which use the same mechanism.</td></tr></table></div>

<p>The extension mechanism uses OSGi. Control bundles are provided by developers and
loaded. On load, via activators, the control bundles register their ControlFactory implementations
with the LdapCodecService. Bundle providers should only export their control interface and
perhaps optionally a simple implementation of their control. The bundle should contain the
following items:</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'>Class</th>
<th class='confluenceTh'>Visibility</th>
<th class='confluenceTh'>Purpose</th>
</tr>
<tr>
<td class='confluenceTd'>Foo</td>
<td class='confluenceTd'><img class="emoticon" src="/confluence/images/icons/emoticons/thumbs_up.gif"
height="19" width="19" align="absmiddle" alt="" border="0"/></td>
<td class='confluenceTd'>An interface for your Foo control</td>
</tr>
<tr>
<td class='confluenceTd'>FooImpl</td>
<td class='confluenceTd'><img class="emoticon" src="/confluence/images/icons/emoticons/thumbs_up.gif"
height="19" width="19" align="absmiddle" alt="" border="0"/></td>
<td class='confluenceTd'>A simple implementation of your Foo control</td>
</tr>
<tr>
<td class='confluenceTd'>FooFactory</td>
<td class='confluenceTd'><img class="emoticon" src="/confluence/images/icons/emoticons/thumbs_down.gif"
height="19" width="19" align="absmiddle" alt="" border="0"/></td>
<td class='confluenceTd'>Factory for your control</td>
</tr>
<tr>
<td class='confluenceTd'>FooDecorator</td>
<td class='confluenceTd'><img class="emoticon" src="/confluence/images/icons/emoticons/thumbs_down.gif"
height="19" width="19" align="absmiddle" alt="" border="0"/></td>
<td class='confluenceTd'>Decorates your control so the codec can handle it while encoding
and decoding</td>
</tr>
<tr>
<td class='confluenceTd'>FooGrammar</td>
<td class='confluenceTd'><img class="emoticon" src="/confluence/images/icons/emoticons/thumbs_down.gif"
height="19" width="19" align="absmiddle" alt="" border="0"/></td>
<td class='confluenceTd'>The Grammar defining the transition states while decoding your
control</td>
</tr>
<tr>
<td class='confluenceTd'>FooContainer</td>
<td class='confluenceTd'><img class="emoticon" src="/confluence/images/icons/emoticons/thumbs_down.gif"
height="19" width="19" align="absmiddle" alt="" border="0"/></td>
<td class='confluenceTd'>A container for packaging your control but soon this might
not be needed</td>
</tr>
<tr>
<td class='confluenceTd'>Anything else</td>
<td class='confluenceTd'><img class="emoticon" src="/confluence/images/icons/emoticons/thumbs_down.gif"
height="19" width="19" align="absmiddle" alt="" border="0"/></td>
<td class='confluenceTd'>Up to you</td>
</tr>
</tbody></table>
</div>


<p>You might have more than one control in your bundle. Whether you do or not, you'll
want to keep all your control interfaces and simple implementations in a directory separate
from your implementation classes. This way you can just export this package from your bundle.
Client code outside of the codec will still want to use your control interfaces and classes
while issuing them in various LDAP operations.</p>

<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/warning.gif" width="16" height="16"
align="absmiddle" alt="" border="0"></td><td>A Maven archetype will be made
available to generate control and extension bundle projects so those wanting to extend the
codec can start working quickly on new own controls and extensions.</td></tr></table></div>

<h3><a name="CodecSubsystem-ConfigurationandLoading"></a>Configuration and
Loading</h3>

<p>Either a specified directory or configuration parameters can be used to instruct
the codec where to find extension bundles. We'll document that as we go. </p>

<p>Either the entire codec will run inside an OSGi environment (future goal) or it will
use an embedded instance of Felix. Embedding Felix into the codec itself allows us to interface
with bundles that can be dynamically loaded to register their controls and extended.</p>

<p><a href="http://felix.apache.org/site/apache-felix-framework-launching-and-embedding.html"
class="external-link" rel="nofollow">http://felix.apache.org/site/apache-felix-framework-launching-and-embedding.html</a></p>

<p>The codec top level directory is located under shared. It is a maven multi-project
having the following directory layout:</p>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>codec/                       --&gt; top level codec directory under shared/
   internal/                 --&gt; codec internals: things we want hidden to everyone
   api/                      --&gt; codec's public API needed to embed it and use it only
   spi/                      --&gt; codec's service provider interface needed to extend
it
   controls/                 --&gt; top level for control extensions
      replication/             --&gt; for example replication controls
      ppolicy/                 --&gt; or the password policy controls
      .../                     --&gt; many more may come ...
   extended/                 --&gt; top level for extended request and response extensions

      cancel/                  --&gt; cancel operations
      certGeneration/          --&gt; certificate generation requests
      storedProcedure/         --&gt; for stored procedure operations
      .../                     --&gt; many more may come ...
</pre>
</div></div>

<h3><a name="CodecSubsystem-Future"></a>Future</h3>

<p>In the future it would be nice to have the SPI really be an annotation library. Users
annotate their control interface and this is the only Java artifact in their extension bundle.
The codec on registration of this interface (instead of the old factory method), reads the
annotations to determine how to build the grammar, container, and decorator. It also generates
the simple implementation. This is all done dynamically at registration time.</p>

<p>ASM can be used to create these classes or something more dynamic can be used to
avoid runtime class generation. The annotations can be simple instructions about the ASN.1
composition of the Control interface properties. With such a system writing new controls would
be very easy to do.</p>

<p>Studio can also provide tooling support for those who want to build and deploy a
new control. It can help them design the control with annotations, and help test the operation
of the control to verify it's correct definition with round trip tests that are automatically
generated. This can take out the tediousness from the entire process and rapidly speed up
enhancements to the client, the server and even to studio.</p>



    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/DIRxSRVx11/Codec+Subsystem">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=25200296&revisedVersion=4&originalVersion=3">View
Changes</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message