directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Alex Karasulu <akaras...@apache.org>
Subject Re: Shared refactoring : what's going on, some feedback
Date Sun, 23 Jan 2011 13:47:14 GMT
On Sun, Jan 23, 2011 at 12:06 PM, Emmanuel Lecharny <elecharny@gmail.com> wrote:
> Hi guys,
>
> as you noticed, some heavy code refactoring is going on in shared. Let me
> give you some feedback about what is being done, and the reasons for those
> refactoring.

Thanks for sending this mail.

> First of all, the idea is to release a shared/LdapAPI 1.0-M1 asap. It will
> be LdapAPI from this point, and not anymore shared. This will be a
> milestone, but it will also be a first step toward the exposed API. When we
> will come with a 1.0-RC1, the API will have to be frozen. That being said,
> let's see where we are going to :
>
> - base class renaming. You can see that Alex changed DN to Dn, etc. The
> rational behind those renamings is that it's consistent with the name scheme
> we use : caml humps all over the code. We have a DnParser class, and a DN
> class, which is not consistent. All in all, we discussed those names back in
> september, and if you really feel that DN is better than Dn, we can revert,
> but I thik it's not really a technical issue, much more a choice to make. To
> me, it's not an issue at all.

To me there are two technical merits to a consistent approach (either
DN+DNParser or Dn+DnParser). First is consistency and the second has
to do with user expectations and tab completion. If API users tab
complete after typing DN they should see everything that starts with
DN including the DNParser or vice versa if using camel humps.

Last but not least, API advice is to use the conventions of your
platform. Our platform is Java and camel humps is the convention but
it got ill defined here due to acronyms. We have many of them in our
space too.

> - API/SPI separation : most of what Alex is doing right now is about hiding
> implementation from the exposed API. The less classes exposed, the less
> problem we might have with users using the SPI classes. ALso consider that
> the API documentation will be more tight.

Hopefully with less API surface area exposed this means less API
changes which means less  documentation changes.

> - OSGi : shared has been completely OSGified, and it's a good thing.

I still have shared-all left but no biggie we can get that wrapped up fast.

We have
> postponed this task year after year, but we reached a point it was to be
> done. One of the reason was that refactoring shared without impacting Studio
> was impossible, because Eclipse dos not allow a project to 'see' shared as a
> dependent source project, so we had to propagate the changes manually,
> something we don't want to do anymore. With the OSGi bundles, studio is now
> directly impacted by shared refactoring without any need to do it by hand.
> Plus OSGi is the best way to manage dependencies, and for shared, it cost
> almost nothing to switch to OSGi (well, it took one day). I also do think
> that after shared refactoring, we have to go for Apacheds.

Yep that might be a little more time consuming but not as much a big
deal. With respect to shared I was about to start breaking apart a
couple more modules but was afraid I might leave trunk a bit
inconsistent until I can get some help from Pierre Monday.

I will be creating the following new modules:

ldap-schema-converter
ldap-model
ldap-client
ldap-codec

Word on extensions. These are features that studio and apacheds have
specific to what we do here at Apache Directory for LDAP rather than
for LDAP in general. We might do similar things for Kerberos and other
protocols. Things like our ACI model and our Administrative model are
things that are X.500 (DAP) spec driven but not part of standard LDAP.

ldap-ext-aci
ldap-ext-x500 or ldap-ext-admin or ldap-ext-subtree etc ... undecided
ldap-ext-sp
ldap-ext-triggers

This now leads me to this thought. We might want to start grouping
some modules together with filesystem and pom nesting in shared like
so:

Legend:
---
foo/ => nested directory for grouping
bar  => without trailing '/' for maven module - osgi bundle
---

shared/
   asn1/
      api
      ber
   ldap/
      ldap-ext/
          aci
          admin
          sp
          trigger
      codec
      model
      schema
      client
   kerberos
      model
      .... etc

This is just a thought. Also we need to make some aggregating bundles
like for ldap-api I think this should be an aggregate like the
shared-all but with the minimum set. Users not working with ApacheDS
will not want to see ApacheDS and Studio specific extended API
elements but the minimum set required to work with vanilla LDAP.

> At the end of the day, the refactoring should be finished soon (maybe one or
> two more days). It may create new sub-modules, which may be gathered later,
> not a big deal. Just keep an eye at what is being done, if you disagree,
> feel free to express your opinion.

OK to make this timeline I will have to get a bit aggressive - we
might have breakage and I will ask Pierre to help me fix the effects
these new module additions will have when he gets back Monday.

Will be back in a couple hours to start again.

> One important point is that we are using a c-t-r mode (commit then review)
> and not a r-t-c, and I think we don't want to switch to a r-t-c at this
> point of the project :). Committing is not for ever, you can -1 one commit,
> it's not an insult to the one who did the commit. I repeat, -1 a commit is
> not an insult. Just be rational, and express your technical vision when you
> -1 something.
>
> All in all, at first I was quite conservative, but I realized that we
> probably need some fresh perspective, because we are all so deeply involved
> that we don't have anymore a 10K feet vision necessary to see what's wrong
> and what's good. It's a good timing now that the API is stable to review it,
> shake it and make it better.

Yeah it's going to be really nice I think.

> Guys, I engage you to look at what Alex is doing when it will be done, and
> express your opinion then. I think this is one unique opportunity to move
> away from a local minimum to the next stable state.

Yes we discussed this on IRC. Very interesting conversation we had.
Sometimes when you stabilize you get stuck in a local minima/maxima.
It takes some jitter to escape it and move on to something which may
be the global minima/maxima: a la genetic algorithms.

I'm lucky to have taken a break from the code and have some fresh eyes
while knowing the code unlike someone new. I'd like to share this
advantage I've gained with you guys so we can all benefit from
something which initially looked like a bad thing. There are pros and
cons to everything in the end.

OK stepping out for a couple hours and will be back to begin more
refactoring. Build may destabilize but hopefully I can work with
Pierre to fix the issues arising from the new modules.

Best,
-- 
Alex Karasulu
My Blog :: http://www.jroller.com/akarasulu/
Apache Directory Server :: http://directory.apache.org
Apache MINA :: http://mina.apache.org
To set up a meeting with me: http://tungle.me/AlexKarasulu

Mime
View raw message