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 14:09:30 GMT
On Mon, Jan 31, 2011 at 3:59 PM, Alex Karasulu <> wrote:

> 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
> values.
> 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
> remarks:
> 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.
> +1
> 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.

Just wanted to make a point here. Perhaps we can expose on special cases the
binary representation. Maybe the Codec service interface can provide a copy
of the encoded value when asked for instead of allowing user tampering. In
the pass thru case, this data should be shuffled off anyway so a copy can be
given thru this API instead of exposing Decorator fields to users allowing
for possible tampering.


> 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