@sitevision/api 1.0.20 → 1.1.0-alpha.2

package/server/SearchFactory/index.d.ts

@@ -0,0 +1,133 @@
+import ExtendedDismaxParserBuilder from "../ExtendedDismaxParserBuilder";
+import FilterBuilder from "../FilterBuilder";
+import HighlightBuilder from "../HighlightBuilder";
+import IndexUtil from "../IndexUtil";
+import IndexingUtil from "../IndexingUtil";
+import SearcherBuilder from "../SearcherBuilder";
+import SortBuilder from "../SortBuilder";
+import SearchSortField from "../../hidden/senselogic/sitevision/api/search/SearchSortField";
+import SearchUtil from "../SearchUtil";
+import SpellCheckBuilder from "../SpellCheckBuilder";
+import StandardParserBuilder from "../StandardParserBuilder";
+import QueryStringUtil from "../QueryStringUtil";
+import MonitorBuilder from "../MonitorBuilder";
+
+/**
+ * Gets a ExtendedDismaxParserBuilder instance.
+ * @return a ExtendedDismaxParserBuilder instance
+ */
+export function getExtendedDismaxParserBuilder(): ExtendedDismaxParserBuilder;
+
+/**
+ * Gets a FilterBuilder instance.
+ * @return a FilterBuilder instance
+ */
+export function getFilterBuilder(): FilterBuilder;
+
+/**
+ * Gets a HighlightBuilder instance.
+ * @return a HighlightBuilder instance
+ */
+export function getHighlightBuilder(): HighlightBuilder;
+
+/**
+ * Gets an IndexUtil instance.
+ * @return an IndexUtil instance
+ */
+export function getIndexUtil(): IndexUtil;
+
+/**
+ * Gets an IndexingUtil instance.
+ * @return an IndexingUtil instance
+ * @since Sitevision 3.6.4
+ */
+export function getIndexingUtil(): IndexingUtil;
+
+/**
+ * Gets a SearcherBuilder instance.
+ * @return a SearcherBuilder instance
+ */
+export function getSearcherBuilder(): SearcherBuilder;
+
+/**
+ * Gets a SortBuilder instance.
+ * @return a SortBuilder instance
+ */
+export function getSortBuilder(): SortBuilder;
+
+/**
+ * Convenience method to get a SearchSortField instance.
+ * @param aField name of the sortable index field
+ * @param aIsAscending the sort order (true == ascending, false == descending)
+ * @return a SearchSortField instance
+ * @throws IllegalArgumentException if aField is null or whitespace-only
+ */
+export function getSearchSortField(
+  aField: string,
+  aIsAscending: boolean
+): SearchSortField;
+
+/**
+ * Convenience method to get a SearchUtil instance.
+ *
+ * <em>A SearchUtil instance can also be retrieved via the {@link senselogic.sitevision.api.Utils#getSearchUtil()}</em>
+ * @return a SearchUtil instance
+ */
+export function getSearchUtil(): SearchUtil;
+
+/**
+ * Gets a SpellCheckBuilder instance.
+ * @return a SpellCheckBuilder instance
+ */
+export function getSpellCheckBuilder(): SpellCheckBuilder;
+
+/**
+ * Gets a StandardParserBuilder instance.
+ * @return a StandardParserBuilder instance
+ */
+export function getStandardParserBuilder(): StandardParserBuilder;
+
+/**
+ * Gets a QueryStringUtil instance.
+ * @return a QueryStringUtil instance
+ */
+export function getQueryStringUtil(): QueryStringUtil;
+
+/**
+ * Gets a MonitorBuilder instance.
+ * @return a MonitorBuilder instance
+ * @since Sitevision 4.1
+ */
+export function getMonitorBuilder(): MonitorBuilder;
+
+/**
+ * Factory for creating search-related instances.
+ *
+ * <p>
+ *    An instance of the Sitevision class implementing this interface can be obtained via {@link senselogic.sitevision.api.Utils#getSearchFactory()}.
+ *    See {@link senselogic.sitevision.api.Utils} for how to obtain an instance of the <code>Utils</code> interface.
+ * </p>Gets a ExtendedDismaxParserBuilder instance.Gets a FilterBuilder instance.Gets a HighlightBuilder instance.Gets an IndexUtil instance.Gets an IndexingUtil instance.Gets a SearcherBuilder instance.Gets a SortBuilder instance.Convenience method to get a SearchSortField instance.Convenience method to get a SearchUtil instance.
+ *
+ * <em>A SearchUtil instance can also be retrieved via the {@link senselogic.sitevision.api.Utils#getSearchUtil()}</em>Gets a SpellCheckBuilder instance.Gets a StandardParserBuilder instance.Gets a QueryStringUtil instance.Gets a MonitorBuilder instance.
+ * @author Magnus Lövgren
+ * @since Sitevision 3.6
+ */
+declare namespace SearchFactory {
+  export {
+    getExtendedDismaxParserBuilder,
+    getFilterBuilder,
+    getHighlightBuilder,
+    getIndexUtil,
+    getIndexingUtil,
+    getSearcherBuilder,
+    getSortBuilder,
+    getSearchSortField,
+    getSearchUtil,
+    getSpellCheckBuilder,
+    getStandardParserBuilder,
+    getQueryStringUtil,
+    getMonitorBuilder,
+  };
+}
+
+export default SearchFactory;

