directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Alex Karasulu <>
Subject Re: Control interface
Date Mon, 31 Jan 2011 13:59:51 GMT
Before going into each of your individual comments I simply want to reflect
on my thoughts regarding the matter of Control's exposing their opaque

First let me list some of the facts we're aware of:

(1) LDAP controls contain an optional value payload encased in a surrounding
envelop that holds the type (OID) and criticality:

        Control ::= SEQUENCE {
                controlType             LDAPOID,
                criticality             BOOLEAN DEFAULT FALSE,
                controlValue            OCTET STRING OPTIONAL }

(2) This optional value can be anything. It does not have to be ASN.1
encoded content. It can be JSON text, XML, or anything else. It's
application specific. However in practice, of the known published controls
the value is AFAIK 100% ASN.1.

(3) Regardless of what is stored in the value, no application can just use
it as is without some kind of component to decode, parse, or interpret this
binary data. It's useless to API users otherwise. It's opaque according to
LDAP, but there has to be some meaning to make use of this content, and that
always requires some code to convert that binary data into usable
information. A useful representation to an API user is a parameterized
representation making the opaque structure transparent.

What exact is that you may ask? Well it's a well defined data type with
members and fields that can be accessed to drive handling logic.

So regardless of whether this binary payload (the value), is json, xml, or
ASN.1 BER encoded data, optimally we should present, or allow them to
present this information to users as a transparent data structure, that they
can use directly to drive code logic. There's not much you can directly do
with a byte[].

(4) In JNDI land, the value, is left as the value, a byte[] because these
guys were so busy with all sorts of naming systems, LDAP only got a little
attention. The general API filled with compromises turned out to be
problematic for the LDAP namespace. There is a way to make controls
pluggable but it's a nightmare. In the end, the pass through strategy made
sense for them. It's just pass through to get a handle on the content,
deferring how to handle it to the application code.

--- o ---

I'll try to make some sense out of my disorderly thoughts now.

(1) The application coder writing the logic to use the control, may not be
the same entity writing/designing the control. The application needs a
transparent parameterized view of the binary opaque data to do anything
sensible with it. Using the data just in pass through situations may occur
but it's the exception and not the rule.

(2) Regardless of the binary value encoding (i.e. json, xml, BER), it can be
marshaled into a distinct data representation that makes sense for
application coders to use.  So if a specific Control subtype in addition to
the type (OID) and criticality properties, exposed all properties needed to
act on that control's content, then these properties can be populated. This
way it's actionable data that can directly be used instead of some useless
binary payload.

(3) It's up to control designers/implementers, to declare what the structure
of their control is. They do this through ASN.1 for BER encoded content for
example. For our codec they should so so by providing a POJI and simple POJO
implementation of their control extending our Control interface which only
has the properties: oid, and criticality.

(4) Expose the POJO and POJI to control users. Yet hide the details of
encoding and decoding. This really does not matter to the control user who
just wants to implement some application logic. It matters not to him if the
data is encoded as JSON, XML, or ASN.1 BER. Just just wants to make the
application logic function based on the information inside. Expose this yet
hide the implementation, (encoding) details.

(5) Make a pluggable framework which supports #4. Let the control
implementor declare (POJI/POJO), and implement (components for encoding and
decoding content) the control's codec extension. The end result to users is
the same regardless of the implementation details.

(6) API's like JNDI left the pass thru door open but did it by exposing the
implementation and potentially allowing the user to shoot themselves in the
foot. Exposing the value is what I am referring to. Really that's fine if
that's all you're going to do but decide on one path. Either expose it and
don't bother representing the opaque data as actionable transparent typed
information. Or don't expose it at all and just let application code deal
with the logical typed information.

So these are my points. Going inline now to answer questions or comment on

On Mon, Jan 31, 2011 at 2:13 PM, Emmanuel Lecharny <>wrote:

> On 1/31/11 1:05 PM, Stefan Seelmann wrote:
>> On Mon, Jan 31, 2011 at 12:08 PM, Emmanuel Lecharny<>
>>  wrote:
>>> Hi,
>>> in the new Control interface we are now using (not the JNDI one), we
>>> don't
>>> expose the getValue() setValue() hasValue() methods. In many respects,
>>> those
>>> methods are useless, and we don't use them in the server.

To us we don't care or should not care about this value. We're application
layer once we try to make sense of the information contained in the value.
We don't care about it as opaque data in studio and in the server.

> However, from a user perspective, someone writing some code on top of the
>>> LDAP API, connected to an unknown server, and getting back some unknown
>>> control, will have no way to get the inner values, unless casting the
>>> control using the ControlDecorator interface.
>>> This is wrong. I think we must expose the three methods to the world.
>> If the user receives an unknown control, what can he do with the value
>> then? He must be able to decode the ASN.1 BER encoded value anyway,
>> right? Then he can also write a new Control class. Am I missing
>> something?
So yeah the byte[] data in the end is useless to everyone. In the end it
must be interpreted to take some action. You know when you get the OID if
you can take action anyway. If you cannot then what's the point to decoding
the value content.

>  He can write a new Control class, but he can also get the opaque value and
> send it to another server.
I off the top of my head cannot think of very many use cases for this
limited situation but we should presume everything is possible. But in this
case, the opaque data is not lost if it's coming in from somewhere, yet it
should still not be exposed according to the reasoning I documented above.

So in this scenario, yes some opaque data comes in and you're not going to
do anything but pass it thru to something else. Ok so you get a Control that
does not expose the value. Under the hood it's a ControlDecorator that holds
the value. So the value is available without exposing application user
access to it. Then when the control needs to be sent off to somewhere else,
this data can be leveraged in the codec, at the layer that should be aware
of it, to prep it for the hand off.

Is this making sense? I may be long winded. Still trying to regain
consciousness this morning.

I mean, there are probably use cases where we want to get the value, not
> decoding it, and use it to do something else.

Yes, but then why bother exposing the value. It's useless and can cause
trouble is what my line of thinking has lead me to.

> Should we force the users to write their own Controls in such a case? Isn't
> it better to provide a generic control with accessors for the value? Ins't
> it a bit over killing to ask the LdapAPI users to implement their own
> controls in order for them to manipulate this value?
(1) In the end if the user is going to use the value and take steps in their
application logic based on that content, then they'd have to decode the
value themselves whatever it is anyway.

(2) If it's opaque, gonna stay opaque, users need not know what's inside,
and it's going to be shuffled off (passed thru) to some other code, client,
server whatever without specific consideration for the content, then there
should be no reason the user code needs access to it. Let the codec encode
decode it, and let only the codec access the binary opaque data.

The alternative is to implement all known controls into the API...
I think if we have a sound plugin mechanism that's easy to use controls can
be implemented very rapidly. Otherwise even the pass thru mechanism has
little to no value.

Practically, after removing the value property, we had serious hardships
shifting our code which was so dependent on accessing this opaque content as
is. I think this is due to the fact that there was no other way to
effectively deal with this at that time.

Alex Karasulu
My Blog ::
Apache Directory Server ::
Apache MINA ::
To set up a meeting with me:

View raw message