Java LDAP API issues summary - round 2

[Rob Weltman <robw@worldspot.com>]

  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.

3. LDAPSearchResultReference.getURLs() -> LDAPSearchResultReference.getReferrals()

  Also, it returns an array of String, not an array of LDAPUrl.

4. Add overloaded bind method to LDAPBind:

 LDAPConnection bind( String ldapurl, LDAPConnection origConn );

5. LDAPSearchListener and LDAPResponseListener implement a new interface: LDAPListener, with methods getMessageIDs(), getResponse(), isResponseReceived(), and merge().

6. Add overloaded LDAPConnection.abandon signature which takes an LDAPConstraints argument (to allow passing a control)

7. Add method to LDAPConnection to get the properties Hashtable (if any) that was used on a SASL bind

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".

9. Clarification in 4.3.8: removing "cn" from and LDAPAttributeSet does not remove "cn;lang-en".

10. LDAPSearchListener

  Add methods isResponseReceived() and isComplete( int msgid ).

11. LDAPMessage

  Add method getResponse( int msgid )

12. Names of constants for LDAP result codes

  Indicate the mapping to ASN.1 names in RFC 2251

13. Section 4.31.3

  LDAP_DEREF_NEVER  should be LDAPConnection.DEREF_NEVER
  LDAP_DEREF_FINDING should be LDAPConnection.DEREF_FINDING
  LDAP_DEREF_SEARCHING should be LDAPConnection.DEREF_SEARCHING
  LDAP_DEREF_ALWAYS should be LDAPConnection.DEREF_ALWAYS

14. LDAPConstraints.setHopLimit

  Clarify that 0 means no limit

15. Typos in constant values

  LDAPConnection.DEREF_SEARCHING should be 1, LDAPConnection.DEREF_FINDING should be 2