You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lucene.apache.org by Doron Cohen <DO...@il.ibm.com> on 2007/02/28 01:59:45 UTC
FieldCache documentation/exposure
Hi,
I am wondering about the exposure (or not) of FieldCache in the
documentation. FieldCache is used by Lucene, internally, for sort purposes.
Being an interface, it is also exposed as public API, but there seems to be
no pointers/documentation suggesting to use it. Well, except for a brief
mentioning in the FAQ entry "The search is slow when there are many hits".
An application, could however, too, use that caching capability for, say,
accessing a stored (external) ID field. See for instance this recent
discussion in the user list -
http://www.nabble.com/Best-way-to-returning-hits-after-search--tf3304485.html
The application could access the cache e.g. like this -
FieldCache fieldCache = FieldCache.DEFAULT;
String f[] = fieldCache.getStrings(ir,fieldname);
After posting a reply for that in the user list I thought about clarifying
about this possible use - so application developers don't have to go and
write their own cache for this, because Lucene already has that. Guess I
wasn't sure if this is just a place where documentation can be improved
(and junit tests added), or the FieldCache is for some reason considered an
internal implementation detail that applications should not rely on.
Thoughts?
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: FieldCache documentation/exposure
Posted by Chris Hostetter <ho...@fucit.org>.
: Guess suggesting to use this in user-list replies would be considered "over
: advertising", but too late at least for
: http://www.nabble.com/Best-way-to-returning-hits-after-search--tf3304485.html
I think the good baseline is to compare it with HitCollector ... it's hte
kind of thing that needs to be well documented, and if a user asks a
question about doing something complex, or more efficiently then the
simple API alows we should certinaly point out that they exist -- as long
as we're clear that using them is non-trivial.
my main point about not advertising was that we shouldn't treat FieldCache
a a "First class class" on package level docs or tutorials the way we do
with Analyzers, IndexSearchers, IndexWriters, Documents, Queries, and
Filters, etc...
http://lucene.apache.org/java/docs/api/overview-summary.html#overview_description
http://lucene.apache.org/java/docs/api/org/apache/lucene/search/package-summary.html#package_description
-Hoss
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: FieldCache documentation/exposure
Posted by Doron Cohen <DO...@il.ibm.com>.
>
> : Guess there are no reservations on the subject; I'll enhance the
> : documentation of this mechanism.
>
> Sorry ... i'm a little behind on my mail ...
I think I know what you mean...
> I wouldn't go advertising it *too* heavily ... i think directly using
> FieldCache is definitely an "Expert" level thing, and we tend to keep the
> documentation on Expert level stuff minimal with the assumption that
> people diging in to that level will familiarize themselves with the code
a
> bit not just read the javadocs.
That's the "tendency" I thought I am identifying, but wasn't sure.
> that said .. i think it's pretty hard ot have too much javadocs ...
> inhancing hte ____ javadocs to explain what ____ is and how it can be
used
> is always good (wether the blank is field in with FieldCache or the name
of
> any other class) but i don't think we need to promote it heavily from the
> top package level javadocs where it might confuse people looking for
basic
> info on the simple aspects of the API.
Sounds fair to me - so I'll just javadoc the class/interface - will do it
in an issue/patch, so any over exposure can be reviewed before committing.
Guess suggesting to use this in user-list replies would be considered "over
advertising", but too late at least for
http://www.nabble.com/Best-way-to-returning-hits-after-search--tf3304485.html
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: FieldCache documentation/exposure
Posted by Chris Hostetter <ho...@fucit.org>.
: Guess there are no reservations on the subject; I'll enhance the
: documentation of this mechanism.
Sorry ... i'm a little behind on my mail ...
I wouldn't go advertising it *too* heavily ... i think directly using
FieldCache is definitely an "Expert" level thing, and we tend to keep the
documentation on Expert level stuff minimal with the assumption that
people diging in to that level will familiarize themselves with the code a
bit not just read the javadocs.
that said .. i think it's pretty hard ot have too much javadocs ...
inhancing hte ____ javadocs to explain what ____ is and how it can be used
is always good (wether the blank is field in with FieldCache or the name of
any other class) but i don't think we need to promote it heavily from the
top package level javadocs where it might confuse people looking for basic
info on the simple aspects of the API.
-Hoss
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: FieldCache documentation/exposure
Posted by Doron Cohen <DO...@il.ibm.com>.
Guess there are no reservations on the subject; I'll enhance the
documentation of this mechanism.
>
> Hi,
>
> I am wondering about the exposure (or not) of FieldCache in the
> documentation. FieldCache is used by Lucene, internally, for sort
purposes.
> Being an interface, it is also exposed as public API, but there seems to
be
> no pointers/documentation suggesting to use it. Well, except for a brief
> mentioning in the FAQ entry "The search is slow when there are many
hits".
>
> An application, could however, too, use that caching capability for, say,
> accessing a stored (external) ID field. See for instance this recent
> discussion in the user list -
>
http://www.nabble.com/Best-way-to-returning-hits-after-search--tf3304485.html
>
> The application could access the cache e.g. like this -
> FieldCache fieldCache = FieldCache.DEFAULT;
> String f[] = fieldCache.getStrings(ir,fieldname);
>
> After posting a reply for that in the user list I thought about
clarifying
> about this possible use - so application developers don't have to go and
> write their own cache for this, because Lucene already has that. Guess I
> wasn't sure if this is just a place where documentation can be improved
> (and junit tests added), or the FieldCache is for some reason considered
an
> internal implementation detail that applications should not rely on.
>
> Thoughts?
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org