Suggesters: allow to pass a user-defined predicate/filter to the completion searcher [LUCENE-4517]

As a user, I'd like to be able to specify a
filter during completion lookup which further determines whether some completion should be considered or not. Assume, for example, that I have a suggestion engine for book titles. In my current search, I'm only interested in computer science books, but I can't/don't want to maintain separate WFSTs for each subject area.

Given some completion candidate, the filter would be called (with a key and/or the completion string as a parameter) to determine whether or not the completion candidate should be added to the result queue.

Note:

Adding a filter/predicate to the AnalyzingSuggester is simple,
as TopNSearcher<> already uses acceptResult() to test whether some completion should be added - that can be overridden in a derived searcher class which simply calls the predicate. Ideally the suggesters would access some kind of factory to instantiate the searcher to be used (instead of hardwiring it in).

**Discussion on java-user:**

Mike McCandless:

Exactly! One gotchya is you have to be careful about the maxQueueDepth, because if your acceptResult accepts too few results then the queue may have pruned away paths that would have led to a valid topN path ...

We may also invert all of these FST based suggests, and expose building blocks for apps to build up custom suggesters. There are many use cases we need to accommodate and we have a ways to converge on a clear API here ...

---
Migrated from [LUCENE-4517](https://issues.apache.org/jira/browse/LUCENE-4517) by Oliver Christ, updated Nov 02 2012
Attachments: [Lucene-trunk-20121026-AnalyzingSuggester.patch](https://apache.github.io/lucene-jira-archive/attachments/LUCENE-4517/Lucene-trunk-20121026-AnalyzingSuggester.patch)

Start by reading AnalyzingSuggester and TopNSearcher, especially acceptResult() and maxQueueDepth; the issue identifies these as the relevant entry points. Review the attached AnalyzingSuggester patch and the discussion before choosing an API. Done means completion lookup accepts a user-defined predicate and preserves correct top-N results when candidates are rejected.

Written by the indexing model from the issue text.