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

[Rob Weltman <robw@wigwamlab.com>]

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


hahnt@us.ibm.com 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".
> 
> 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: hahnt@us.ibm.com
> Internal: Timothy Hahn/Endicott/IBM@IBMUS or IBMUSM00(HAHNT)
> phone: 607.752.6388     tie-line: 8/852.6388
> fax: 607.752.3681