Mailing-List: contact java-dev-help@lucene.apache.org; run by ezmlm
Precedence: bulk
Reply-To: java-dev@lucene.apache.org
Received-SPF: pass (athena.apache.org: domain of williamstw@gmail.com
 designates 209.85.160.176 as permitted sender)
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=gamma;
        h=mime-version:in-reply-to:references:date:message-id:subject:from:to
         :content-type;
        b=ZfQy+JT3RdxxP2fu3Ob4vekbjAaVqJr+9aQ/jdHDFJAB/rRxJCL81hGBdJSwu+2liz
         65pKAFGmxSqN3H+5av0dcYhrOlFZpwTUxCTQPSdOB2H46fS1307q2rDpOCnMcUkKZkm3
         OgYozRv6YXMeqW+g5lFLv86zwa43+lM1hc/eQ=
MIME-Version: 1.0
In-Reply-To: <s2v786fde51004130827r994f2d7en64d2147df5a13f7d@mail.gmail.com>
References: <s2v786fde51004130827r994f2d7en64d2147df5a13f7d@mail.gmail.com>
Date: Tue, 13 Apr 2010 11:56:26 -0400
Message-ID: <u2x499888441004130856i9b189363uef581c6d674ca962@mail.gmail.com>
Subject: Re: Proposal about Version API "relaxation"
From: Tim Williams <williamstw@gmail.com>
To: java-dev@lucene.apache.org
Content-Type: text/plain; charset=ISO-8859-1

On Tue, Apr 13, 2010 at 11:27 AM, Shai Erera <serera@gmail.com> wrote:
> Hi
>
> I'd like to propose a relaxation on the Version API. Uwe, please read the
> entire email before you reply :).
>
> I was thinking, following a question on the user list, that the
> Version-based API may not be very intuitive to users, especially those who
> don't care about versioning, as well as very inconvenient. So there are two
> issues here:
> 1) How should one use Version smartly so that he keeps backwards
> compatibility. I think we all know the answer, but a Wiki page with some
> "best practices" tips would really help users use it.
> 2) How can one write sane code, which doesn't pass versions all over the
> place if: (1) he doesn't care about versions, or (2) he cares, and sets the
> Version to the same value in his app, in all places.
>
> Also, I think that today we offer a flexibility to users, to set different
> Versions on different objects in the life span of their application - which
> is a good flexibility but can also lead people to shoot themselves in the
> legs if they're not careful -- e.g. upgrading Version across their app, but
> failing to do so for one or two places ...
>
> So the change I'd like to propose is to mostly alleviate (2) and better
> protect users - I DO NOT PROPOSE TO GET RID OF Version :).
>
> I was thinking that we can add on Version a DEFAULT version, which the
> caller can set. So Version.setDefault and Version.getDefault will be added,
> as static members (more on the static-ness of it later). We then change the
> API which requires Version to also expose an API which doesn't require it,
> and that API will call Version.getDefault(). People can use it if they want
> to ...
>
> Few points:
> 1) As a default DEFAULT Version is controversial, I don't want to propose
> it, even though I think Lucene can define the DEFAULT to be the latest.
> Instead, I propose that Version.getDefault throw a
> DefaultVersionNotSetException if it wasn't set, while an API which relies on
> the default Version is called (I don't want to return null, not sure how
> safe it is).
> 2) That DEFAULT Version is static, which means it will affect all indexing
> code running inside the JVM. Which is fine:
> 2.1) Perhaps all the indexing code should use the same Version
> 2.2) If you know that's not the case, then pass Version to the API which
> requires it - you cannot use the 'default Version' API -- nothing changes
> for you.
> One case is missing -- you might not know if your code is the only indexing
> code which runs in the JVM ... I don't have a solution to that, but I think
> it'll be revealed pretty quickly, and you can change your code then ...
>
> So to summarize - the current Version API will remain and people can still
> use it. The DEFAULT Version API is meant for convenience for those who don't
> want to pass Version everywhere, for the reasons I outlined above. This will
> also clean our test code significantly, as the tests will set the DEFAULT
> version to TEST_VERSION_CURRENT at start ...
>
> The changes to the Version class will be very simple.
>
> If people think that's acceptable, I can open an issue and work on it.

>From the peanut gallery, I say *please*.  This Version idiom has taken
an otherwise beautiful api and nearly boosted it to the likes of DOM
and InputStream;)

--tim

---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org