Subject: comments on draft-ietf-ldapext-ldap-java-api-11.txt

From: [email-masked]
Date: Thu, 21 Sep 2000 11:36:36 -0400

Greetings,

I finally got around to reading this draft.  It looks great so far.  I've 
summarized my comments here:

Section 4.3.5:
--------------
"cn;lang-ja-JP-kanji" may be a subtype of "cn;lang-ja" - based on recent 
discussions on this list, I don't think that this is true.  It seems to me 
that "cn;lang-ja-JP-kanji" is really treated as a subtype of "cn".

similarly, I think the example in this section need fixing as well:

getAttribute( "cn", "lang-en-us" ); does NOT return "cn;lang-en"

getAttribute( "sn", "lang-en" ); does NOT return "sn"

formating for description of "attrName" should be fixed.

Section 4.3.8:
--------------
Are attribute descriptions and attribute subtypes accounted for in this? 
For example, will a:

attrSet.remove("name");

call result in all "cn", "sn", "cn;lang-us" attributes being removed from 
the LDAPAttributeSet?

Section 4.5.1:
--------------
Are alternative attribute type names, attribute subtypes, and attribute 
descriptions accounted for in this comparison implemenatation?

Section 4.5.4:
--------------
If an entry does not contain an attribute, is it considered greater than 
or less than an entry that does contain the attribute?

Section 4.6.4:
--------------
If the authentication method does not have an associated distinguished 
name, does this method return null?  An exception?

Section 4.6.17, 4.6.18:
-----------------------
Is a bind() done as well?  If so, what method is used?  Is this controlled 
by the LDAPSearchConstraints object that is passed in?

Section 4.7.1:
--------------
Maybe this was covered in previous discussions on this list.  It is not 
clear from the draft, however, what the subtle differences are between a 
LDAPBind and LDAPRebind class and where these differences are used.

Section 4.7.8:
--------------
A clarification: If the bind proc is null (the default), then no 
authentication is done on the initial connection.

Section 4.11.1:
---------------
"after appropriate normalization".  Doesn't this imply that the CLIENT 
have full knowledge of the "active" schema?  More clarification as to the 
extent of normalization that will be done is needed here.  Full DN 
handling is actually quite complex.  If that is what is intended here, 
then it needs to be made clear.  Further, this could require some form of 
communication with an LDAP server to get a set of "schema" with which to 
work with.

Section 4.11.4, 4.11.5:
-----------------------
Will the values returned be appropriately escaped or un-escaped based on 
the escaping rules in RFC 2253?

Section 4.12.4 (and many others, including all of 4.29, 4.38, 4.39, 4.40):
--------------------------------------------------------------------------
Why is a "String dn" returned/passed in and not a LDAPDN when a 
distinguished name is to be used?

Section 4.16.5:
---------------
Are the constants referred to here for result codes defined as static 
constants anywhere?  I did not see them defined as such anywhere in this 
draft.  This could possibly be done in LDAPException as:

class LDAPException {
...
public static final int NO_SUCH_OBJECT = 1;
...
}

Section 4.21:
-------------
Since this set of modifications is ordered, should it be called 
LDAPModificationList instead?

Section 4.21.2:
---------------
A clarification.  Since the list is ordered, add() should clarify that it 
adds at the END of the list.

Section 4.21.4:
---------------
This is similar to the comment above on Section 4.3.8, are subtypes, 
attribute descriptions, and alternate attribute type names accounted for 
here?

Section 4.24 and 4.25:
----------------------
The setup of LDAPRebindAuth and LDAPRebind seem only to support the notion 
of "simple" authentication.  How are other authentication methods to be 
setup and used when following referrals?

Section 4.26.1:
---------------
Clarification: the full response is received prior to throwing the 
referral exception, correct?

Section 4.29.11:
----------------
"of attribute definitions" should be "of LDAPAttributeSchema definitions".

Section 4.29.12:
----------------
"of attribute definitions" should be "of LDAPObjectClassSchema 
definitions".

Section 4.29.13:
----------------
"of attribute definitions" should be "of LDAPMatchingRuleSchema 
definitions".

Section 4.29.20-25:
-------------------
clarification: the returned Enumeration is an Enumeration of Strings, 
correct?

Section 4.30.1-3:
-----------------
I would prefer that these methods NOT be defined in the abstract base 
class.  They don't make sense for some derived classes.  This was alluded 
to later in the document (Section 4.37).

Section 4.30.6:
---------------
clarification: the returned Enumeration is an Enumeration of Strings, 
correct?

