lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tim Williams <william...@gmail.com>
Subject Re: Proposal about Version API "relaxation"
Date Tue, 13 Apr 2010 15:56:26 GMT
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


Mime
View raw message