Subject: Java LDAP API issues summary - round 2

From: Rob Weltman <[email-masked]>
Date: Sun, 08 Oct 2000 21:31:39 -0700

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

---

From: Steven Sonntag <[email-masked]>
Date: Mon, 09 Oct 2000 14:01:38 -0600

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

---

From: Rob Weltman <[email-masked]>
Date: Mon, 09 Oct 2000 18:26:17 -0700

> not be associated with constraints.

  The draft currently defines the following global options for LDAPConnection.setOption:

and the following per-instance options:
LDAPConnection.DEREF
LDAPConnection.SIZELIMIT

---

From: Rob Weltman <[email-masked]>
Date: Mon, 09 Oct 2000 18:33:29 -0700

> not be associated with constraints.

  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

---

From: Steven Sonntag <[email-masked]>
Date: Wed, 11 Oct 2000 11:44:35 -0600

--- snip ---

>   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 ad…

I'm just curious why STRING_FORMAT is possily  global.  If I understand this API correctly
an application could choose to get all data in T.61 format whether or not the connection is V2 or V3.

Is it global because an application will probably deal only with one character set, or because of of something
intrinsic to the connection itself.

-Steve

--
------------------------
Steve Sonntag
Novell, Inc., the leading provider of Net services software

---

From: Rob Weltman <[email-masked]>
Date: Wed, 11 Oct 2000 11:35:16 -0700

> intrinsic to the connection itself.

  It doesn't need to be global to the connection, but the purpose of the API was to accomodate the wide range of character set encoding behavior of current LDAP servers. While the correct behavior is to return T.61 to an LDAPv2 client and UTF8 to an LDAPv3 client, some servers always return UTF8 (or do no conversion
at all, just returning whatever was stored - which might be T.61 or UTF8). For this purpose, it makes sense to set the format once after a connection has been established (and the client knows what type of server it's talking to) for all threads or objects sharing the same physical connection.

Rob