package/server/SearchUtil/index.d.ts

@@ -0,0 +1,164 @@
+import SearchResult from "../../hidden/senselogic/sitevision/api/search/SearchResult";
+
+/**
+ * <p>
+ *    Searches the default index using the <em>multi-field</em> ("edismax") parser.
+ * </p>
+ *
+ * <p>
+ *    Here is a simple example written in server-side javascript:
+ * </p>
+ * <pre><code>
+ * var searchUtil = request.getAttribute("sitevision.utils").getSearchUtil();
+ * var result = searchUtil.search("test*", null, 0, 10);
+ * if (result.hasHits()) {
+ *    out.println("Approximate hit count: " + result.getApproximateCount() + "&lt;br/&gt;");
+ *    var hits = result.getHits();
+ *    while (hits.hasNext()) {
+ *       var hit = hits.next();
+ *       out.print("&lt;a href=\"" + hit.getField('uri') + "\" title=\"\"&gt;");
+ *       out.print(hit.getField('title'));
+ *       out.print("&lt;/a&gt;");
+ *       out.println("&lt;br/&gt;");
+ *    }
+ * } else {
+ *    out.println("No hits for query = '" + result.getQuery() + "'&lt;br/&gt;");
+ * }
+ * </code></pre>
+ *
+ * <p>
+ *    <em>Note! <code>aQuery</code> will be stripped from Local params,
+ *    see {@link senselogic.sitevision.api.search.query.QueryStringUtil#stripLocalParams(String)}.</em>
+ * </p>
+ * @param aQuery The search query according to the <em>Solr query syntax</em>
+ * @param sortFields A <code>List</code> of {@link SearchSortField} objects. May be <code>null</code>.
+ * @param aStartAtHit number of leading hits to be skipped
+ * @param aMaxHitsToReturn maximum total number of hits to be returned
+ * @return The search returns a {@link SearchResult} and is never <code>null</code>
+ */
+export function search(
+  aQuery: string,
+  sortFields: unknown[],
+  aStartAtHit: number,
+  aMaxHitsToReturn: number
+): SearchResult;
+
+/**
+ * <p>
+ *    Searches the default index using the <em>single-field</em> ("standard") parser with a specified default field.
+ * </p>
+ *
+ * <p>
+ *    <em>Note! <code>aQuery</code> will be stripped from Local params,
+ *    see {@link senselogic.sitevision.api.search.query.QueryStringUtil#stripLocalParams(String)}.</em>
+ * </p>
+ * @param aQuery The search query according to the <em>Solr query syntax</em>
+ * @param aFieldName name of the field that should be queried
+ * @param sortFields A <code>List</code> of {@link SearchSortField} objects. May be <code>null</code>.
+ * @param aStartAtHit number of leading hits to be skipped
+ * @param aMaxHitsToReturn maximum total number of hits to be returned
+ * @return a {@link SearchResult} and is never <code>null</code>
+ * @since Sitevision 2.7_06
+ * @since Sitevision 3.0
+ */
+export function search(
+  aQuery: string,
+  aFieldName: string,
+  sortFields: unknown[],
+  aStartAtHit: number,
+  aMaxHitsToReturn: number
+): SearchResult;
+
+/**
+ * <p>
+ *    Convenience interface for querying the default index.
+ * </p>
+ *
+ * <div style="border:1px dotted gray; padding-left:10px; padding-right:10px; padding-bottom:10px">
+ *    <p>
+ *       <strong>Note!</strong> This interface contains convenience methods for basic search in the default index.
+ *       When more powerful search behaviour is needed - use {@link senselogic.sitevision.api.search.searcher.Searcher} instead!
+ *       <em>Actually, you can always use Searcher, but not always SearchUtil</em>.
+ *    </p>
+ *    <p>
+ *       Examples of when you <em>must</em> use {@link senselogic.sitevision.api.search.searcher.Searcher} instead is:
+ *    </p>
+ *    <ul>
+ *       <li>
+ *          You want to query <em>another index</em> (not the default index).
+ *       </li>
+ *       <li>
+ *          You want to do multi-field querying and want to <em>specify query fields</em> (not use the default ones specified by the index).
+ *       </li>
+ *       <li>
+ *          You want to use a <em>filter</em> to separate the "user" query and the "filter" query (which also improves performance).
+ *       </li>
+ *       <li>
+ *          You want to <em>highlight</em> one or more fields in the search result.
+ *       </li>
+ *       <li>
+ *          You want <em>suggestions ("did you mean")</em> in the search result.
+ *       </li>
+ *    </ul>
+ * </div>
+ *
+ * <p>
+ *    <strong>Query syntax note! </strong>Query strings should be expressed according to the <em>Solr query syntax</em>.
+ *    The syntax is basically the
+ *    <em><a href="http://lucene.apache.org/core/4_10_3/queryparser/org/apache/lucene/queryparser/classic/package-summary.html#package_description">
+ *       Lucene query syntax</a></em>
+ *    with <em><a href="http://wiki.apache.org/solr/SolrQuerySyntax#Differences_From_Lucene_Query_Parser">some minor differences</a></em>.
+ *    Also note that a general recommendation is to always use the <em>prefix operators</em> (<code>+</code>/<code>-</code>) instead of the
+ *    <em>boolean keywords</em> (AND/OR/NOT)
+ *    to avoid unexpected behaviour. For deeper understanding, see for example
+ *    <a href="https://lucidworks.com/blog/2011/12/28/why-not-and-or-and-not/">Why Not AND, OR, And NOT?</a>.
+ * </p>
+ *
+ * <p>
+ *    An instance of the Sitevision class implementing this interface can be obtained via {@link senselogic.sitevision.api.Utils#getSearchUtil()}.
+ *    See {@link senselogic.sitevision.api.Utils} for how to obtain an instance of the <code>Utils</code> interface.
+ * </p><p>
+ *    Searches the default index using the <em>multi-field</em> ("edismax") parser.
+ * </p>
+ *
+ * <p>
+ *    Here is a simple example written in server-side javascript:
+ * </p>
+ * <pre><code>
+ * var searchUtil = request.getAttribute("sitevision.utils").getSearchUtil();
+ * var result = searchUtil.search("test*", null, 0, 10);
+ * if (result.hasHits()) {
+ *    out.println("Approximate hit count: " + result.getApproximateCount() + "&lt;br/&gt;");
+ *    var hits = result.getHits();
+ *    while (hits.hasNext()) {
+ *       var hit = hits.next();
+ *       out.print("&lt;a href=\"" + hit.getField('uri') + "\" title=\"\"&gt;");
+ *       out.print(hit.getField('title'));
+ *       out.print("&lt;/a&gt;");
+ *       out.println("&lt;br/&gt;");
+ *    }
+ * } else {
+ *    out.println("No hits for query = '" + result.getQuery() + "'&lt;br/&gt;");
+ * }
+ * </code></pre>
+ *
+ * <p>
+ *    <em>Note! <code>aQuery</code> will be stripped from Local params,
+ *    see {@link senselogic.sitevision.api.search.query.QueryStringUtil#stripLocalParams(String)}.</em>
+ * </p><p>
+ *    Searches the default index using the <em>single-field</em> ("standard") parser with a specified default field.
+ * </p>
+ *
+ * <p>
+ *    <em>Note! <code>aQuery</code> will be stripped from Local params,
+ *    see {@link senselogic.sitevision.api.search.query.QueryStringUtil#stripLocalParams(String)}.</em>
+ * </p>
+ * @author Mikael Wikblom
+ * @since Sitevision 2.6_06
+ * @see senselogic.sitevision.api.search.searcher.Searcher
+ */
+declare namespace SearchUtil {
+  export { search };
+}
+
+export default SearchUtil;

