Re: Java LDAP API issues summary - round 2

[Rob Weltman <robw@worldspot.com>]

Steven Sonntag wrote:
> 
> Rob Weltman wrote:
> 
> >   This is an attempt to summarize all issues discussed since my summary to the list on 9/24 this year.
> >
> > Rob
> >
> > 1. LDAPConnection.setOption/LDAPConnection.getOption
> >
> >   I think Steve proposed eliminating it (since its functionality can be expressed with LDAPConstraints.setSearchConstraints). The only problem I have with that is that we distinguish between objects sharing the same physical connection (ones created with LDAPConnection.clone) and each having its own configuration, on the one hand, and configuration settings which globally affect all such objects on the other hand. All the settings in LDAPConstraints and LDAPSearchConstraints are private to each object, while some of the settings in setOption are global. Including global settings in LDAPConstraints and LDAPSearchConstraints may be confusing for a programmer using this API.
> >
> > 2. Getting the protocol level of the connection
> >
> >   If we keep LDAPConnection.getOption, it should be there (since it is global to the physical connection); that is how it is implemented in the Mozilla SDK.
> >
> >   If we eliminate LDAPConnection.getOption and include global settings in the constraints object, then the protocol level accessor will need to be moved to LDAPConstraints.
> >
> 
> ---snip---
> 
> >
> >
> > 8. Change wording in 4.35.5 from "The returned value may be an LDAPEntry or an LDAPReferralException" to "The returned value may be an LDAPEntry or an LDAPException".
> >
> 
> I am not sure from your e-mail what you intend to do here.  I do agree that it is confusing to have global
> data in the constraints object.  IMO global data like protocol level or hashTable should NOT be in the
> constraints object.  They should be in data common to all the clones of a connection.
> 
> Right now  LDAPConnections supports separate APIs for setting / getting data that is global to the connection, viz.
> authenticationMethod
> authenticationDN
> authenticationPasswd
> host
> port
> inputStream
> outputStream
> property
> connected
> bound
> socketFactory
> 
> The hashTable and protocol level also belong in this category.
> 
> Are you suggesting that all options relating to constraints data be removed from the
> get/getOption API?  I agree that is a good idea.
> 
> Are you suggesting that options relating to global data be retained or added
> to set/getOption?  I am not sure that is a good idea.  It means that if the data type
> passed to setOption is wrong, it would not be caught at compile time, but via
> a RuntimeException.  Personally I would rather see a compile error.  On the
> otherhand, the get/set methods for the above now become an instance of get/setOption,
> simplifying the API and reducing the number of methods in LDAPConnection, but in
> its place multiplying variations of LDAPSetOption.
> 
> Currently level and hashTable are set via the appropriate connect or bind method.  This
> implies that only get methods are needed as the values are effectively read-only or informational
> after the connect / bind calls are complete.
> 
> My vote is to add two get methods, one for protocol level, and one for hashTable.  These should
> not be associated with constraints.
> 
> -Steve

  I guess the draft doesn't define any global options for LDAPConnection.setOption, except for possibly:

LDAPConnection.STRING_FORMAT

The others are all per-instance options:

LDAPConnection.DEREF
LDAPConnection.SIZELIMIT
LDAPConnection.SERVER_TIMELIMIT
LDAPConnection.TIMELIMIT
LDAPConnection.REFERRALS
LDAPConnection.REFERRALS_REBIND_PROC
LDAPConnection.BIND
LDAPConnection.REFERRALS_HOP_LIMIT
LDAPConnection.BATCHSIZE

  All the per-instance options can be eliminated immediately in favor of setConstraints/setSearchConstraints. And with nothing left (except possibly STRING_FORMAT), I agree that we can afford to add the two suggested additional methods to get the bound protocol level and the properties Hashtable used on binding.


Rob