On Tue, Apr 13, 2010 at 11:27 AM, Shai Erera <ser...@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-unsubscr...@lucene.apache.org For additional commands, e-mail: java-dev-h...@lucene.apache.org
