You are viewing a plain text version of this content. The canonical link for it is here.
Posted to api@directory.apache.org by Emmanuel Lecharny <el...@apache.org> on 2009/11/24 16:53:07 UTC
Let's start for real ?
Hi guys,
what about starting for real to work on this common API ? We have had
many preliminary discussions, and also have done a common presentation
with Ludovic 2 months ago. I was pretty busy since then, but right now,
the urgency to get a clean API is getting higher.
We have already clarified what a common API should be about. I suggest
we start by defining the names we want to use for the base objects.
There are a few which are really genuine to ldap, namely, DN, RDN, AVA,
Entry, Attribute, Modification, Control, LdapURL, AttributeType,
DitContentRule, DitStructureRule, MatchingRule, MatchingRuleUse,
NameForm, ObjectClass, Syntax, ResultCode, OID and CSN.
i'm not sure I have listed all the base objects, so feel free to add
those you think are missing.
Also those names are not the final ones. The idea is to discuss about
the exact names we will use. For instance, DN is not necessarily the
most common form. Many APIs or implementations are using LdapDn or
LdapDN. Assuming that the Java naming convention requires that the first
letter only to be upcased, one can think that Dn or Rdn is a better name.
Please feel free to give your opinion.
<Emmanuel's option>
DN : I would rather use Dn
RDN : Same her, Rdn sounds better to me
AVA : idem, Ava
Entry : fine
Attribute : fine, except that it collides with JNDI attributes, making
the JNDI -> new API translation cumbersome. EntryAttribute ?
Modification : Fine
Control : Fine
LdapURL : LdapUrl has my preference
AttributeType : Fine
DitContentRule : Fine
DitStructureRule : Fine
MatchingRule : Fine
MatchingRuleUse : Fine
NameForm : Fine
ObjectClass : Fine
Syntax : Fine, or LdapSyntax
ResultCode : Fine
OID: Oid for me
CSN: Csn again, same reason
--
--
cordialement, regards,
Emmanuel Lécharny
www.iktek.com
directory.apache.org
Re: Let's start for real ?
Posted by Matthew Swift <Ma...@Sun.COM>.
On 27/11/09 11:18, Emmanuel Lecharny wrote:
>> Anyway, we can cross this bridge when we come to it. I don't think that it's
>> a priority now.
>>
> Absolutely.
>
> In fact, to be frank, the reason I mentionned this problem is because
> we had a full JNDI layer built into ADS, and we ditched it last year.
> The problem was that it was not easy to ditch it cimpletely, as the
> external interface was still JNDI, and I had to write the converters,
> which was a PITA.
>
> Now, considering what is doing UnboundId, ie a JNDI layer on top of
> their API, at some point, we may need to design a SPI based on our
> API. But again, everything will be buried in the code, and it's not a
> big deal.
>
> So +1 to keep Attribute.
>
>
> PS : I will create a Wiki page where we will be able to define the API
> and comment it, so that we can converge at some point.
>
Cool - send out the link to it when it's available.
Matt
Re: Let's start for real ?
Posted by Emmanuel Lecharny <el...@apache.org>.
> Anyway, we can cross this bridge when we come to it. I don't think that it's
> a priority now.
Absolutely.
In fact, to be frank, the reason I mentionned this problem is because
we had a full JNDI layer built into ADS, and we ditched it last year.
The problem was that it was not easy to ditch it cimpletely, as the
external interface was still JNDI, and I had to write the converters,
which was a PITA.
Now, considering what is doing UnboundId, ie a JNDI layer on top of
their API, at some point, we may need to design a SPI based on our
API. But again, everything will be buried in the code, and it's not a
big deal.
So +1 to keep Attribute.
PS : I will create a Wiki page where we will be able to define the API
and comment it, so that we can converge at some point.
--
Regards,
Cordialement,
Emmanuel Lécharny
www.iktek.com
Re: Let's start for real ?
Posted by Matthew Swift <Ma...@Sun.COM>.
> On 27/11/2009 10:05, Emmanuel Lecharny wrote:
>> Sure, as much as possible. This is why we picked LdapDn instead of DN,
>> and such names. I just have an issue with Attribute, because if we
>> want to write a wrapper around JNDI, it will end with ugly package
>> bnames to be added in the code to avoid confusion between Attribute
>> (jndi) and Attribute (API)...
>
> I don't think we should sacrifice the general public API
> cleanness/homogeneity for the specific JNDI wrapper case.
>
100% agree.
> What we should be looking for is to have the best, cleanest LDAP API -
> in the long term, it is the only one that matters.
>
> And for the confusion, well I don't think
> javax.naming.directory.Attribute brings much of it :)
>
A couple of other points regarding JNDI interop:
* A conversion layer may have to deal with ugly name clashes, but
this will not usually result in application code having to deal
with those clashes by using package names everywhere. E.g.
// SDK Entry
Entry e = ...;
// JNDI Attribute
Attribute a = ....;
// No name pollution required here:
e.addAttribute(JNDIAdapter.newSDKAttribute(a));
* Personally, I'm not 100% convinced of the advantages of such a
conversion layer since it implies that an application will contain
a mixture of legacy API (e.g. JNDI) code and new SDK code. Another
option is to provide a JNDI LdapContext implementation which uses
the new SDK. Then there's no need to change any legacy code - just
use the new LdapContext.
Anyway, we can cross this bridge when we come to it. I don't think that
it's a priority now.
Matt
Re: Let's start for real ?
Posted by Francois <fa...@gmail.com>.
On 27/11/2009 10:26, Emmanuel Lecharny wrote:
> It's just that I don't like to see packages in the code...
>
> But it may be just me :)
Stand reassure, neither I do.
But as Java doesn't have local name alias of imported type[1], I think
we have to deal with them as a "less bad" alternative compared to a less
clean API.
[1]
http://scala.sygneca.com/faqs/language#how-do-i-import
--
Francois ARMAND
http://fanf42.blogspot.com
Re: Let's start for real ?
Posted by Emmanuel Lecharny <el...@apache.org>.
On Fri, Nov 27, 2009 at 10:24 AM, Francois <fa...@gmail.com> wrote:
> On 27/11/2009 10:05, Emmanuel Lecharny wrote:
>>
>> Sure, as much as possible. This is why we picked LdapDn instead of DN,
>> and such names. I just have an issue with Attribute, because if we
>> want to write a wrapper around JNDI, it will end with ugly package
>> bnames to be added in the code to avoid confusion between Attribute
>> (jndi) and Attribute (API)...
>
> I don't think we should sacrifice the general public API
> cleanness/homogeneity for the specific JNDI wrapper case.
>
> What we should be looking for is to have the best, cleanest LDAP API - in
> the long term, it is the only one that matters.
You are probably right.
> And for the confusion, well I don't think javax.naming.directory.Attribute
> brings much of it :)
It's just that I don't like to see packages in the code...
But it may be just me :)
--
Regards,
Cordialement,
Emmanuel Lécharny
www.iktek.com
Re: Let's start for real ?
Posted by Francois <fa...@gmail.com>.
On 27/11/2009 10:05, Emmanuel Lecharny wrote:
> Sure, as much as possible. This is why we picked LdapDn instead of DN,
> and such names. I just have an issue with Attribute, because if we
> want to write a wrapper around JNDI, it will end with ugly package
> bnames to be added in the code to avoid confusion between Attribute
> (jndi) and Attribute (API)...
I don't think we should sacrifice the general public API
cleanness/homogeneity for the specific JNDI wrapper case.
What we should be looking for is to have the best, cleanest LDAP API -
in the long term, it is the only one that matters.
And for the confusion, well I don't think
javax.naming.directory.Attribute brings much of it :)
--
Francois ARMAND
http://fanf42.blogspot.com
Re: Let's start for real ?
Posted by Emmanuel Lecharny <el...@apache.org>.
On Fri, Nov 27, 2009 at 9:56 AM, Ludovic Poitou <Lu...@sun.com> wrote:
> Sorry for the delayed answer.
> Matt wasn't subscribed to the list (I think it's done now), and I'm out of the office for a conference.
> We will be back in the office on Monday and will give some answer (unless Matt beats me with it).
> Overall I do think we should try to match the names (and case) used in the RFC.
Sure, as much as possible. This is why we picked LdapDn instead of DN,
and such names. I just have an issue with Attribute, because if we
want to write a wrapper around JNDI, it will end with ugly package
bnames to be added in the code to avoid confusion between Attribute
(jndi) and Attribute (API)...
PS : Does Matt received my mail ? Or should I resubmit it to the list ?
--
Regards,
Cordialement,
Emmanuel Lécharny
www.iktek.com
Re: Let's start for real ?
Posted by Emmanuel Lecharny <el...@apache.org>.
On Fri, Nov 27, 2009 at 11:23 AM, Matthew Swift <Ma...@sun.com> wrote:
> Hi Emmanuel
>
>> Also those names are not the final ones. The idea is to discuss about
>> the exact names we will use. For instance, DN is not necessarily the
>> most common form. Many APIs or implementations are using LdapDn or
>> LdapDN. Assuming that the Java naming convention requires that the first
>> letter only to be upcased, one can think that Dn or Rdn is a better name.
>>
>
>
> I think that this convention applies to words in Java names, and not
> necessarily abbreviations such as DN. In fact a cursory look through the
> JDK6/J2EE6 APIs will reveal that there is definitely no convention! Take a
> look at javax.xml.* where they seem to mix XML/Xml and HTTP/Http and various
> other well known abbreviations with gay abandon :-)
>
> My personal preference and our convention here has been to use uppercase for
> abbreviations, but I don't feel so strongly to let such a detail get in the
> way of progress.
>
> I think that the most important things to focus on are to make the SDK easy
> to learn and easy to use and that means keeping it small, clean, and
> consistent.
Totally agree. As soon as we have a convenient naming that mostly fits
everyone (religoious war appart), let's move on.
I just have preferences, which may just be bad taste anyways...
--
Regards,
Cordialement,
Emmanuel Lécharny
www.iktek.com
Re: Let's start for real ?
Posted by Matthew Swift <Ma...@Sun.COM>.
Hi Emmanuel
> Also those names are not the final ones. The idea is to discuss about
> the exact names we will use. For instance, DN is not necessarily the
> most common form. Many APIs or implementations are using LdapDn or
> LdapDN. Assuming that the Java naming convention requires that the first
> letter only to be upcased, one can think that Dn or Rdn is a better name.
>
I think that this convention applies to words in Java names, and not
necessarily abbreviations such as DN. In fact a cursory look through the
JDK6/J2EE6 APIs will reveal that there is definitely no convention! Take
a look at javax.xml.* where they seem to mix XML/Xml and HTTP/Http and
various other well known abbreviations with gay abandon :-)
My personal preference and our convention here has been to use uppercase
for abbreviations, but I don't feel so strongly to let such a detail get
in the way of progress.
I think that the most important things to focus on are to make the SDK
easy to learn and easy to use and that means keeping it small, clean,
and consistent.
Matt
Re: Let's start for real ?
Posted by Matthew Swift <Ma...@Sun.COM>.
Hi Emmanuel,
I've put my responses inline..
On 27/11/09 12:42, Emmanuel Lecharny wrote:
> Ok, so we can start with :
>
> DN
> RDN
> AVA
> Entry
> Attribute
> Modification
> Control
> AttributeType
> DitContentRule
> DitStructureRule
> MatchingRule
> MatchingRuleUse
> NameForm
> ObjectClass
> Syntax
> ResultCode
>
> Still to be decided :
> LdapURL or LdapUrl ? I'm fine with both, but I don't like LDAPURL
>
I think LdapURL.
BTW, in our current SDK effort we have AVA as an inner class of RDN in
order to make it clearer to users of the tight coupling between the two.
In particular, an AVA is not the same sort of AVA that you'd find in a
compare operation or in a filter since it does not permit attribute
options and, perhaps more subtly, the "value" should not conform to the
matching rule assertion syntax, but to the attribute syntax (which is
usually the same anyway for equality matching rules, but it's worth
pointing out).
> OID: It's much more a ASN.1 notion, right. But in many case, we may
> manipulate an OID instead of a String. Frankly, the only thing I do
> with such a class right now is to use a static method named OID.isOid(
> String ). It can be left outside of the API too.
>
> CSN: Or EntryCSN. Not sure that it should be exposed too.
>
>
>> A data type that we have found particularly useful is AttributeDescription
>>
> <snip/>
>
> If this is a wrapper on top of an AttributeType (or an ID), with
> options, then it sounds like a good idea. It could help having a
> lightweight API instead of having tens of methods for each specific
> case : AT with options, etc.
>
>
Agreed - in our server we don't have an AttributeDescription API and
instead we have many methods of the form that you describe, e.g:
Entry.getAttribute(AttributeType type)
Entry.getAttribute(AttributeType type, String... options)
Entry.getAttribute(AttributeType type, Set<String> options)
It gets pretty bloated once you add in methods for removing attributes
and checking for containment, etc. Another nice thing about having an
AttributeDescription type is that you can cache them in ThreadLocals for
very faster decoding and reduction in memory throughput.
>
>> We don't require that the client API has a schema available. The default
>> schema can be either the built in standard "core" schema (e.g. cn, sn, etc)
>> or it could even be the built in "empty" schema, both of which fake up
>> missing attribute type definitions on demand (in which case they use octet
>> string syntax and equality matching). This is nice because it means that the
>> API does not need get bloated by having two API abstractions (non schema
>> aware and schema aware).
>>
> We discussed a lot with Ludo about it. The Client API must not be
> schema aware, but it must allow someone to use a schema if needed. The
> default would be to use the core schema.
>
>
Agreed.
> In order to use the Schema within an entry, it would just be a matter
> of injecting the Schema into the Entry, either in the constructor, or
> later. It will of course propagate to all the included AT, Dn, etc...
> The details have to be explicited, of course
>
>
In our SDK I have made the following two assumptions with the aim of
keeping the API as lean as possible:
* most client application developers will only use a single LDAP schema
* if an application requires multiple schema then it's probably
acceptable to force them to use more "heavy weight" methods
This means that high-level API components such as Entry and Attribute
(but not DN or AttributeDescription which IMO are low level) do not
provide a means for specifying a schema during construction. Instead
they use the application default schema. Developers still get the
flexibility to use non-default schema by using the more heavy weight API
methods. Here's some examples:
// Use application default schema to decode attribute descriptions
and DNs.
Attribute a1 = new LinkedAttribute("description", "value1",
"value2", "value3");
a1.add("another value");
Entry e1 = new SortedEntry("dc=example,dc=com");
e1.addAttribute("description", "value1", "value2", "value3");
e1.addAttribute("dc", "example");
// Now more heavyweight approach using alternative schema.
Schema schema = ...;
AttributeDescription ad =
AttributeDescription.valueOf("description", schema);
Attribute a2 = new LinkedAttribute(ad, "value1", "value2", "value3");
// It is possible, though not advisable, to use both approaches for
Entries.
DN dn = DN.valueOf("dc=example,dc=com", schema);
Entry e2 = new SortedEntry(dn);
e2.addAttribute("description", "value1", "value2", "value3");
e2.addAttribute(a2);
Like you say we could inject the schema when constructing the Entry -
it's only an additional constructor.
>
>> Here's some other types that you'll probably need:
>>
>> * Filter - this is the raw Filter structure defined in RFC 4511
>> protocol def. We also have a Matcher object (in the style of the
>> Regex APIs) which represents a Filter compiled against a
>> particular schema.
>>
> Filter, +1
>
> I'm not sure about the Matcher object, as it's supposed to be used by
> the server only. But who knows?
>
>
Yeah - I don't know. It could be useful when parsing and filtering LDIF
or doing client side entry filtering.
>> * Assertion - represents an attribute value assertion compiled by a
>> MatchingRule - typically these are stored in a compiled Filter
>> (Matcher)
>>
> Same as above...
>
Agreed.
>
>> * Schema - a container of attribute types, object classes, etc
>>
> We call it SchemaManager in ADS, Schema is definitively better. +1
>
>
>> * ByteString and/or AttributeValue - you'll need at the bear minimum
>> a ByteString for storing attribute values. You may decide that you
>> need an AttributeValue as well in order to cache the normalized
>> form, but I don't think that it's necessary and it just bloats the
>> API and memory - the Attribute can cache normalized forms.
>> Matching rules will need to normalize bytes. For such a low level
>> primitive it's best to use an immutable object for this. We also
>> have a ByteSequence and ByteStringBuilder in the same manner as
>> CharSequence, StringBuilder, and String.
>>
> Again, a lot of discussion about it. I'm not convinced that we really
> need a ByteString object, as data are either String or byte[], and
> String will be internally converted to byte[] (after a PrepareString
> normalization). The AttributeValue is what I called AVA (sticking to
> the RFC terminology). It makes sense to me to have such an object, as
> we have to keep the user provided value, and to have a normalized form
> of this value. Of course, you can cach such a value in the Attribute,
> but you will have to do the same thing for the RDNs.
>
> I would arther discuss those specific points on another thread to not
> confuse people.
>
OK.
>
>> * Search scope (needs to be extensible - i.e. not an enum)
>>
> So Scope or SearchScope ? Also, does it really have to be extensible ?
>
I think SearchScope - Scope seems a bit generic to me. I don't feel
strongly about this though.
The LDAP RFC specify several extension points. Two of them are the
search scope and modification type. I don't that we need to go overboard
supporting extensibility, but I think that it may be too limiting to use
a enums for these since they are inextensible (e.g. adding new values
could break switch statements in client apps). Also it might be the case
that certain applications are using their own custom scope/mod-type
which are out of our control. Therefore I think that it would be nice if
we supported the standard scopes and mod-types as constants but perhaps
allowed client apps to define their own on the fly. E.g:
SearchScope scope = SearchScope.SUBTREE;
// User defined value (we could allow the caller to pass in a
user-friendly name as well):
SearchScope scope = SearchScope.valueOf(4);
// But... what does this do? Should it evaluate to true?
if (SearchScope.valueOf(5) == SearchScope.valueOf(5)) {
// Same instance - enum like behavior.
}
For modification types I thought it might be cool to allow registration
of new types including a Strategy pattern call-back which can be used to
apply changes to an attribute.
public interface ModificationStrategy {
// Ignore exceptions for now for simplicity.
Attribute modifyAttribute(Attribute currentAttribute, Attribute
changes);
}
public final class ModificationType {
public static final ModificationType ADD = register(...);
public static final ModificationType DELETE = register(...);
public static final ModificationType REPLACE = register(...);
public static final ModificationType INCREMENT = register(...);
// Support registration of additional types.
public static void register(int type, String shortName,
ModificationStrategy strategy);
...
}
I think that this is probably more useful on the server side rather than
in a client API so I'm not going to push for this. However, I think that
we should allow clients to pass in arbitrary modification types in
modify requests. If we want elements of this API to be used on the
server side then I think that it's really important to support
user-defined scopes and mod-types since, if we do not, the LDAP server
will fail incoming operations during the request decode phase.
Result codes should definitely allow arbitrary values (i.e. not an enum)
since LDAP extended operations and controls can define their own.
>
>> * Modification type (needs to be extensible - i.e. not an enum)
>>
> Operation ? ModOp?
>
>
The protocol calls this field Operation, but I think that this is one of
those cases where we should ignore the RFC naming. In this case
Operation is way too generic - for a start basic LDAP request types are
referred to as Operations (add, delete, modify, modifyDN, search, etc).
In our server we've used Modification (RFC element
ModifyRequest.changes) and ModificationType (RFC element
ModifyRequest.changes.operation). In our prototype SDK we've used Change
instead of Modification and ModificationType as per the server. I was
probably smoking something that day since I haven't been consistent! ;-)
For consistency I should have stuck with Modification/ModificationType
or Change/ChangeType. However, the latter form could easily be confused
with an LDIF record change type.
So after all that verboseness, my preference is for
Modification/ModificationType. I prefer ModificationType because it is
clearly associated with the class Modification.
>> * Dereference aliases policy
>>
> Sure. Don't have a name in mind
>
>
We just use DereferenceAliasesPolicy. It's a bit long but it's rarely
used so developers rarely need to type it in.
>> * Condition result for filters (true, false, undefined)
>>
> Yup. A name ?
>
>
Err... we've been imaginative and used ConditionResult :-)
Matt
Re: Let's start for real ?
Posted by Emmanuel Lecharny <el...@apache.org>.
Ok, so we can start with :
DN
RDN
AVA
Entry
Attribute
Modification
Control
AttributeType
DitContentRule
DitStructureRule
MatchingRule
MatchingRuleUse
NameForm
ObjectClass
Syntax
ResultCode
Still to be decided :
LdapURL or LdapUrl ? I'm fine with both, but I don't like LDAPURL
OID: It's much more a ASN.1 notion, right. But in many case, we may
manipulate an OID instead of a String. Frankly, the only thing I do
with such a class right now is to use a static method named OID.isOid(
String ). It can be left outside of the API too.
CSN: Or EntryCSN. Not sure that it should be exposed too.
> A data type that we have found particularly useful is AttributeDescription
<snip/>
If this is a wrapper on top of an AttributeType (or an ID), with
options, then it sounds like a good idea. It could help having a
lightweight API instead of having tens of methods for each specific
case : AT with options, etc.
> We don't require that the client API has a schema available. The default
> schema can be either the built in standard "core" schema (e.g. cn, sn, etc)
> or it could even be the built in "empty" schema, both of which fake up
> missing attribute type definitions on demand (in which case they use octet
> string syntax and equality matching). This is nice because it means that the
> API does not need get bloated by having two API abstractions (non schema
> aware and schema aware).
We discussed a lot with Ludo about it. The Client API must not be
schema aware, but it must allow someone to use a schema if needed. The
default would be to use the core schema.
In order to use the Schema within an entry, it would just be a matter
of injecting the Schema into the Entry, either in the constructor, or
later. It will of course propagate to all the included AT, Dn, etc...
The details have to be explicited, of course
> Here's some other types that you'll probably need:
>
> * Filter - this is the raw Filter structure defined in RFC 4511
> protocol def. We also have a Matcher object (in the style of the
> Regex APIs) which represents a Filter compiled against a
> particular schema.
Filter, +1
I'm not sure about the Matcher object, as it's supposed to be used by
the server only. But who knows?
> * Assertion - represents an attribute value assertion compiled by a
> MatchingRule - typically these are stored in a compiled Filter
> (Matcher)
Same as above...
> * Schema - a container of attribute types, object classes, etc
We call it SchemaManager in ADS, Schema is definitively better. +1
> * ByteString and/or AttributeValue - you'll need at the bear minimum
> a ByteString for storing attribute values. You may decide that you
> need an AttributeValue as well in order to cache the normalized
> form, but I don't think that it's necessary and it just bloats the
> API and memory - the Attribute can cache normalized forms.
> Matching rules will need to normalize bytes. For such a low level
> primitive it's best to use an immutable object for this. We also
> have a ByteSequence and ByteStringBuilder in the same manner as
> CharSequence, StringBuilder, and String.
Again, a lot of discussion about it. I'm not convinced that we really
need a ByteString object, as data are either String or byte[], and
String will be internally converted to byte[] (after a PrepareString
normalization). The AttributeValue is what I called AVA (sticking to
the RFC terminology). It makes sense to me to have such an object, as
we have to keep the user provided value, and to have a normalized form
of this value. Of course, you can cach such a value in the Attribute,
but you will have to do the same thing for the RDNs.
I would arther discuss those specific points on another thread to not
confuse people.
> * Search scope (needs to be extensible - i.e. not an enum)
So Scope or SearchScope ? Also, does it really have to be extensible ?
> * Modification type (needs to be extensible - i.e. not an enum)
Operation ? ModOp?
> * Dereference aliases policy
Sure. Don't have a name in mind
> * Condition result for filters (true, false, undefined)
Yup. A name ?
--
Regards,
Cordialement,
Emmanuel Lécharny
www.iktek.com
Re: Let's start for real ?
Posted by Matthew Swift <Ma...@Sun.COM>.
> [...]
> DN : I would rather use Dn
> RDN : Same her, Rdn sounds better to me
> AVA : idem, Ava
> Entry : fine
> Attribute : fine, except that it collides with JNDI attributes, making
> the JNDI -> new API translation cumbersome. EntryAttribute ?
> Modification : Fine
> Control : Fine
> LdapURL : LdapUrl has my preference
> AttributeType : Fine
> DitContentRule : Fine
> DitStructureRule : Fine
> MatchingRule : Fine
> MatchingRuleUse : Fine
> NameForm : Fine
> ObjectClass : Fine
> Syntax : Fine, or LdapSyntax
> ResultCode : Fine
> OID: Oid for me
> CSN: Csn again, same reason
>
I'm happy with those, except that I prefer uppercase (LDAPURL looks
pretty ugly though).
I'm not sure of the value of OID or CSN in an LDAP SDK (especially the
latter).
A data type that we have found particularly useful is
AttributeDescription since this is a structured object (type + options)
with precise syntax and matching semantics (e.g. options must be sorted)
and which is used widely in LDAP. It is then possible for apps to cache
these types if they want to save on repeated parsing:
public final class AttributeDescription {
// Uses default schema.
public static AttributeDescription valueOf(String s) throws
IllegalArgumentException { ... }
// Uses user provided schema.
public static AttributeDescription valueOf(String s, Schema
schema) throws IllegalArgumentException { ... }
// Various convenience methods
public boolean isSubtypeOf(AttributeDescription a) {...}
public boolean containsOption(String s) {...}
// As well as hashCode, equals, compareTo, and toString
}
Then we have:
public interface Entry {
...
Attribute getAttribute(AttributeDescription a);
// Implicit AttributeDescription.valueOf(attributeDescription);
Attribute getAttribute(String attributeDescription) throws
IllegalArgumentException;
}
We don't require that the client API has a schema available. The default
schema can be either the built in standard "core" schema (e.g. cn, sn,
etc) or it could even be the built in "empty" schema, both of which fake
up missing attribute type definitions on demand (in which case they use
octet string syntax and equality matching). This is nice because it
means that the API does not need get bloated by having two API
abstractions (non schema aware and schema aware).
Here's some other types that you'll probably need:
* Filter - this is the raw Filter structure defined in RFC 4511
protocol def. We also have a Matcher object (in the style of the
Regex APIs) which represents a Filter compiled against a
particular schema.
* Assertion - represents an attribute value assertion compiled by a
MatchingRule - typically these are stored in a compiled Filter
(Matcher)
* Schema - a container of attribute types, object classes, etc
* ByteString and/or AttributeValue - you'll need at the bear minimum
a ByteString for storing attribute values. You may decide that you
need an AttributeValue as well in order to cache the normalized
form, but I don't think that it's necessary and it just bloats the
API and memory - the Attribute can cache normalized forms.
Matching rules will need to normalize bytes. For such a low level
primitive it's best to use an immutable object for this. We also
have a ByteSequence and ByteStringBuilder in the same manner as
CharSequence, StringBuilder, and String.
* Search scope (needs to be extensible - i.e. not an enum)
* Modification type (needs to be extensible - i.e. not an enum)
* Dereference aliases policy
* Condition result for filters (true, false, undefined)
Matt
*
Re: Let's start for real ?
Posted by Matthew Swift <Ma...@Sun.COM>.
On 27/11/09 11:14, Emmanuel Lecharny wrote:
>> Yes - I'm on the list now - I joined yesterday afternoon. :-)
>>
> Welcome ! I hope that Sun LDAP developpers will stay at sun long enouh
> to complete this API definition (I just read that Jean-François Arcand
> will leave Sun on dec. 4th... What a loss :/ ). Anyways, that's life
> ...
>
Yes - this is a bit of a bummer, especially as we were using Grizzly
internally for the IO layer in our SDK.
It seems that Grizzly pretty mature these days so it should live on and
we can always become more active ourselves.
>> I've also been cutting and pasting bits of the RFC text into the Javadoc
>> where possible and linking to it, so that people feel "closer" to the
>> standard. I think, if possible, we should take a similar approach in this
>> joint LDAP SDK effort, assuming that we are allowed to quote bits of RFC
>> since they are Copyrighted? Obviously the Javadoc would look pretty ugly if
>> we had to put "Copyright (C) The Internet Society" everywhere.
>>
> Well, if quoted correctly, this is not an isssue. I guess that a
> mention of the copyright in a notice.txt should be fine.
>
>
[...]
Good point - yes we can do that.
Matt
Re: Let's start for real ?
Posted by Emmanuel Lecharny <el...@apache.org>.
>
> Yes - I'm on the list now - I joined yesterday afternoon. :-)
Welcome ! I hope that Sun LDAP developpers will stay at sun long enouh
to complete this API definition (I just read that Jean-François Arcand
will leave Sun on dec. 4th... What a loss :/ ). Anyways, that's life
...
>
> I agree with Ludo's comment above regarding naming. Something we've been
> trying to do is to follow the RFC naming as much as possible as well as
> following Java naming conventions. Sometimes there is a choice of name to
> use (e.g. LDAPDN from RFC4511 which looks ugly all uppercase, or DN from
> RFC4512 which looks silly in mixed case but good in uppercase). We've chosen
> DN in this case for simply for reasons of familiarity: most people refer to
> distinguish names as DNs - not LDAP DNs.
This is a road I also walk : all the messages definition in ADS are
closely defined following the RFCs, even if it sounds silly sometime
(Object instead of DN, etc...)
I proposed Dn just because it was a mix between something easy to use
(better than LdapDN : whatever, is there any DN outside of the LDAP
world ? ;), and because of the Sun JAVA naming convention. But
considering that it's a composite name (Distinguished Name), DN fits
well too.
Ok, let's stay with DN.
RDN too, I guess.
> I've also been cutting and pasting bits of the RFC text into the Javadoc
> where possible and linking to it, so that people feel "closer" to the
> standard. I think, if possible, we should take a similar approach in this
> joint LDAP SDK effort, assuming that we are allowed to quote bits of RFC
> since they are Copyrighted? Obviously the Javadoc would look pretty ugly if
> we had to put "Copyright (C) The Internet Society" everywhere.
Well, if quoted correctly, this is not an isssue. I guess that a
mention of the copyright in a notice.txt should be fine.
--
Regards,
Cordialement,
Emmanuel Lécharny
www.iktek.com
Re: Let's start for real ?
Posted by Matthew Swift <Ma...@Sun.COM>.
On 27/11/09 09:56, Ludovic Poitou wrote:
> Sorry for the delayed answer.
> Matt wasn't subscribed to the list (I think it's done now), and I'm out of the office for a conference.
> We will be back in the office on Monday and will give some answer (unless Matt beats me with it).
> Overall I do think we should try to match the names (and case) used in the RFC.
>
> Ludo
Yes - I'm on the list now - I joined yesterday afternoon. :-)
I agree with Ludo's comment above regarding naming. Something we've been
trying to do is to follow the RFC naming as much as possible as well as
following Java naming conventions. Sometimes there is a choice of name
to use (e.g. LDAPDN from RFC4511 which looks ugly all uppercase, or DN
from RFC4512 which looks silly in mixed case but good in uppercase).
We've chosen DN in this case for simply for reasons of familiarity: most
people refer to distinguish names as DNs - not LDAP DNs.
I've also been cutting and pasting bits of the RFC text into the Javadoc
where possible and linking to it, so that people feel "closer" to the
standard. I think, if possible, we should take a similar approach in
this joint LDAP SDK effort, assuming that we are allowed to quote bits
of RFC since they are Copyrighted? Obviously the Javadoc would look
pretty ugly if we had to put "Copyright (C) The Internet Society"
everywhere.
Matt
Re: Let's start for real ?
Posted by Ludovic Poitou <Lu...@Sun.COM>.
Sorry for the delayed answer.
Matt wasn't subscribed to the list (I think it's done now), and I'm out of the office for a conference.
We will be back in the office on Monday and will give some answer (unless Matt beats me with it).
Overall I do think we should try to match the names (and case) used in the RFC.
Ludo
On Nov 24, 2009, at 4:53 PM, Emmanuel Lecharny wrote:
> Hi guys,
>
> what about starting for real to work on this common API ? We have had
> many preliminary discussions, and also have done a common presentation
> with Ludovic 2 months ago. I was pretty busy since then, but right now,
> the urgency to get a clean API is getting higher.
>
> We have already clarified what a common API should be about. I suggest
> we start by defining the names we want to use for the base objects.
>
> There are a few which are really genuine to ldap, namely, DN, RDN, AVA,
> Entry, Attribute, Modification, Control, LdapURL, AttributeType,
> DitContentRule, DitStructureRule, MatchingRule, MatchingRuleUse,
> NameForm, ObjectClass, Syntax, ResultCode, OID and CSN.
>
> i'm not sure I have listed all the base objects, so feel free to add
> those you think are missing.
>
> Also those names are not the final ones. The idea is to discuss about
> the exact names we will use. For instance, DN is not necessarily the
> most common form. Many APIs or implementations are using LdapDn or
> LdapDN. Assuming that the Java naming convention requires that the first
> letter only to be upcased, one can think that Dn or Rdn is a better name.
>
> Please feel free to give your opinion.
>
> <Emmanuel's option>
> DN : I would rather use Dn
> RDN : Same her, Rdn sounds better to me
> AVA : idem, Ava
> Entry : fine
> Attribute : fine, except that it collides with JNDI attributes, making
> the JNDI -> new API translation cumbersome. EntryAttribute ?
> Modification : Fine
> Control : Fine
> LdapURL : LdapUrl has my preference
> AttributeType : Fine
> DitContentRule : Fine
> DitStructureRule : Fine
> MatchingRule : Fine
> MatchingRuleUse : Fine
> NameForm : Fine
> ObjectClass : Fine
> Syntax : Fine, or LdapSyntax
> ResultCode : Fine
> OID: Oid for me
> CSN: Csn again, same reason
>
> --
> --
> cordialement, regards,
> Emmanuel Lécharny
> www.iktek.com
> directory.apache.org
>
>
>
---
Ludovic Poitou Sun Microsystems Inc.
OpenDS Community Manager Directory Services
http://blogs.sun.com/Ludo/ Grenoble Engineering Center - France
Join OpenDS, https://opends.dev.java.net/servlets/ProjectMembershipRequest
Sun Microsystems requires the following notice:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
NOTICE: This email message is for the sole use of the intended
recipient(s) and may contain confidential and privileged information.
Any unauthorized review, use, disclosure or distribution is prohibited.
If you are not the intended recipient, please contact the sender by
reply email and destroy all copies of the original message.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Re: Let's start for real ?
Posted by Alex Karasulu <ak...@gmail.com>.
You like camel humps which is the Java way. +1 to that.
On Tue, Nov 24, 2009 at 10:53 AM, Emmanuel Lecharny <el...@apache.org>wrote:
> Hi guys,
>
> what about starting for real to work on this common API ? We have had
> many preliminary discussions, and also have done a common presentation
> with Ludovic 2 months ago. I was pretty busy since then, but right now,
> the urgency to get a clean API is getting higher.
>
> We have already clarified what a common API should be about. I suggest
> we start by defining the names we want to use for the base objects.
>
> There are a few which are really genuine to ldap, namely, DN, RDN, AVA,
> Entry, Attribute, Modification, Control, LdapURL, AttributeType,
> DitContentRule, DitStructureRule, MatchingRule, MatchingRuleUse,
> NameForm, ObjectClass, Syntax, ResultCode, OID and CSN.
>
> i'm not sure I have listed all the base objects, so feel free to add
> those you think are missing.
>
> Also those names are not the final ones. The idea is to discuss about
> the exact names we will use. For instance, DN is not necessarily the
> most common form. Many APIs or implementations are using LdapDn or
> LdapDN. Assuming that the Java naming convention requires that the first
> letter only to be upcased, one can think that Dn or Rdn is a better name.
>
> Please feel free to give your opinion.
>
> <Emmanuel's option>
> DN : I would rather use Dn
> RDN : Same her, Rdn sounds better to me
> AVA : idem, Ava
> Entry : fine
> Attribute : fine, except that it collides with JNDI attributes, making
> the JNDI -> new API translation cumbersome. EntryAttribute ?
> Modification : Fine
> Control : Fine
> LdapURL : LdapUrl has my preference
> AttributeType : Fine
> DitContentRule : Fine
> DitStructureRule : Fine
> MatchingRule : Fine
> MatchingRuleUse : Fine
> NameForm : Fine
> ObjectClass : Fine
> Syntax : Fine, or LdapSyntax
> ResultCode : Fine
> OID: Oid for me
> CSN: Csn again, same reason
>
> --
> --
> cordialement, regards,
> Emmanuel Lécharny
> www.iktek.com
> directory.apache.org
>
>
>
>
--
Alex Karasulu
My Blog :: http://www.jroller.com/akarasulu/
Apache Directory Server :: http://directory.apache.org
Apache MINA :: http://mina.apache.org