From 6ed8241a664c72e62c1db0924fc4a96d89dfde74 Mon Sep 17 00:00:00 2001 From: Bryan Jacobowitz Date: Wed, 14 Feb 2024 09:25:08 -0500 Subject: [PATCH 1/2] Add WrappedCandidateMatcher for composing matchers --- .../org/apache/lucene/monitor/QueryMatch.java | 15 ++++ .../monitor/WrappedCandidateMatcher.java | 74 +++++++++++++++++++ .../lucene/monitor/WrappedMatcherFactory.java | 25 +++++++ 3 files changed, 114 insertions(+) create mode 100644 lucene/monitor/src/java/org/apache/lucene/monitor/WrappedCandidateMatcher.java create mode 100644 lucene/monitor/src/java/org/apache/lucene/monitor/WrappedMatcherFactory.java diff --git a/lucene/monitor/src/java/org/apache/lucene/monitor/QueryMatch.java b/lucene/monitor/src/java/org/apache/lucene/monitor/QueryMatch.java index 57632094edc7..5a04628e61a2 100644 --- a/lucene/monitor/src/java/org/apache/lucene/monitor/QueryMatch.java +++ b/lucene/monitor/src/java/org/apache/lucene/monitor/QueryMatch.java @@ -48,6 +48,21 @@ protected QueryMatch doMatch(String queryId, int doc, Scorable scorer) { } }; + public static final WrappedMatcherFactory SIMPLE_WRAPPED_MATCHER_FACTORY = + searcher -> + new WrappedCandidateMatcher( + new CollectingMatcher(searcher, ScoreMode.COMPLETE_NO_SCORES) { + @Override + public QueryMatch resolve(QueryMatch match1, QueryMatch match2) { + return match1; + } + + @Override + protected QueryMatch doMatch(String queryId, int doc, Scorable scorer) { + return new QueryMatch(queryId); + } + }); + /** * Creates a new QueryMatch for a specific query and document * diff --git a/lucene/monitor/src/java/org/apache/lucene/monitor/WrappedCandidateMatcher.java b/lucene/monitor/src/java/org/apache/lucene/monitor/WrappedCandidateMatcher.java new file mode 100644 index 000000000000..2d46c2544db4 --- /dev/null +++ b/lucene/monitor/src/java/org/apache/lucene/monitor/WrappedCandidateMatcher.java @@ -0,0 +1,74 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.lucene.monitor; + +import java.io.IOException; +import java.util.List; +import java.util.Map; +import org.apache.lucene.search.Query; + +// Wrapper class for an existing candidate matcher exposing finish, matchQuery and reportError +// for composition of matchers +public class WrappedCandidateMatcher { + + private CandidateMatcher delegateTo; + + public WrappedCandidateMatcher(CandidateMatcher wrapThis) { + delegateTo = wrapThis; + } + + public void matchQuery(String queryId, Query matchQuery, Map metadata) + throws IOException { + delegateTo.matchQuery(queryId, matchQuery, metadata); + } + + public MultiMatchingQueries finish(long buildTime, int queryCount) { + return delegateTo.finish(buildTime, queryCount); + } + + protected void addMatch(T match, int doc) { + delegateTo.addMatch(match, doc); + } + + public T resolve(T match1, T match2) { + return delegateTo.resolve(match1, match2); + } + + public void reportError(String queryId, Exception e) { + delegateTo.reportError(queryId, e); + } + + protected void doFinish() { + delegateTo.doFinish(); + } + + protected void copyMatches(CandidateMatcher other) { + delegateTo.copyMatches(other); + } + + public static MultiMatchingQueries buildMultiMatchingQueries( + List> matches, + Map errors, + long queryBuildTime, + long searchTime, + int queriesRun, + int batchSize) { + return new MultiMatchingQueries<>( + matches, errors, queryBuildTime, searchTime, queriesRun, batchSize); + } +} diff --git a/lucene/monitor/src/java/org/apache/lucene/monitor/WrappedMatcherFactory.java b/lucene/monitor/src/java/org/apache/lucene/monitor/WrappedMatcherFactory.java new file mode 100644 index 000000000000..8421409bedf6 --- /dev/null +++ b/lucene/monitor/src/java/org/apache/lucene/monitor/WrappedMatcherFactory.java @@ -0,0 +1,25 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.lucene.monitor; + +import org.apache.lucene.search.IndexSearcher; + +public interface WrappedMatcherFactory { + + WrappedCandidateMatcher createWrappedMatcher(IndexSearcher searcher); +} From df1797a4305e8d5319a36b18879178402062ce4b Mon Sep 17 00:00:00 2001 From: Bryan Jacobowitz Date: Thu, 15 Feb 2024 15:39:48 -0500 Subject: [PATCH 2/2] Javadoc for WrappedCandidateMatcher and WrappedMatcherFactory --- .../monitor/WrappedCandidateMatcher.java | 51 ++++++++++++++++++- .../lucene/monitor/WrappedMatcherFactory.java | 9 ++++ 2 files changed, 58 insertions(+), 2 deletions(-) diff --git a/lucene/monitor/src/java/org/apache/lucene/monitor/WrappedCandidateMatcher.java b/lucene/monitor/src/java/org/apache/lucene/monitor/WrappedCandidateMatcher.java index 2d46c2544db4..c3653c76a445 100644 --- a/lucene/monitor/src/java/org/apache/lucene/monitor/WrappedCandidateMatcher.java +++ b/lucene/monitor/src/java/org/apache/lucene/monitor/WrappedCandidateMatcher.java @@ -22,45 +22,92 @@ import java.util.Map; import org.apache.lucene.search.Query; -// Wrapper class for an existing candidate matcher exposing finish, matchQuery and reportError -// for composition of matchers +/** + * Wrapper class for an existing candidate matcher exposing finish, matchQuery and reportError for + * composition of matchers + */ public class WrappedCandidateMatcher { private CandidateMatcher delegateTo; + /** + * Creates a new WrappedCandidateMatcher delegating to the supplied CandidateMatcher + * + * @param wrapThis the CandidateMatcher to which functions should be delegate + */ public WrappedCandidateMatcher(CandidateMatcher wrapThis) { delegateTo = wrapThis; } + /** + * Runs the supplied query against the delegate CandidateMatcher's set of documents, storing any + * resulting match, and recording the query in the presearcher hits + * + * @param queryId the query id + * @param matchQuery the query to run + * @param metadata the query metadata + * @throws IOException on IO errors + */ public void matchQuery(String queryId, Query matchQuery, Map metadata) throws IOException { delegateTo.matchQuery(queryId, matchQuery, metadata); } + /** + * @return the matches from this matcher + */ public MultiMatchingQueries finish(long buildTime, int queryCount) { return delegateTo.finish(buildTime, queryCount); } + /** + * Record a match into delegate + * + * @param match a QueryMatch object + */ protected void addMatch(T match, int doc) { delegateTo.addMatch(match, doc); } + /** + * If two matches from the same query are found (for example, two branches of a disjunction), + * combine them using the delegate's resolve function. + * + * @param match1 the first match found + * @param match2 the second match found + * @return a Match object that combines the two + */ public T resolve(T match1, T match2) { return delegateTo.resolve(match1, match2); } + /** If running a query throws an Exception, this function will add error into delegate */ public void reportError(String queryId, Exception e) { delegateTo.reportError(queryId, e); } + /** Called when all monitoring of a batch of documents is complete */ protected void doFinish() { delegateTo.doFinish(); } + /** Copy all matches from another CandidateMatcher */ protected void copyMatches(CandidateMatcher other) { delegateTo.copyMatches(other); } + /** + * Build a MultiMatchingQueries + * + * @param matches the matches to include, mapping from queryId to match + * @param errors any errors thrown while evaluating matches + * @param queryBuildTime how long (in ns) it took to build the Presearcher query for the matcher + * run + * @param searchTime how long (in ms) it took to run the selected queries + * @param queriesRun the number of queries passed to this CandidateMatcher during the matcher run + * @param batchSize the number of documents in the batch + * @return a MultiMatchingQueries object with the results of matching a batch of Documents + */ public static MultiMatchingQueries buildMultiMatchingQueries( List> matches, Map errors, diff --git a/lucene/monitor/src/java/org/apache/lucene/monitor/WrappedMatcherFactory.java b/lucene/monitor/src/java/org/apache/lucene/monitor/WrappedMatcherFactory.java index 8421409bedf6..5076be93909e 100644 --- a/lucene/monitor/src/java/org/apache/lucene/monitor/WrappedMatcherFactory.java +++ b/lucene/monitor/src/java/org/apache/lucene/monitor/WrappedMatcherFactory.java @@ -19,7 +19,16 @@ import org.apache.lucene.search.IndexSearcher; +/** + * Interface for the creation of new WrappedCandidateMatcher objects + * + * @param a subclass of {@link CandidateMatcher} + */ public interface WrappedMatcherFactory { + /** + * Create a new {@link WrappedCandidateMatcher} object, to be used to select queries to match + * against the passed-in IndexSearcher + */ WrappedCandidateMatcher createWrappedMatcher(IndexSearcher searcher); }