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:06: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 (16)</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" > <br>||Class||Visibility||Purpose||
<br></td></tr>
            <tr><td class="diff-changed-lines" >|Foo|(y)|An interface for your
<span class="diff-added-words"style="background-color: #dfd;">Foo</span> control|
<br></td></tr>
            <tr><td class="diff-changed-lines" >|FooImpl|(y)|A simple implementation
of your <span class="diff-added-words"style="background-color: #dfd;">Foo</span>
control| <br></td></tr>
            <tr><td class="diff-unchanged" >|FooFactory|(n)|Factory for your control|
<br>|FooDecorator|(n)|Decorates your control so the codec can handle it while encoding
and decoding| <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >|Anything else|(n)|Up to you| <br>
<br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">You
might have more than one control in your bundle. Whether you do or not, you&#39;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. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">If
these bundles are started (via supplied configuration parameters) they register controls and
extended operations into the codec.  <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">{note}
<br>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.   <br>{note} <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">New
control implement <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h3.
Configuration and Loading <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">Either
a specified directory or configuration parameters can be used to instruct the codec where
to find extension bundles. We&#39;ll document that as we go.  <br></td></tr>
            <tr><td class="diff-unchanged" > <br>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. <br> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Those
wanting to extend the codec by writing new controls and extended operations need to create
two separate bundles. From this point we&#39;ll talk about controls only but the same
mechanism applies to extended operations. First an API bundle that exposes a  <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">http://felix.apache.org/site/apache-felix-framework-launching-and-embedding.html
<br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-changed-lines" >The codec top level directory
is located under shared. It is a maven <span class="diff-changed-words">multi<span
class="diff-added-chars"style="background-color: #dfd;">-</span>project</span>
having the following directory layout: <br></td></tr>
            <tr><td class="diff-unchanged" > <br>{noformat} <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">codec/
<br>   core <br>   api <br>   spi <br>   controls/ <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">codec/
                      --&gt; top level codec directory under shared/ <br>   internal/
                --&gt; codec internals: things we want hidden to everyone <br> 
 api/                      --&gt; codec&#39;s public API needed to embed it and use
it only <br>   spi/                      --&gt; codec&#39;s service provider
interface needed to extend it <br>   controls/                 --&gt; top level
for control extensions <br></td></tr>
            <tr><td class="diff-changed-lines" >replication/ <span class="diff-added-words"style="background-color:
#dfd;">            --&gt; for example replication controls</span> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">
     ppolicy/ <br>   extended/ <br>      foo/ <br>      bar/  <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">
     ppolicy/                 --&gt; or the password policy controls <br>      .../
                    --&gt; many more may come ... <br>   extended/             
   --&gt; top level for extended request and response extensions  <br>      cancel/
                 --&gt; cancel operations <br>      certGeneration/          --&gt;
certificate generation requests <br>      storedProcedure/         --&gt; for stored
procedure operations <br>      .../                     --&gt; many more may come
<br></td></tr>
            <tr><td class="diff-unchanged" >{noformat} <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>

    </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=3&originalVersion=2">View
Changes</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message