directory-api mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Emmanuel Lecharny <>
Subject Re: [Shared] API Design Questionnaire #1
Date Sat, 29 Jan 2011 13:38:25 GMT
On 1/28/11 5:58 PM, Alex Karasulu wrote:
> Hi community,
> Now that we're coming close to finishing up the shared refactoring we have
> to make some choices. Not all these choices have major impacts but some
> might. In the past we could do what we liked and change our minds etc. Now
> with a 1.0 of the shared libraries as the future mother of all Java LDAP
> APIs we're going to have to live with our choices.
> To opine, just place an 'X' in an option [  ] box.
> (1) ModifyRequest has a bunch of methods that were recently added to perform
> the same operations that you use the Modification interface for. This is
> redundant in my opinion and adds more unnecessary surface area. We don't
> need it and don't need an optional path to do the same thing confusing our
> users.  I suggest removing them.
> [  ] Yes - get rid of extra optional methods
> [X] No  - keep the extra optional methods
> [  ] --- - I don't care about this stuff

But I would change their names. They are confusing. Be aware that I'm 
not 100% convinced that those methods are *really* important, so I may 
change my opinion later (to 'remove them')
> (2) Interfaces verses simple/basic classes implementing them have been
> something I've swayed back and forth on. Here are the options but note I am
> just using AddRequest as an example.
> [X] - (a)
>              interface                                 = *I*AddRequest
>              simple API exposed implementation         = AddRequest
>              not so simple internal use implementation = AddRequest*Decoder*
> [X] - (c)
>              interface                                 = AddRequest
>              simple API exposed implementation         = AddRequest*Impl*
>              not so simple internal use implementation = AddRequest*Decoder*
> We're applying option 'C' right now. I'm torn but think A might suite us
> better for the long term, and for any situation. You also know what's an
> interface and what's not although the IDE automatically shows you this stuff
> on the package/class browser.
I do think that *I* is better for users, as it gives them a clue about 
the fact that's is an interface.

In any case, if we pick this option, we have to do it for all the code base.

Right now, I suggest we stay on (c)

> (3) JNDI remnants are somewhat still present even if we've gotten rid of
> most of them. In the model interfaces for Control, ExtendedRequest, and
> ExtendedResponse (IntermediateResponse as well but this has nothing to do
> with JNDI) we have exposed access to ASN.1 encoded data. I think this is a
> big mistake to do in the public API.

Never had the energy to get rid of those. One of the reasons was that we 
used those classes inside the server (in the SP part).

But, yes, we must get rid of them. There is an existing JIRA for such an 
action, btw.
> Controls and extended operation interfaces should simply expose
> parameters/properties leaving the rest up to the CODEC to handle. There
> should be no need to get or set the entire ASN.1 blob for the control or
> extended operation's request response pair. What good does it do anyway?
> It's just opening the door for users to incorrectly alter properly encoded
> ASN.1 data causing problems. I think the getValue() setValue() methods
> remained after we ran screaming away from JNDI. But it seems these
> interfaces remained and now they're a liability. Where manipulation of the
> binary ASN.1 data is needed we can leave this up to the CODEC under a
> decorator to do.
> I recommend removing these, what do you think?
> [X] Yes - Remove them, they are more bad then good
> [  ] No  - Don't remove them, I like using em
> [  ] --- - I don't give a rat's a**

Emmanuel L├ęcharny

View raw message