package/server/SearcherBuilder/index.d.ts

@@ -0,0 +1,260 @@
+import Filter from "../../hidden/senselogic/sitevision/api/search/searcher/component/Filter";
+import Highlight from "../../hidden/senselogic/sitevision/api/search/searcher/component/Highlight";
+import Node from "../../hidden/javax/jcr/Node";
+import Parser from "../../hidden/senselogic/sitevision/api/search/searcher/component/Parser";
+import Sort from "../../hidden/senselogic/sitevision/api/search/searcher/component/Sort";
+import SpellCheck from "../../hidden/senselogic/sitevision/api/search/searcher/component/SpellCheck";
+import Monitor from "../../hidden/senselogic/sitevision/api/search/searcher/component/Monitor";
+import Searcher from "../../hidden/senselogic/sitevision/api/search/searcher/Searcher";
+
+/**
+ * Sets the filter component.
+ *
+ * <p>
+ *    A <code>Filter</code> instance is created via the {@link FilterBuilder#build()} method.
+ * </p>
+ * @param aFilter the filter component
+ * @return this builder
+ * @see FilterBuilder
+ */
+export function setFilter(aFilter: Filter): SearcherBuilder;
+
+/**
+ * Sets the highlight component.
+ *
+ * <p>
+ *    A <code>Highlight</code> instance is created via the {@link HighlightBuilder#build()} method.
+ * </p>
+ * @param aHighlight the highlight component
+ * @return this builder
+ * @see HighlightBuilder
+ */
+export function setHighlight(aHighlight: Highlight): SearcherBuilder;
+
+/**
+ * Sets the index to search in.
+ *
+ * <p>
+ *    <strong>Note!</strong> If no index is set, the <code>Searcher</code> that is constructed will use
+ *    the <em>default node index</em> (i.e. the main index with pages/images/files etc.).
+ * </p>
+ *
+ * <p>
+ *    <strong>Tip!</strong> Use the {@link senselogic.sitevision.api.search.index.IndexUtil} utility to get an index.
+ * </p>
+ * @param anIndex the index
+ * @return this builder
+ * @throws IllegalArgumentException if <code>anIndex</code> isn't an index node (primary node type name should be <code>sv:nodeIndex</code> or <code>sv:applicationIndex</code>)
+ */
+export function setIndex(anIndex: Node): SearcherBuilder;
+
+/**
+ * Sets the parser component.
+ *
+ * <p>
+ *    A <code>Parser</code> instance is created via the {@link ExtendedDismaxParserBuilder#build()} method
+ *    or the {@link StandardParserBuilder#build()} method.
+ * </p>
+ *
+ * <p>
+ *    <strong>Note!</strong> If no Parser is set, the <code>Searcher</code> that is constructed will use a <em>default multi-field
+ *    parser</em> (that can be constructed via {@link ExtendedDismaxParserBuilder}).
+ * </p>
+ * @param aParser the parser component
+ * @return this builder
+ * @see ExtendedDismaxParserBuilder
+ * @see StandardParserBuilder
+ */
+export function setParser(aParser: Parser): SearcherBuilder;
+
+/**
+ * Sets the sort component.
+ *
+ * <p>
+ *    A <code>Sort</code> instance is created via the {@link SortBuilder#build()} method.
+ * </p>
+ * @param aSort the sort component
+ * @return this builder
+ * @see SortBuilder
+ */
+export function setSort(aSort: Sort): SearcherBuilder;
+
+/**
+ * Sets the spell check (suggestions/did-you-mean) component.
+ *
+ * <p>
+ *    A <code>SpellCheck</code> instance is created via the {@link SpellCheckBuilder#build()} method.
+ * </p>
+ * @param aSpellCheck the spell check component
+ * @return this builder
+ * @see SpellCheckBuilder
+ */
+export function setSpellCheck(aSpellCheck: SpellCheck): SearcherBuilder;
+
+/**
+ * Sets the monitor component.
+ *
+ * <p>
+ *    A <code>Monitor</code> instance is created via the {@link MonitorBuilder#build()} method.
+ * </p>
+ * @param aMonitor the monitor component
+ * @return this builder
+ * @see MonitorBuilder
+ * @since Sitevision 4.1
+ */
+export function setMonitor(aMonitor: Monitor): SearcherBuilder;
+
+/**
+ * Creates a Searcher instance using currently specified components.
+ * @return a Searcher instance
+ */
+export function build(): Searcher;
+
+/**
+ * <p>
+ *    Builder for creating a {@link senselogic.sitevision.api.search.searcher.Searcher} with a specific setup of components.
+ * </p>
+ *
+ * <p>
+ *    The following components can be set. All components are optional.
+ * </p>
+ * <ul>
+ *    <li>
+ *       {@link senselogic.sitevision.api.search.searcher.component.Parser}<em>
+ *          - what parser should be used to handle the queries and what field/fields should be queried?
+ *       </em>
+ *       Default: a <em>default multi-field parser</em>.
+ *    </li>
+ *    <li>
+ *       {@link senselogic.sitevision.api.search.searcher.component.Filter}<em>
+ *          - how should the result be limited?
+ *       </em>
+ *       Default: <code>null</code> (i.e. no filtering).
+ *    </li>
+ *    <li>
+ *       {@link senselogic.sitevision.api.search.searcher.component.SpellCheck}<em>
+ *          - should the search engine try to get suggestions (did you mean)?
+ *       </em>
+ *       Default: <code>null</code> (i.e. no suggestions).
+ *    </li>
+ *    <li>
+ *       {@link senselogic.sitevision.api.search.searcher.component.Highlight}<em>
+ *          - which fields should be highlighted and how?
+ *       </em>
+ *       Default: <code>null</code> (i.e. no highlighting).
+ *    </li>
+ *    <li>
+ *       {@link senselogic.sitevision.api.search.searcher.component.Sort}<em>
+ *          - how should the result be sorted?
+ *       </em>
+ *       Default: <code>null</code> (i.e. no sorting).
+ *    </li>
+ *    <li>
+ *       {@link senselogic.sitevision.api.search.searcher.component.Monitor}<em>
+ *          - how should querying be monitored? (e.g. should search query logging mode be on or off?)
+ *       </em>
+ *       Default: <code>null</code> (i.e. no monitoring).
+ *    </li>
+ * </ul>
+ * <p>
+ *    What <em>index</em> to query can also be specified. Default is the <em>default node index</em>
+ *    (i.e. the main index with pages/images/files etc.).
+ * </p>
+ *
+ * <p>
+ *    <strong>Example of how to use the SearchBuilder to create a Searcher in Velocity:</strong>
+ * </p>
+ * <pre><code>
+ *   <em>## Get the search factory</em>
+ *   #set ($searchFactory = $sitevisionUtils.searchFactory)
+ *
+ *   <em>## Create a Filter component</em>
+ *   #set ($filterBuilder = $searchFactory.filterBuilder)
+ *   #set ($filter = $filterBuilder.addFilterQuery('metadata.category:responsive').build())
+ *
+ *   <em>## Create a Highlight component</em>
+ *   #set ($highlightBuilder = $searchFactory.highlightBuilder)
+ *   #set ($highlight = $highlightBuilder.addHighlightedField('summary').build())
+ *
+ *   <em>## Create a Sort component</em>
+ *   #set ($lastPublishedSort = $searchFactory.getSearchSortField('lastpublished', true))
+ *   #set ($sortBuilder = $searchFactory.sortBuilder)
+ *   #set ($sort = $sortBuilder.addSortField($lastPublishedSort).build())
+ *
+ *   <em>## Get the search builder</em>
+ *   #set ($searcherBuilder = $searchFactory.searcherBuilder)
+ *
+ *   <em>## Set all components and create the Searcher</em>
+ *   #set ($searcher = $searcherBuilder.setFilter($filter).setHighlight($highlight).setSort($sort).build())
+ *
+ *   <em>## Search and handle the result</em>
+ *   #set ($searchResult = $searcher.search('example*', 10))
+ *   <em>...</em>
+ * </code></pre>
+ *
+ * <p>
+ *    <strong>Tip!</strong> The {@link senselogic.sitevision.api.base.Builder Builder interface documentation} contains
+ *    more information about Builders and how to work with them!
+ * </p>
+ *
+ * <p>
+ *    An instance of the Sitevision class implementing this interface can be obtained via
+ *    {@link senselogic.sitevision.api.search.SearchFactory#getSearcherBuilder()}.
+ *    See {@link senselogic.sitevision.api.search.SearchFactory} for how to obtain an instance of the <code>SearchFactory</code> interface.
+ * </p>Sets the filter component.
+ *
+ * <p>
+ *    A <code>Filter</code> instance is created via the {@link FilterBuilder#build()} method.
+ * </p>Sets the highlight component.
+ *
+ * <p>
+ *    A <code>Highlight</code> instance is created via the {@link HighlightBuilder#build()} method.
+ * </p>Sets the index to search in.
+ *
+ * <p>
+ *    <strong>Note!</strong> If no index is set, the <code>Searcher</code> that is constructed will use
+ *    the <em>default node index</em> (i.e. the main index with pages/images/files etc.).
+ * </p>
+ *
+ * <p>
+ *    <strong>Tip!</strong> Use the {@link senselogic.sitevision.api.search.index.IndexUtil} utility to get an index.
+ * </p>Sets the parser component.
+ *
+ * <p>
+ *    A <code>Parser</code> instance is created via the {@link ExtendedDismaxParserBuilder#build()} method
+ *    or the {@link StandardParserBuilder#build()} method.
+ * </p>
+ *
+ * <p>
+ *    <strong>Note!</strong> If no Parser is set, the <code>Searcher</code> that is constructed will use a <em>default multi-field
+ *    parser</em> (that can be constructed via {@link ExtendedDismaxParserBuilder}).
+ * </p>Sets the sort component.
+ *
+ * <p>
+ *    A <code>Sort</code> instance is created via the {@link SortBuilder#build()} method.
+ * </p>Sets the spell check (suggestions/did-you-mean) component.
+ *
+ * <p>
+ *    A <code>SpellCheck</code> instance is created via the {@link SpellCheckBuilder#build()} method.
+ * </p>Sets the monitor component.
+ *
+ * <p>
+ *    A <code>Monitor</code> instance is created via the {@link MonitorBuilder#build()} method.
+ * </p>Creates a Searcher instance using currently specified components.
+ * @author Magnus Lövgren
+ * @since Sitevision 3.6
+ */
+declare namespace SearcherBuilder {
+  export {
+    setFilter,
+    setHighlight,
+    setIndex,
+    setParser,
+    setSort,
+    setSpellCheck,
+    setMonitor,
+    build,
+  };
+}
+
+export default SearcherBuilder;