Section 4.30.10,11,12:
----------------------
These should clarify what LDAP operations are being performed.  I think 
that 4.30.10 is an LDAP MODIFY where a new attribute value is added to the 
existing attributetypes, objectclasses, ldapsyntaxes, or matchingrules 
attribute in the subschemasubentry, 4.30.11 is a LDAP MODIFY operation to 
delete a specific attribute value, and 4.30.12 is an LDAP MODIFY with a 
"delete value" + "add value" in the ModificationSet/List.  This should be 
described in these sections.

Section 4.30.12:
----------------
Also in this section, the value from "this.getValue()" is used as the 
"attribute value to delete", correct?

Section 4.31.1:
---------------
Why is doReferrals set to "false" by default?

non-SIMPLE re-bind authentication seems to need more thought, in general. 
Is anybody working on this?

Is hop_limit set to zero by default?  Does zero imply no limit?

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

Section 4.32.1:
---------------
What is meant by "outstanding requests"?  Is this the set of responses 
that have not yet been completely received from the remote server?  Or the 
set of responses that have not been "received" by the application?  Or 
both?

Section 4.32.3:
---------------
Would it be useful to have a "isReponseReceived( int msgid )" method as 
well?

How about an "isComplete( int msgid )"?

Section 4.35.5:
---------------
"This the" should be "This is the"

"or an LDAPReferralException." should be "or an LDAPReferralException is 
thrown."

Should there be a way to get the referrals FIRST (i.e. not at the end as 
an exception), so that other searches can be started in the background? 
This would allow multiple outstanding searches to multiple servers to run 
in parallel instead of serializing referrals chasing.

Section 4.38.1:
---------------
attrNames description, "null for all attributes".  Should this be "null or 
a single value of "*" for all attributes".

Section 4.39.13:
----------------
Description of LDAPConnection.REFERRALS_HOP_LIMIT.  Change "no more than 5 
referrals in a row" to "no more than 5 nested referrals."

Section 4.40.1:
---------------
Will the client send off abandon requests for all outstanding (but 
incomplete) operations if a bind() is invoked?

Thanks,
Tim Hahn

Internet: [email-masked]
Internal: Timothy Hahn/Endicott/IBM@IBMUS or IBMUSM00(HAHNT)
phone: 607.752.6388     tie-line: 8/852.6388
fax: 607.752.3681

---

From: "Kurt D. Zeilenga" <[email-masked]>
Date: Thu, 21 Sep 2000 09:03:32 -0700

At 11:36 AM 9/21/00 -0400, [email-masked] wrote:
>Section 4.3.5: 
>-------------- 
>"cn;lang-ja-JP-kanji" may be a subtype of "cn;lang-ja" - based on recent discussions on this list,

Language tags have no structure, "cn;lang-ja" and "cn;lang-ja-JP-kanji"
are siblings of "cn" attribute type.

> I don't think that this is true.  It seems to me that "cn;lang-ja-JP-kanji" is really treated as a subtype of "cn". 

Correct.  I think the latest lang tag discussion is more whether
"cn;lang-ja;lang-ja-JP-kanji" is treated as a direct subtype of "cn"
or is treaded as subtypes of both "cn;lang-ja" and "cn;lang-ja-JP-kanji"
(which are subtypes of "cn").

---

From: Rob Weltman <[email-masked]>
Date: Thu, 21 Sep 2000 09:53:56 -0700

Tim,

  I'll comment on the other things along with all the messages from
Steve soon, but here just a comment on the language subtype APIs.

  They were designed after a study of application usage of localized
attribute values, with the intent of best supporting such applications,
not of reflecting the LDAP protocol representation of language subtypes.
There is no need for the latter, since a client can request "cn" or
"cn;lang-ja" or "cn;lang-ja-JP-kanji" and will receive the results
dictated by LDAPv3.

  The usage model found in applications was that they wanted to access
the attribute value that was most specific to the requesting client, if
available, and to fall back to more general values if not. For a given
user entry, there might be a dozen attributes with a single value (no
language subtype), and five or less with different representations for
different locales. The application wants to pass in all locale
information that is available for the requesting client to the SDK, and
to receive from the SDK the most appropriate values for each of the
attributes of the entry. For example, the application might request
";lang-ja-JP-kanji" for all attributes of the entry; those attributes
that have that subtype will return them, while those that do not contain
that subtype but do contain ";lang-ja" will return ";lang-ja" values,
and those that contain no subtypes will return the base values.

  The alternative to this hierarchical model is that applications are
