From api-return-253-apmail-directory-api-archive=directory.apache.org@directory.apache.org Fri Jan 28 16:59:23 2011 Return-Path: Delivered-To: apmail-directory-api-archive@minotaur.apache.org Received: (qmail 14136 invoked from network); 28 Jan 2011 16:59:22 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3) by minotaur.apache.org with SMTP; 28 Jan 2011 16:59:22 -0000 Received: (qmail 41594 invoked by uid 500); 28 Jan 2011 16:59:22 -0000 Delivered-To: apmail-directory-api-archive@directory.apache.org Received: (qmail 41550 invoked by uid 500); 28 Jan 2011 16:59:21 -0000 Mailing-List: contact api-help@directory.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: api@directory.apache.org Delivered-To: mailing list api@directory.apache.org Received: (qmail 41539 invoked by uid 99); 28 Jan 2011 16:59:20 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 28 Jan 2011 16:59:20 +0000 X-ASF-Spam-Status: No, hits=1.8 required=5.0 tests=FREEMAIL_FROM,HTML_FONT_FACE_BAD,HTML_MESSAGE,RCVD_IN_DNSWL_LOW,SPF_PASS,T_TO_NO_BRKTS_FREEMAIL X-Spam-Check-By: apache.org Received-SPF: pass (athena.apache.org: domain of akarasulu@gmail.com designates 74.125.82.44 as permitted sender) Received: from [74.125.82.44] (HELO mail-ww0-f44.google.com) (74.125.82.44) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 28 Jan 2011 16:59:16 +0000 Received: by wwa36 with SMTP id 36so3570227wwa.1 for ; Fri, 28 Jan 2011 08:58:54 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:mime-version:sender:date:x-google-sender-auth :message-id:subject:from:to:content-type; bh=1da44bjP8m31yzV1NnE4I1Ide20h2Z2MIp++swVEVqo=; b=F/mS4wxcWv8d6TWLPIuI8IGI4o17mQXUAxj4FPhvd96BlxHD9dSK+KaxR+iQWoRIp+ N8RtkDuc0MoT+sktE8M4nD08Dszf8CsF405MmHJqNvbxymmzToJ8dw6q8nTd8qVh+tgQ XtuXC8VY75aEuS3dciXGZuvo15yyDa9o527wk= DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=mime-version:sender:date:x-google-sender-auth:message-id:subject :from:to:content-type; b=bVYkqXdJRYFWna6ukf23upvXvU3FIUSMAdtf27WQ3n/jc2gZVUl65ifOB0cA9cdp3o tSaxgzr95Iacq7pT2ZDfZyqDdwXjFtJS7wZzu67WaGiygV9PI6yhjGAZt5ngCP3F1NWa rpwvf1mHETBG523Xs4Bccv8TiGm8YMmFeXQnY= MIME-Version: 1.0 Received: by 10.216.59.143 with SMTP id s15mr1963517wec.49.1296233934662; Fri, 28 Jan 2011 08:58:54 -0800 (PST) Sender: akarasulu@gmail.com Received: by 10.216.73.78 with HTTP; Fri, 28 Jan 2011 08:58:54 -0800 (PST) Date: Fri, 28 Jan 2011 18:58:54 +0200 X-Google-Sender-Auth: iRlu3yK2-OOmnZCGcv89jkdK7_A Message-ID: Subject: [Shared] API Design Questionnaire #1 From: Alex Karasulu To: api@directory.apache.org Content-Type: multipart/alternative; boundary=000e0ce0f8a438aeb2049aeafbe4 --000e0ce0f8a438aeb2049aeafbe4 Content-Type: text/plain; charset=ISO-8859-1 Hi community, Now that we're coming close to finishing up the shared refactoring we have to make some choices. Not all these choices have major impacts but some might. In the past we could do what we liked and change our minds etc. Now with a 1.0 of the shared libraries as the future mother of all Java LDAP APIs we're going to have to live with our choices. To opine, just place an 'X' in an option [ ] box. (1) ModifyRequest has a bunch of methods that were recently added to perform the same operations that you use the Modification interface for. This is redundant in my opinion and adds more unnecessary surface area. We don't need it and don't need an optional path to do the same thing confusing our users. I suggest removing them. [ ] Yes - get rid of extra optional methods [ ] No - keep the extra optional methods [ ] --- - I don't care about this stuff (2) Interfaces verses simple/basic classes implementing them have been something I've swayed back and forth on. Here are the options but note I am just using AddRequest as an example. [ ] - (a) interface = *I*AddRequest simple API exposed implementation = AddRequest not so simple internal use implementation = AddRequest*Decoder* [ ] - (b) interface = AddRequest simple API exposed implementation = *Simple*AddRequest not so simple internal use implementation = AddRequest*Decoder* [ ] - (c) interface = AddRequest simple API exposed implementation = AddRequest*Impl* not so simple internal use implementation = AddRequest*Decoder* [ ] - (d) interface = AddRequest simple API exposed implementation = *Basic*AddRequest not so simple internal use implementation = AddRequest*Decoder* [ ] - (e) I pick the fat lady with the pink tutu .... We're applying option 'C' right now. I'm torn but think A might suite us better for the long term, and for any situation. You also know what's an interface and what's not although the IDE automatically shows you this stuff on the package/class browser. (3) JNDI remnants are somewhat still present even if we've gotten rid of most of them. In the model interfaces for Control, ExtendedRequest, and ExtendedResponse (IntermediateResponse as well but this has nothing to do with JNDI) we have exposed access to ASN.1 encoded data. I think this is a big mistake to do in the public API. Controls and extended operation interfaces should simply expose parameters/properties leaving the rest up to the CODEC to handle. There should be no need to get or set the entire ASN.1 blob for the control or extended operation's request response pair. What good does it do anyway? It's just opening the door for users to incorrectly alter properly encoded ASN.1 data causing problems. I think the getValue() setValue() methods remained after we ran screaming away from JNDI. But it seems these interfaces remained and now they're a liability. Where manipulation of the binary ASN.1 data is needed we can leave this up to the CODEC under a decorator to do. I recommend removing these, what do you think? [ ] Yes - Remove them, they are more bad then good [ ] No - Don't remove them, I like using em [ ] --- - I don't give a rat's a** -- Alex Karasulu My Blog :: http://www.jroller.com/akarasulu/ Apache Directory Server :: http://directory.apache.org Apache MINA :: http://mina.apache.org To set up a meeting with me: http://tungle.me/AlexKarasulu --000e0ce0f8a438aeb2049aeafbe4--