This allows clients to obtain: * *
"Snippet" refers to a substring of text from the content of document that is returned as a
* part of search result.
*
* @see SearchResults
*/
@SafeParcelable.Class(creator = "SearchResultCreator")
@SuppressWarnings("HiddenSuperclass")
public final class SearchResult extends AbstractSafeParcelable {
@FlaggedApi(Flags.FLAG_ENABLE_SAFE_PARCELABLE_2)
@NonNull
public static final Parcelable.Creator The meaning of the ranking signal and its value is determined by the selected ranking
* strategy:
*
* These joined documents match the outer document as specified in the {@link JoinSpec} with
* parentPropertyExpression and childPropertyExpression. They are ordered according to the
* {@link JoinSpec#getNestedSearchSpec}, and as many SearchResults as specified by {@link
* JoinSpec#getMaxJoinedResultCount} will be returned. If no {@link JoinSpec} was specified,
* this returns an empty list.
*
* This method is inefficient to call repeatedly, as new {@link SearchResult} objects are
* created each time.
*
* @return a List of SearchResults containing joined documents.
*/
@NonNull
public List Class Example 1:
*
* A document contains the following text in property "subject":
*
* "A commonly used fake word is foo. Another nonsense word that’s used a lot is bar."
*
* If the queryExpression is "foo" and {@link SearchSpec#getMaxSnippetSize} is 10,
*
*
*
* Class Example 2:
*
* A document contains one property named "subject" and one property named "sender" which
* contains a "name" property.
*
* In this case, we will have 2 property paths: {@code sender.name} and {@code subject}.
*
* Let {@code sender.name = "Test Name Jr."} and {@code subject = "Testing 1 2 3"}
*
* If the queryExpression is "Test" with {@link SearchSpec#TERM_MATCH_PREFIX} and {@link
* SearchSpec#getMaxSnippetSize} is 10. We will have 2 matches:
*
* Match-1
*
* Match-2
*
* If this is {@code null}, methods which require access to the document, like {@link
* #getExactMatch}, will throw {@link NullPointerException}.
*/
@Nullable private GenericDocument mDocument = null;
/** Full text of the matched property. Populated on first use. */
@Nullable private String mFullText;
/** Range of property that exactly matched the query. Populated on first use. */
@Nullable private MatchRange mExactMatchRangeCached;
/**
* Range of property that corresponds to the subsequence of the exact match that directly
* matches a query term. Populated on first use.
*/
@Nullable private MatchRange mSubmatchRangeCached;
/** Range of some reasonable amount of context around the query. Populated on first use. */
@Nullable private MatchRange mWindowRangeCached;
@Constructor
MatchInfo(
@Param(id = 1) @NonNull String propertyPath,
@Param(id = 2) int exactMatchRangeStart,
@Param(id = 3) int exactMatchRangeEnd,
@Param(id = 4) int submatchRangeStart,
@Param(id = 5) int submatchRangeEnd,
@Param(id = 6) int snippetRangeStart,
@Param(id = 7) int snippetRangeEnd) {
mPropertyPath = Objects.requireNonNull(propertyPath);
mExactMatchRangeStart = exactMatchRangeStart;
mExactMatchRangeEnd = exactMatchRangeEnd;
mSubmatchRangeStart = submatchRangeStart;
mSubmatchRangeEnd = submatchRangeEnd;
mSnippetRangeStart = snippetRangeStart;
mSnippetRangeEnd = snippetRangeEnd;
}
/**
* Gets the property path corresponding to the given entry.
*
* A property path is a '.' - delimited sequence of property names indicating which
* property in the document these snippets correspond to.
*
* Example properties: 'body', 'sender.name', 'sender.emailaddress', etc. For class
* example 1 this returns "subject"
*/
@NonNull
public String getPropertyPath() {
return mPropertyPath;
}
/**
* Gets a {@link PropertyPath} object representing the property path corresponding to the
* given entry.
*
* Methods such as {@link GenericDocument#getPropertyDocument} accept a path as a string
* rather than a {@link PropertyPath} object. However, you may want to manipulate the path
* before getting a property document. This method returns a {@link PropertyPath} rather
* than a String for easier path manipulation, which can then be converted to a String.
*
* @see #getPropertyPath
* @see PropertyPath
*/
@NonNull
public PropertyPath getPropertyPathObject() {
if (mPropertyPathObject == null) {
mPropertyPathObject = new PropertyPath(mPropertyPath);
}
return mPropertyPathObject;
}
/**
* Gets the full text corresponding to the given entry.
*
* Class example 1: this returns "A commonly used fake word is foo. Another nonsense word
* that's used a lot is bar."
*
* Class example 2: for the first {@link MatchInfo}, this returns "Test Name Jr." and,
* for the second {@link MatchInfo}, this returns "Testing 1 2 3".
*/
@NonNull
public String getFullText() {
if (mFullText == null) {
if (mDocument == null) {
throw new IllegalStateException(
"Document has not been populated; this MatchInfo cannot be used yet");
}
mFullText = getPropertyValues(mDocument, mPropertyPath);
}
return mFullText;
}
/**
* Gets the {@link MatchRange} of the exact term of the given entry that matched the query.
*
* Class example 1: this returns [29, 32].
*
* Class example 2: for the first {@link MatchInfo}, this returns [0, 4] and, for the
* second {@link MatchInfo}, this returns [0, 7].
*/
@NonNull
public MatchRange getExactMatchRange() {
if (mExactMatchRangeCached == null) {
mExactMatchRangeCached = new MatchRange(mExactMatchRangeStart, mExactMatchRangeEnd);
}
return mExactMatchRangeCached;
}
/**
* Gets the exact term of the given entry that matched the query.
*
* Class example 1: this returns "foo".
*
* Class example 2: for the first {@link MatchInfo}, this returns "Test" and, for the
* second {@link MatchInfo}, this returns "Testing".
*/
@NonNull
public CharSequence getExactMatch() {
return getSubstring(getExactMatchRange());
}
/**
* Gets the {@link MatchRange} of the exact term subsequence of the given entry that matched
* the query.
*
* Class example 1: this returns [29, 32].
*
* Class example 2: for the first {@link MatchInfo}, this returns [0, 4] and, for the
* second {@link MatchInfo}, this returns [0, 4].
*/
@NonNull
public MatchRange getSubmatchRange() {
checkSubmatchSupported();
if (mSubmatchRangeCached == null) {
mSubmatchRangeCached = new MatchRange(mSubmatchRangeStart, mSubmatchRangeEnd);
}
return mSubmatchRangeCached;
}
/**
* Gets the exact term subsequence of the given entry that matched the query.
*
* Class example 1: this returns "foo".
*
* Class example 2: for the first {@link MatchInfo}, this returns "Test" and, for the
* second {@link MatchInfo}, this returns "Test".
*/
@NonNull
public CharSequence getSubmatch() {
checkSubmatchSupported();
return getSubstring(getSubmatchRange());
}
/**
* Gets the snippet {@link MatchRange} corresponding to the given entry.
*
* Only populated when set maxSnippetSize > 0 in {@link
* SearchSpec.Builder#setMaxSnippetSize}.
*
* Class example 1: this returns [29, 41].
*
* Class example 2: for the first {@link MatchInfo}, this returns [0, 9] and, for the
* second {@link MatchInfo}, this returns [0, 13].
*/
@NonNull
public MatchRange getSnippetRange() {
if (mWindowRangeCached == null) {
mWindowRangeCached = new MatchRange(mSnippetRangeStart, mSnippetRangeEnd);
}
return mWindowRangeCached;
}
/**
* Gets the snippet corresponding to the given entry.
*
* Snippet - Provides a subset of the content to display. Only populated when requested
* maxSnippetSize > 0. The size of this content can be changed by {@link
* SearchSpec.Builder#setMaxSnippetSize}. Windowing is centered around the middle of the
* matched token with content on either side clipped to token boundaries.
*
* Class example 1: this returns "foo. Another".
*
* Class example 2: for the first {@link MatchInfo}, this returns "Test Name" and, for
* the second {@link MatchInfo}, this returns "Testing 1 2 3".
*/
@NonNull
public CharSequence getSnippet() {
return getSubstring(getSnippetRange());
}
private CharSequence getSubstring(MatchRange range) {
return getFullText().substring(range.getStart(), range.getEnd());
}
private void checkSubmatchSupported() {
if (mSubmatchRangeStart == -1) {
throw new UnsupportedOperationException(
"Submatch is not supported with this backend/Android API level "
+ "combination");
}
}
/** Extracts the matching string from the document. */
private static String getPropertyValues(GenericDocument document, String propertyName) {
String result = document.getPropertyString(propertyName);
if (result == null) {
throw new IllegalStateException(
"No content found for requested property path: " + propertyName);
}
return result;
}
/**
* Sets the {@link GenericDocument} for {@link MatchInfo}.
*
* {@link MatchInfo} lacks a constructor that populates {@link MatchInfo#mDocument} This
* provides the ability to set {@link MatchInfo#mDocument}
*/
void setDocument(@NonNull GenericDocument document) {
mDocument = document;
}
@FlaggedApi(Flags.FLAG_ENABLE_SAFE_PARCELABLE_2)
@Override
public void writeToParcel(@NonNull Parcel dest, int flags) {
MatchInfoCreator.writeToParcel(this, dest, flags);
}
/** Builder for {@link MatchInfo} objects. */
public static final class Builder {
private final String mPropertyPath;
private MatchRange mExactMatchRange = new MatchRange(0, 0);
int mSubmatchRangeStart = -1;
int mSubmatchRangeEnd = -1;
private MatchRange mSnippetRange = new MatchRange(0, 0);
/**
* Creates a new {@link MatchInfo.Builder} reporting a match with the given property
* path.
*
* A property path is a dot-delimited sequence of property names indicating which
* property in the document these snippets correspond to.
*
* Example properties: 'body', 'sender.name', 'sender.emailaddress', etc. For class
* example 1, this returns "subject".
*
* @param propertyPath A dot-delimited sequence of property names indicating which
* property in the document these snippets correspond to.
*/
public Builder(@NonNull String propertyPath) {
mPropertyPath = Objects.requireNonNull(propertyPath);
}
/** @hide */
public Builder(@NonNull MatchInfo matchInfo) {
Objects.requireNonNull(matchInfo);
mPropertyPath = matchInfo.mPropertyPath;
mExactMatchRange = matchInfo.getExactMatchRange();
mSubmatchRangeStart = matchInfo.mSubmatchRangeStart;
mSubmatchRangeEnd = matchInfo.mSubmatchRangeEnd;
mSnippetRange = matchInfo.getSnippetRange();
}
/** Sets the exact {@link MatchRange} corresponding to the given entry. */
@CanIgnoreReturnValue
@NonNull
public Builder setExactMatchRange(@NonNull MatchRange matchRange) {
mExactMatchRange = Objects.requireNonNull(matchRange);
return this;
}
/**
* Sets the start and end of a submatch {@link MatchRange} corresponding to the given
* entry.
*/
@CanIgnoreReturnValue
@NonNull
public Builder setSubmatchRange(@NonNull MatchRange matchRange) {
mSubmatchRangeStart = matchRange.getStart();
mSubmatchRangeEnd = matchRange.getEnd();
return this;
}
/** Sets the snippet {@link MatchRange} corresponding to the given entry. */
@CanIgnoreReturnValue
@NonNull
public Builder setSnippetRange(@NonNull MatchRange matchRange) {
mSnippetRange = Objects.requireNonNull(matchRange);
return this;
}
/** Constructs a new {@link MatchInfo}. */
@NonNull
public MatchInfo build() {
return new MatchInfo(
mPropertyPath,
mExactMatchRange.getStart(),
mExactMatchRange.getEnd(),
mSubmatchRangeStart,
mSubmatchRangeEnd,
mSnippetRange.getStart(),
mSnippetRange.getEnd());
}
}
}
/**
* Class providing the position range of matching information.
*
* All ranges are finite, and the left side of the range is always {@code <=} the right side
* of the range.
*
* Example: MatchRange(0, 100) represents hundred ints from 0 to 99."
*/
public static final class MatchRange {
private final int mEnd;
private final int mStart;
/**
* Creates a new immutable range.
*
* The endpoints are {@code [start, end)}; that is the range is bounded. {@code start}
* must be lesser or equal to {@code end}.
*
* @param start The start point (inclusive)
* @param end The end point (exclusive)
*/
public MatchRange(int start, int end) {
if (start > end) {
throw new IllegalArgumentException(
"Start point must be less than or equal to " + "end point");
}
mStart = start;
mEnd = end;
}
/** Gets the start point (inclusive). */
public int getStart() {
return mStart;
}
/** Gets the end point (exclusive). */
public int getEnd() {
return mEnd;
}
@Override
public boolean equals(@Nullable Object other) {
if (this == other) {
return true;
}
if (!(other instanceof MatchRange)) {
return false;
}
MatchRange otherMatchRange = (MatchRange) other;
return this.getStart() == otherMatchRange.getStart()
&& this.getEnd() == otherMatchRange.getEnd();
}
@Override
@NonNull
public String toString() {
return "MatchRange { start: " + mStart + " , end: " + mEnd + "}";
}
@Override
public int hashCode() {
return Objects.hash(mStart, mEnd);
}
}
}
*
*
* @return Ranking signal of the document
*/
public double getRankingSignal() {
return mRankingSignal;
}
/**
* Returns the informational ranking signals of the {@link GenericDocument}, according to the
* expressions added in {@link SearchSpec.Builder#addInformationalRankingExpressions}.
*/
@NonNull
@FlaggedApi(Flags.FLAG_ENABLE_INFORMATIONAL_RANKING_EXPRESSIONS)
public List
*
*
* for each match in the document.
*
*
*
*
*
*
*
*
*
*/
@SafeParcelable.Class(creator = "MatchInfoCreator")
@SuppressWarnings("HiddenSuperclass")
public static final class MatchInfo extends AbstractSafeParcelable {
@FlaggedApi(Flags.FLAG_ENABLE_SAFE_PARCELABLE_2)
@NonNull
public static final Parcelable.Creator