forced to either create duplicate attribute values (i.e. create subtyped
attributes even where the values are identical to those of the base
attributes) or to do the subtype analysis themselves.

Rob

[email-masked] wrote:
> 
> Greetings,
> 
> I finally got around to reading this draft.  It looks great so far.
>  I've summarized my comments here:
> 
> Section 4.3.5:
> --------------
> "cn;lang-ja-JP-kanji" may be a subtype of "cn;lang-ja" - based on
> recent discussions on this list, I don't think that this is true.  It
> seems to me that "cn;lang-ja-JP-kanji" is really treated as a subtype
> of "cn".
> 
> Are attribute descriptions and attribute subtypes accounted for in
> this?  For example, will a:
> 
> attrSet.remove("name");
> 
> call result in all "cn", "sn", "cn;lang-us" attributes being removed
> from the LDAPAttributeSet?
> 
> Section 4.5.1:
> --------------
> Are alternative attribute type names, attribute subtypes, and
> attribute descriptions accounted for in this comparison
> implemenatation?
> 
> Section 4.5.4:
> --------------
> If an entry does not contain an attribute, is it considered greater
> than or less than an entry that does contain the attribute?
> 
> Section 4.6.4:
> --------------
> Is a bind() done as well?  If so, what method is used?  Is this
> controlled by the LDAPSearchConstraints object that is passed in?
> 
> Section 4.7.1:
> --------------
> Maybe this was covered in previous discussions on this list.  It is
> not clear from the draft, however, what the subtle differences are
> between a LDAPBind and LDAPRebind class and where these differences
> are used.
> 
> Section 4.7.8:
> --------------
> have full knowledge of the "active" schema?  More clarification as to
> the extent of normalization that will be done is needed here.  Full DN
> then it needs to be made clear.  Further, this could require some form
> of communication with an LDAP server to get a set of "schema" with
> which to work with.
> 
> Section 4.11.4, 4.11.5:
> -----------------------
> Will the values returned be appropriately escaped or un-escaped based
> on the escaping rules in RFC 2253?
> 
> constants anywhere?  I did not see them defined as such anywhere in
> this draft.  This could possibly be done in LDAPException as:
> 
> class LDAPException {
> ...
> A clarification.  Since the list is ordered, add() should clarify that
> it adds at the END of the list.
> 
> Section 4.21.4:
> ---------------
> attribute descriptions, and alternate attribute type names accounted
> for here?
> 
> Section 4.24 and 4.25:
> ----------------------
> The setup of LDAPRebindAuth and LDAPRebind seem only to support the
> notion of "simple" authentication.  How are other authentication
> methods to be setup and used when following referrals?
> 
> Section 4.26.1:
> ---------------
> class.  They don't make sense for some derived classes.  This was
> alluded to later in the document (Section 4.37).
> 
> Section 4.30.6:
> ---------------
> These should clarify what LDAP operations are being performed.  I
> think that 4.30.10 is an LDAP MODIFY where a new attribute value is
> added to the existing attributetypes, objectclasses, ldapsyntaxes, or
> matchingrules attribute in the subschemasubentry, 4.30.11 is a LDAP
> MODIFY operation to delete a specific attribute value, and 4.30.12 is
> an LDAP MODIFY with a "delete value" + "add value" in the
> ModificationSet/List.  This should be described in these sections.
> 
> Section 4.30.12:
> ----------------
> non-SIMPLE re-bind authentication seems to need more thought, in
> general.  Is anybody working on this?
> 
> that have not yet been completely received from the remote server?  Or
> the set of responses that have not been "received" by the application?
>  Or both?
> 
> Section 4.32.3:
> ---------------
> Would it be useful to have a "isReponseReceived( int msgid )" method
> as well?
> 
> "or an LDAPReferralException." should be "or an LDAPReferralException
> is thrown."
> 
> Should there be a way to get the referrals FIRST (i.e. not at the end
> as an exception), so that other searches can be started in the
> background?  This would allow multiple outstanding searches to
> multiple servers to run in parallel instead of serializing referrals
> chasing.
> 
> Section 4.38.1:
> ---------------
> attrNames description, "null for all attributes".  Should this be
> "null or a single value of "*" for all attributes".
> 
> Section 4.39.13:
> ----------------
> Description of LDAPConnection.REFERRALS_HOP_LIMIT.  Change "no more
> than 5 referrals in a row" to "no more than 5 nested referrals."
> 
> Section 4.40.1:
> ---------------