You are viewing a plain text version of this content. The canonical link for it is here.
Posted to api@directory.apache.org by Alex Karasulu <ak...@apache.org> on 2011/01/28 17:58:54 UTC
[Shared] API Design Questionnaire #1
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
[ ] No - keep the extra optional methods
[ ] --- - I don't care about this stuff
(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.
[ ] - (a)
interface = *I*AddRequest
simple API exposed implementation = AddRequest
not so simple internal use implementation = AddRequest*Decoder*
[ ] - (b)
interface = AddRequest
simple API exposed implementation = *Simple*AddRequest
not so simple internal use implementation = AddRequest*Decoder*
[ ] - (c)
interface = AddRequest
simple API exposed implementation = AddRequest*Impl*
not so simple internal use implementation = AddRequest*Decoder*
[ ] - (d)
interface = AddRequest
simple API exposed implementation = *Basic*AddRequest
not so simple internal use implementation = AddRequest*Decoder*
[ ] - (e) I pick the fat lady with the pink tutu ....
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.
(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.
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?
[ ] 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**
--
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
Re: [Shared] API Design Questionnaire #1
Posted by Emmanuel Lecharny <el...@gmail.com>.
On 1/30/11 7:07 PM, Alex Karasulu wrote:
> On Sun, Jan 30, 2011 at 7:29 PM, Stefan Seelmann<se...@apache.org>wrote:
>
>> On Sun, Jan 30, 2011 at 5:11 PM, Alex Karasulu<ak...@apache.org>
>> wrote:
>>> On Sun, Jan 30, 2011 at 3:17 AM, Emmanuel Lecharny<elecharny@gmail.com
>>> wrote:
>>>
>>>> On 1/29/11 10:38 PM, Stefan Seelmann wrote:
>>>>
>>>>> [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.
>>>>>>
>>>>> This is my opinion for a low-level API, which 1:1 maps LDAP
>>>>> terminology to the Java API. I think we should additional have a
>>>>> simplified API where the user don't need to deal with request and
>>>>> response objects at all.
>>>>>
>>>>> BTW: We have this discussion again and again ;-) We really need to
>>>>> decide a consistent naming.
>>>>>
>>>> I think we already discussed it more than once, and we all agreed on
>> this
>>>> convention.
>>>>
>>>> I'm not sure we want to rehash this again every 2 years :/
>>>>
>>>>
>>> When there's a push to release a 1.0 of an API, we need to make the API
>>> consistent. I can do this myself but the community way is to have a
>>> discussion. If you do not want to discuss this feel free not to
>>> participate, or say you don't care.
>> I don't see that anyone said that the API development should not be
>> community driven.
>>
> I did not suggest anyone said that. If you read above I am saying I have no
> choice but to post and share with the community rather than do it myself.
We have to be careful in our phrasing. Or we should be careful in the
way we understand things.
The *I* notation in shared has been added temporarily in order to ease
the refactoring, and should be removed in trunk.
Again, injecting them in trunk was probably a wrong move, and should
have been done in a branch. We all know that...
Ok, assuming that this was just a misunderstanding, I guess we can move on.
--
Regards,
Cordialement,
Emmanuel Lécharny
www.iktek.com
Re: [Shared] API Design Questionnaire #1
Posted by Alex Karasulu <ak...@apache.org>.
On Sun, Jan 30, 2011 at 7:29 PM, Stefan Seelmann <se...@apache.org>wrote:
> On Sun, Jan 30, 2011 at 5:11 PM, Alex Karasulu <ak...@apache.org>
> wrote:
> > On Sun, Jan 30, 2011 at 3:17 AM, Emmanuel Lecharny <elecharny@gmail.com
> >wrote:
> >
> >> On 1/29/11 10:38 PM, Stefan Seelmann wrote:
> >>
> >>>
> >>> [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.
> >>>>
> >>> This is my opinion for a low-level API, which 1:1 maps LDAP
> >>> terminology to the Java API. I think we should additional have a
> >>> simplified API where the user don't need to deal with request and
> >>> response objects at all.
> >>>
> >>> BTW: We have this discussion again and again ;-) We really need to
> >>> decide a consistent naming.
> >>>
> >>
> >> I think we already discussed it more than once, and we all agreed on
> this
> >> convention.
> >>
> >> I'm not sure we want to rehash this again every 2 years :/
> >>
> >>
> > When there's a push to release a 1.0 of an API, we need to make the API
> > consistent. I can do this myself but the community way is to have a
> > discussion. If you do not want to discuss this feel free not to
> > participate, or say you don't care.
>
> I don't see that anyone said that the API development should not be
> community driven.
>
I did not suggest anyone said that. If you read above I am saying I have no
choice but to post and share with the community rather than do it myself.
--
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
Re: [Shared] API Design Questionnaire #1
Posted by Alex Karasulu <ak...@apache.org>.
On Sun, Jan 30, 2011 at 7:29 PM, Stefan Seelmann <se...@apache.org>wrote:
> On Sun, Jan 30, 2011 at 5:11 PM, Alex Karasulu <ak...@apache.org>
> wrote:
> > On Sun, Jan 30, 2011 at 3:17 AM, Emmanuel Lecharny <elecharny@gmail.com
> >wrote:
> >
> >> On 1/29/11 10:38 PM, Stefan Seelmann wrote:
> >>
> >>>
> >>> [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.
> >>>>
> >>> This is my opinion for a low-level API, which 1:1 maps LDAP
> >>> terminology to the Java API. I think we should additional have a
> >>> simplified API where the user don't need to deal with request and
> >>> response objects at all.
> >>>
> >>> BTW: We have this discussion again and again ;-) We really need to
> >>> decide a consistent naming.
> >>>
> >>
> >> I think we already discussed it more than once, and we all agreed on
> this
> >> convention.
> >>
> >> I'm not sure we want to rehash this again every 2 years :/
> >>
> >>
> > When there's a push to release a 1.0 of an API, we need to make the API
> > consistent. I can do this myself but the community way is to have a
> > discussion. If you do not want to discuss this feel free not to
> > participate, or say you don't care.
>
> I don't see that anyone said that the API development should not be
> community driven.
>
> In shared and apacheds we currently us a mix of the *Impl* suffix and
> the *Default/<whatever>* prefix for classes. I only count two
> interfaces with the *I* prefix, that is probably caused because they
> were moved from studio to shared. In studio there are many more *I*
> prefixed interfaces, which was inspired by the Eclipse naming
> conventions. But afaik we never used *I* prefix in shared or apacheds.
>
> Oh, I just searched for *I* prefixed files, and now there are 14 more, why
> that?
>
> $ find shared -name "I[A-Z]*.java" | cut -d "/" -f 9-
> shared/dsmlv2/IAction.java
> shared/dsmlv2/IGrammar.java
> shared/ldap/codec/controls/ppolicy/IPasswordPolicyRequest.java
> shared/ldap/codec/controls/ppolicy/IPasswordPolicyResponse.java
> shared/ldap/codec/controls/replication/syncDoneValue/ISyncDoneValue.java
> shared/ldap/codec/controls/replication/syncInfoValue/ISyncInfoValue.java
> shared/ldap/codec/controls/replication/syncmodifydn/ISyncModifyDn.java
>
> shared/ldap/codec/controls/replication/syncRequestValue/ISyncRequestValue.java
> shared/ldap/codec/controls/replication/syncStateValue/ISyncStateValue.java
> shared/ldap/codec/ICodecControl.java
> shared/ldap/codec/IControlFactory.java
> shared/ldap/codec/IDecorator.java
> shared/ldap/codec/IExtendedOpFactory.java
> shared/ldap/codec/ILdapCodecService.java
> shared/ldap/codec/ITestCodecControl.java
> shared/ldap/codec/ITestControl.java
>
>
Yep that's a test. I wanted to see how ugly it would be to get a feel for
it. Then I was going to revert it to which ever scheme we chose.
I don't think I like the I* approach.
--
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
Re: [Shared] API Design Questionnaire #1
Posted by Stefan Seelmann <se...@apache.org>.
On Sun, Jan 30, 2011 at 5:11 PM, Alex Karasulu <ak...@apache.org> wrote:
> On Sun, Jan 30, 2011 at 3:17 AM, Emmanuel Lecharny <el...@gmail.com>wrote:
>
>> On 1/29/11 10:38 PM, Stefan Seelmann wrote:
>>
>>>
>>> [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.
>>>>
>>> This is my opinion for a low-level API, which 1:1 maps LDAP
>>> terminology to the Java API. I think we should additional have a
>>> simplified API where the user don't need to deal with request and
>>> response objects at all.
>>>
>>> BTW: We have this discussion again and again ;-) We really need to
>>> decide a consistent naming.
>>>
>>
>> I think we already discussed it more than once, and we all agreed on this
>> convention.
>>
>> I'm not sure we want to rehash this again every 2 years :/
>>
>>
> When there's a push to release a 1.0 of an API, we need to make the API
> consistent. I can do this myself but the community way is to have a
> discussion. If you do not want to discuss this feel free not to
> participate, or say you don't care.
I don't see that anyone said that the API development should not be
community driven.
In shared and apacheds we currently us a mix of the *Impl* suffix and
the *Default/<whatever>* prefix for classes. I only count two
interfaces with the *I* prefix, that is probably caused because they
were moved from studio to shared. In studio there are many more *I*
prefixed interfaces, which was inspired by the Eclipse naming
conventions. But afaik we never used *I* prefix in shared or apacheds.
Oh, I just searched for *I* prefixed files, and now there are 14 more, why that?
$ find shared -name "I[A-Z]*.java" | cut -d "/" -f 9-
shared/dsmlv2/IAction.java
shared/dsmlv2/IGrammar.java
shared/ldap/codec/controls/ppolicy/IPasswordPolicyRequest.java
shared/ldap/codec/controls/ppolicy/IPasswordPolicyResponse.java
shared/ldap/codec/controls/replication/syncDoneValue/ISyncDoneValue.java
shared/ldap/codec/controls/replication/syncInfoValue/ISyncInfoValue.java
shared/ldap/codec/controls/replication/syncmodifydn/ISyncModifyDn.java
shared/ldap/codec/controls/replication/syncRequestValue/ISyncRequestValue.java
shared/ldap/codec/controls/replication/syncStateValue/ISyncStateValue.java
shared/ldap/codec/ICodecControl.java
shared/ldap/codec/IControlFactory.java
shared/ldap/codec/IDecorator.java
shared/ldap/codec/IExtendedOpFactory.java
shared/ldap/codec/ILdapCodecService.java
shared/ldap/codec/ITestCodecControl.java
shared/ldap/codec/ITestControl.java
Kind Regards,
Stefan
Re: [Shared] API Design Questionnaire #1
Posted by Stefan Seelmann <se...@apache.org>.
On Sun, Jan 30, 2011 at 5:11 PM, Alex Karasulu <ak...@apache.org> wrote:
> On Sun, Jan 30, 2011 at 3:17 AM, Emmanuel Lecharny <el...@gmail.com>wrote:
>
>> On 1/29/11 10:38 PM, Stefan Seelmann wrote:
>>
>>>
>>> [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.
>>>>
>>> This is my opinion for a low-level API, which 1:1 maps LDAP
>>> terminology to the Java API. I think we should additional have a
>>> simplified API where the user don't need to deal with request and
>>> response objects at all.
>>>
>>> BTW: We have this discussion again and again ;-) We really need to
>>> decide a consistent naming.
>>>
>>
>> I think we already discussed it more than once, and we all agreed on this
>> convention.
>>
>> I'm not sure we want to rehash this again every 2 years :/
>>
>>
> When there's a push to release a 1.0 of an API, we need to make the API
> consistent. I can do this myself but the community way is to have a
> discussion. If you do not want to discuss this feel free not to
> participate, or say you don't care.
I don't see that anyone said that the API development should not be
community driven.
In shared and apacheds we currently us a mix of the *Impl* suffix and
the *Default/<whatever>* prefix for classes. I only count two
interfaces with the *I* prefix, that is probably caused because they
were moved from studio to shared. In studio there are many more *I*
prefixed interfaces, which was inspired by the Eclipse naming
conventions. But afaik we never used *I* prefix in shared or apacheds.
Oh, I just searched for *I* prefixed files, and now there are 14 more, why that?
$ find shared -name "I[A-Z]*.java" | cut -d "/" -f 9-
shared/dsmlv2/IAction.java
shared/dsmlv2/IGrammar.java
shared/ldap/codec/controls/ppolicy/IPasswordPolicyRequest.java
shared/ldap/codec/controls/ppolicy/IPasswordPolicyResponse.java
shared/ldap/codec/controls/replication/syncDoneValue/ISyncDoneValue.java
shared/ldap/codec/controls/replication/syncInfoValue/ISyncInfoValue.java
shared/ldap/codec/controls/replication/syncmodifydn/ISyncModifyDn.java
shared/ldap/codec/controls/replication/syncRequestValue/ISyncRequestValue.java
shared/ldap/codec/controls/replication/syncStateValue/ISyncStateValue.java
shared/ldap/codec/ICodecControl.java
shared/ldap/codec/IControlFactory.java
shared/ldap/codec/IDecorator.java
shared/ldap/codec/IExtendedOpFactory.java
shared/ldap/codec/ILdapCodecService.java
shared/ldap/codec/ITestCodecControl.java
shared/ldap/codec/ITestControl.java
Kind Regards,
Stefan
Re: [Shared] API Design Questionnaire #1
Posted by Alex Karasulu <ak...@apache.org>.
On Sun, Jan 30, 2011 at 3:17 AM, Emmanuel Lecharny <el...@gmail.com>wrote:
> On 1/29/11 10:38 PM, Stefan Seelmann wrote:
>
>>
>> [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.
>>>
>> This is my opinion for a low-level API, which 1:1 maps LDAP
>> terminology to the Java API. I think we should additional have a
>> simplified API where the user don't need to deal with request and
>> response objects at all.
>>
>> BTW: We have this discussion again and again ;-) We really need to
>> decide a consistent naming.
>>
>
> I think we already discussed it more than once, and we all agreed on this
> convention.
>
> I'm not sure we want to rehash this again every 2 years :/
>
>
When there's a push to release a 1.0 of an API, we need to make the API
consistent. I can do this myself but the community way is to have a
discussion. If you do not want to discuss this feel free not to
participate, or say you don't care.
--
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
Re: [Shared] API Design Questionnaire #1
Posted by Emmanuel Lecharny <el...@gmail.com>.
On 1/29/11 10:38 PM, Stefan Seelmann wrote:
>
>> [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.
> This is my opinion for a low-level API, which 1:1 maps LDAP
> terminology to the Java API. I think we should additional have a
> simplified API where the user don't need to deal with request and
> response objects at all.
>
> BTW: We have this discussion again and again ;-) We really need to
> decide a consistent naming.
I think we already discussed it more than once, and we all agreed on
this convention.
I'm not sure we want to rehash this again every 2 years :/
--
Regards,
Cordialement,
Emmanuel Lécharny
www.iktek.com
Re: [Shared] API Design Questionnaire #1
Posted by Stefan Seelmann <se...@apache.org>.
On Fri, Jan 28, 2011 at 5:58 PM, Alex Karasulu <ak...@apache.org> 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
I think the extra methods makes it much easier to construct a
ModifyRequest, one line of code instead of three lines:
ModifyRequest request = ...;
request.replace("mail", "value1", "value2", "value3");
is equivalent to
ModifyRequest request = ...;
EntryAttribute attribute = new DefaultEntryAttribute(("mail",
"value1", "value2", "value3");
Modification mod = new
DefaultModification(ModificationOperation.REPLACE, attribute);
request.addModification(mod);
IMO those are very close to LDIF syntax, I like them.
But it makes sense to rename the methods:
- remove -> addRemoveModification
- add -> addAddModification
- replace -> addReplaceModification
Additional those methods should return the created Modification object.
At last we may remove the "addModification()" methods.
> (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.
>
> [ ] - (a)
> interface = *I*AddRequest
> simple API exposed implementation = AddRequest
> not so simple internal use implementation = AddRequest*Decoder*
> [ ] - (b)
> interface = AddRequest
> simple API exposed implementation = *Simple*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*
> [ ] - (d)
> interface = AddRequest
> simple API exposed implementation = *Basic*AddRequest
> not so simple internal use implementation = AddRequest*Decoder*
>
> [ ] - (e) I pick the fat lady with the pink tutu ....
>
> 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.
This is my opinion for a low-level API, which 1:1 maps LDAP
terminology to the Java API. I think we should additional have a
simplified API where the user don't need to deal with request and
response objects at all.
BTW: We have this discussion again and again ;-) We really need to
decide a consistent naming.
> (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.
>
> 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**
I see you already removed the methods, sorry for not responding in time...
Kind Regards,
Stefan
Re: [Shared] API Design Questionnaire #1
Posted by Emmanuel Lecharny <el...@gmail.com>.
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**
--
Regards,
Cordialement,
Emmanuel Lécharny
www.iktek.com