@sitevision/api 1.1.0-alpha.1 → 2.0.0-alpha.0

package/hidden/senselogic/sitevision/api/search/searcher/builder/ExtendedDismaxParserBuilder/index.d.ts

@@ -0,0 +1,257 @@
+import Parser from "../../component/Parser";
+import Builder from "../../../../base/Builder";
+
+/**
+ * <p>
+ *    Builder for creating a multi-field {@link senselogic.sitevision.api.search.searcher.component.Parser} component with specific behaviour.
+ * </p>
+ *
+ * <p>
+ *    ExtendedDismaxParserBuilder has several <strong>optional attributes</strong>:
+ * </p>
+ * <ul>
+ *    <li>
+ *       <em>query fields (qf)</em>
+ *       - The fields to query. Default is the fields specified by the index configuration.
+ *       <em>
+ *          (Default query fields for the default Node index is:
+ *          <code>name.analyzed</code>, <code>title.analyzed</code> and <code>content.analyzed</code>)
+ *       </em>
+ *    </li>
+ *    <li>
+ *       <em>user fields (uf)</em>
+ *       - The fields a user can specifically address in a query. Default is the value specified by the index configuration.
+ *    </li>
+ *    <li>
+ *       <em>phrase fields (pf)</em>
+ *       - The phrase fields that can be used for term proximity. Default is the value specified by the index configuration.
+ *    </li>
+ *    <li>
+ *       <em>minimum should match (mm)</em>
+ *       - How terms matching should be handled. Default is the value specified by the index configuration.
+ *    </li>
+ *    <li>
+ *       <em>tiebreaker (tie)</em>
+ *       - How terms matching multiple query fields should be handled. Default is the value specified by the index configuration.
+ *    </li>
+ *    <li>
+ *       <em>additive boost function (bf)</em>
+ *       - Function that can be used to influence the score (additive). Default is the value specified by the index configuration.
+ *    </li>
+ *    <li>
+ *       <em>multiplicative boost function (boost)</em>
+ *       - Function that can be used to influence the score (multiplicative). Default is the value specified by the index configuration.
+ *    </li>
+ *    <li>
+ *       <em>boost query (bq)</em>
+ *       - The query to include in the user's query to influence the score. Default is the value specified by the index configuration.
+ *    </li>
+ * </ul>
+ *
+ * <p>
+ *    Using the ExtendedDismaxParserBuilder is pretty straightforward, if you remember that it is <strong>stateful</strong>.
+ *    Conceptually you would typically use it like this:
+ * </p>
+ * <ol>
+ *   <li>Get the ExtendedDismaxParserBuilder</li>
+ *   <li>Possibly add a query field</li>
+ *   <li>Possibly add another query field</li>
+ *   <li>...</li>
+ *   <li>Do build</li>
+ * </ol>
+ * <p>
+ *    When you have built a <code>Parser</code> instance, you can re-use the ExtendedDismaxParserBuilder to build more instances. Typically like:
+ * </p>
+ * <ol>
+ *   <li>Clear the query fields</li>
+ *   <li>Possibly add a query field</li>
+ *   <li>Possibly add another query field</li>
+ *   <li>...</li>
+ *   <li>Do build</li>
+ * </ol>
+ * <p>
+ *    <strong>Example of how this strategy could be implemented in Velocity:</strong>
+ * </p>
+ * <pre><code>
+ *   <em>## Get the builder</em>
+ *   #set ($searchFactory = $sitevisionUtils.searchFactory)
+ *   #set ($edismaxBuilder = $searchFactory.extendedDismaxParserBuilder)
+ *
+ *   <em>## Create a Parser</em>
+ *   #set ($nameFieldParser = $edismaxBuilder.addQueryField('name.analyzed').build())
+ *
+ *   <em>## Re-use the builder to create another Parser</em>
+ *   #set ($nameAndTitleFieldParser = $edismaxBuilder.addQueryField('title.analyzed').build())
+ *
+ *   <em>## Re-use the builder to create yet another Parser</em>
+ *   #set ($titleAndContentFieldParser = $edismaxBuilder.clearQueryFields().addQueryField('title.analyzed').addQueryField('content.analyzed').build())
+ * </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>
+ *    <em>Solr note: the defType param for this parser is 'edismax'</em>
+ * </p>
+ *
+ * <p>
+ *    An instance of the Sitevision class implementing this interface can be obtained via
+ *    {@link senselogic.sitevision.api.search.SearchFactory#getExtendedDismaxParserBuilder()}.
+ *    See {@link senselogic.sitevision.api.search.SearchFactory} for how to obtain an instance of the <code>SearchFactory</code> interface.
+ * </p>
+ * @author Magnus Lövgren
+ * @since Sitevision 3.6
+ */
+
+interface ExtendedDismaxParserBuilder {
+  /**
+   * Adds a query field.
+   *
+   * <p>
+   *    <em>Solr note: this is the 'qf' param.</em>
+   * </p>
+   * @param aQueryField the name of the query field, a <code>null</code> or whitespace-only value will be ignored
+   * @return this builder
+   */
+  addQueryField(aQueryField: java.lang.String): ExtendedDismaxParserBuilder;
+
+  /**
+   * Adds a query field with a specific boost.
+   *
+   * <p>
+   *    <em>Solr note: this is the 'qf' param.</em>
+   * </p>
+   * @param aQueryField the name of the query field, a <code>null</code> or whitespace-only value will be ignored
+   * @param aBoostValue the boost value, a negative value will be ignored
+   * @return this builder
+   */
+  addQueryField(
+    aQueryField: java.lang.String,
+    aBoostValue: double
+  ): ExtendedDismaxParserBuilder;
+
+  /**
+   * Removes all currently specified query fields.
+   * @return this builder
+   */
+  clearQueryFields(): ExtendedDismaxParserBuilder;
+
+  /**
+   * Sets the tiebreaker.
+   *
+   * <p>
+   *    <em>Solr note: this is the 'tie' param. The value should typically be something much less than 1.</em>
+   * </p>
+   * @param aTieBreaker the tiebreaker
+   * @return this builder
+   * @since Sitevision 4.0.2
+   */
+  setTieBreaker(aTieBreaker: double): ExtendedDismaxParserBuilder;
+
+  /**
+   * Sets the user fields.
+   *
+   * <p>
+   *    <em>Solr note: this is the 'uf' param.</em>
+   * </p>
+   * @param aUserFields the user fields
+   * @return this builder
+   * @since Sitevision 4.0.2
+   */
+  setUserFields(aUserFields: java.lang.String): ExtendedDismaxParserBuilder;
+
+  /**
+   * Sets the minimum should match.
+   *
+   * <p>
+   *    <em>Solr note: this is the 'mm' param. A value of 100% corresponds to the AND operator and a value of 0% corresponds to th OR operator.</em>
+   * </p>
+   * @param aMinimumShouldMatch the minimum should match
+   * @return this builder
+   * @since Sitevision 4.0.2
+   */
+  setMinimumShouldMatch(
+    aMinimumShouldMatch: java.lang.String
+  ): ExtendedDismaxParserBuilder;
+
+  /**
+   * Adds a phrase field.
+   *
+   * <p>
+   *    <em>Solr note: this is the 'pf' param.</em>
+   * </p>
+   * @param aPhraseField a phrase field, a <code>null</code> or whitespace-only value will be ignored
+   * @return this builder
+   * @since Sitevision 4.0.2
+   */
+  addPhraseField(aPhraseField: java.lang.String): ExtendedDismaxParserBuilder;
+
+  /**
+   * Removes all currently specified phrase fields.
+   * @return this builder
+   * @since Sitevision 4.0.2
+   */
+  clearPhraseFields(): ExtendedDismaxParserBuilder;
+
+  /**
+   * Sets a boost query.
+   *
+   * <p>
+   *    <em>Solr note: this is the 'bq' param.</em>
+   * </p>
+   * @param aBoostQuery the boost query
+   * @return this builder
+   * @since Sitevision 4.0.2
+   */
+  setBoostQuery(aBoostQuery: java.lang.String): ExtendedDismaxParserBuilder;
+
+  /**
+   * Adds an additive boost function.
+   *
+   * <p>
+   *    <em>Solr note: this is the 'bf' param.</em>
+   * </p>
+   * @param aAdditiveBoostFunction an additive boost function, a <code>null</code> or whitespace-only value will be ignored
+   * @return this builder
+   * @since Sitevision 4.0.2
+   */
+  addAdditiveBoostFunction(
+    aAdditiveBoostFunction: java.lang.String
+  ): ExtendedDismaxParserBuilder;
+
+  /**
+   * Removes all currently specified additive boost functions.
+   * @return this builder
+   * @since Sitevision 4.0.2
+   */
+  clearAdditiveBoostFunctions(): ExtendedDismaxParserBuilder;
+
+  /**
+   * Adds a a multiplicative boost function.
+   *
+   * <p>
+   *    <em>Solr note: this is the 'boost' param.</em>
+   * </p>
+   * @param aMultiplicativeBoostFunction a multiplicative boost function, a <code>null</code> or whitespace-only value will be ignored
+   * @return this builder
+   * @since Sitevision 4.0.2
+   */
+  addMultiplicativeBoostFunction(
+    aMultiplicativeBoostFunction: java.lang.String
+  ): ExtendedDismaxParserBuilder;
+
+  /**
+   * Removes all currently specified multiplicative boost functions.
+   * @return this builder
+   * @since Sitevision 4.0.2
+   */
+  clearMultiplicativeBoostFunctions(): ExtendedDismaxParserBuilder;
+
+  /**
+   * Creates a Parser component instance using currently specified state/behaviour.
+   * @return a parser component
+   */
+  build(): Parser;
+}

package/hidden/senselogic/sitevision/api/search/searcher/builder/FilterBuilder/index.d.ts

@@ -0,0 +1,103 @@
+import Filter from "../../component/Filter";
+import Builder from "../../../../base/Builder";
+
+/**
+ * <p>
+ *    Builder for creating a {@link senselogic.sitevision.api.search.searcher.component.Filter} component with specific behaviour.
+ * </p>
+ *
+ * <p>
+ *    FilterBuilder has one <strong>mandatory attribute</strong>:
+ * </p>
+ * <ul>
+ *    <li>
+ *       <em>filter query</em> - The query/queries. Must be non-null.
+ *    </li>
+ * </ul>
+ *
+ * <p>
+ *    Using the FilterBuilder is pretty straightforward, if you remember that it is <strong>stateful</strong>. Conceptually you
+ *    would typically use it like this:
+ * </p>
+ * <ol>
+ *   <li>Get the FilterBuilder</li>
+ *   <li>Add a filter query</li>
+ *   <li>Possibly add another filter query</li>
+ *   <li>...</li>
+ *   <li>Do build</li>
+ * </ol>
+ * <p>
+ *    When you have built a <code>Filter</code> instance, you can re-use the FilterBuilder to build more instances. Typically like:
+ * </p>
+ * <ol>
+ *   <li>Clear the filter queries</li>
+ *   <li>Add a filter query</li>
+ *   <li>Possibly add another filter query</li>
+ *   <li>...</li>
+ *   <li>Do build</li>
+ * </ol>
+ * <p>
+ *    <strong>Example of how this strategy could be implemented in Velocity:</strong>
+ * </p>
+ * <pre><code>
+ *   <em>## Get the builder</em>
+ *   #set ($searchFactory = $sitevisionUtils.searchFactory)
+ *   #set ($filterBuilder = $searchFactory.FilterBuilder)
+ *
+ *   <em>## Create a Filter</em>
+ *   #set ($nameMustStartWithAndersFilter = $filterBuilder.addFilterQuery('+name:Anders*').build())
+ *
+ *   <em>## Re-use the builder to create another Filter</em>
+ *   #set ($nameMustContainMagnusFilter = $filterBuilder.clearFilterQueries().addFilterQuery('+name.analyzed:magnus*').build())
+ * </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#getFilterBuilder()}.
+ *    See {@link senselogic.sitevision.api.search.SearchFactory} for how to obtain an instance of the <code>SearchFactory</code> interface.
+ * </p>
+ * @author Magnus Lövgren
+ * @since Sitevision 3.6
+ */
+
+interface FilterBuilder {
+  /**
+   * Adds a filter query.
+   *
+   * <p>
+   *    <em>Solr note: this is the 'fq' param</em>
+   * </p>
+   *
+   * <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="http://searchhub.org/2011/12/28/why-not-and-or-and-not/">Why Not AND, OR, And NOT?</a>.
+   * </p>
+   * @param aFilterQuery the filter query, a <code>null</code> or whitespace-only value will be ignored
+   * @return this builder
+   */
+  addFilterQuery(aFilterQuery: java.lang.String): FilterBuilder;
+
+  /**
+   * Removes all previously added filter queries.
+   * @return this builder
+   */
+  clearFilterQueries(): FilterBuilder;
+
+  /**
+   * Creates a Filter component instance using currently specified state/behaviour.
+   * @return a filter component
+   * @throws IllegalStateException if no filter query exist
+   */
+  build(): Filter;
+}

package/hidden/senselogic/sitevision/api/search/searcher/builder/HighlightBuilder/index.d.ts

@@ -0,0 +1,153 @@
+import Highlight from "../../component/Highlight";
+import Builder from "../../../../base/Builder";
+
+/**
+ * <p>
+ *    Builder for creating a {@link senselogic.sitevision.api.search.searcher.component.Highlight} component with specific behaviour.
+ * </p>
+ *
+ * <p>
+ *    HighlightBuilder has one <strong>mandatory attribute</strong>:
+ * </p>
+ * <ul>
+ *    <li>
+ *       <em>highlighted field</em> - The name of the field(s) that should be highlighted. Must be non-null.
+ *    </li>
+ * </ul>
+ * <p>
+ *    HighlightBuilder also has some <strong>optional attributes</strong>:
+ * </p>
+ * <ul>
+ *    <li>
+ *       <em>fragment char count</em> - The size of a highlighted fragment. Default is 200.
+ *    </li>
+ *    <li>
+ *       <em>fragment pre string</em> - The start value of a highlighted section of a fragment. Default is "&lt;mark&gt;".
+ *    </li>
+ *    <li>
+ *       <em>fragment post string</em> - The end value of a highlighted section of a fragment. Default is "&lt;/mark&gt;".
+ *    </li>
+ * </ul>
+ *
+ * <p>
+ *    Using the HighlightBuilder is pretty straightforward, if you remember that it is <strong>stateful</strong>. Conceptually you
+ *    would typically use it like this:
+ * </p>
+ * <ol>
+ *   <li>Get the HighlightBuilder</li>
+ *   <li>Add a highlighted field</li>
+ *   <li>Possibly set a char count</li>
+ *   <li>Possibly set pre + post</li>
+ *   <li>Do build</li>
+ * </ol>
+ * <p>
+ *    When you have built a <code>Highlight</code> instance, you can re-use the HighlightBuilder to build more instances. Typically like:
+ * </p>
+ * <ol>
+ *   <li>Clear the highlighted fields</li>
+ *   <li>Possibly change char count</li>
+ *   <li>Possibly change pre + post</li>
+ *   <li>Do build</li>
+ * </ol>
+ * <p>
+ *    <strong>Example of how this strategy could be implemented in Velocity:</strong>
+ * </p>
+ * <pre><code>
+ *   <em>## Get the builder</em>
+ *   #set ($searchFactory = $sitevisionUtils.searchFactory)
+ *   #set ($highlightBuilder = $searchFactory.highlightBuilder)
+ *
+ *   <em>## Create a Highlight</em>
+ *   #set ($summaryHighlight = $highlightBuilder.addHighlightedField('summary').build())
+ *
+ *   <em>## Re-use the builder to create another Highlight</em>
+ *   #set ($nameHighlight = $highlightBuilder.clearHighlightedFields().addHighlightedField('name').build())
+ * </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#getHighlightBuilder()}.
+ *    See {@link senselogic.sitevision.api.search.SearchFactory} for how to obtain an instance of the <code>SearchFactory</code> interface.
+ * </p>
+ * @author Magnus Lövgren
+ * @since Sitevision 3.6
+ */
+
+interface HighlightBuilder {
+  /**
+   * Adds a field that should be highlighted.
+   *
+   * <p>
+   *    <em>Solr note: this is the 'hl.fl' param</em>
+   * </p>
+   * @param aHighlightedField name of the field, a <code>null</code> or whitespace-only value will be ignored
+   * @return this builder
+   */
+  addHighlightedField(aHighlightedField: java.lang.String): HighlightBuilder;
+
+  /**
+   * Removes all previously added highlighted fields.
+   * @return this builder
+   */
+  clearHighlightedFields(): HighlightBuilder;
+
+  /**
+   * Sets the number of chars that highlighted fragment should contain.
+   *
+   * <p>
+   *    If no char count is specified, the default value of the index config will be used (200).
+   * </p>
+   *
+   * <p>
+   *    <em>Solr note: this is the 'hl.fragsize' param</em>
+   * </p>
+   * @param aCharCount the char count
+   * @return this builder
+   * @throws IllegalArgumentException if <code>aCharCount</code> is zero or negative
+   */
+  setFragmentCharCount(aCharCount: int): HighlightBuilder;
+
+  /**
+   * Sets the start value for the highlighted section(s) of a fragment.
+   *
+   * <p>
+   *    If the pre string and post string are not specified, the default value of the index config will be used
+   *    ('&lt;mark&gt;' and '&lt;/mark&gt;').
+   * </p>
+   *
+   * <p>
+   *    <em>Solr note: this is the 'hl.simple.pre' param</em>
+   * </p>
+   * @param aPreString a fragment start
+   * @return this builder
+   */
+  setFragmentPreString(aPreString: java.lang.String): HighlightBuilder;
+
+  /**
+   * Sets the end value for the highlighted section(s) of a fragment.
+   *
+   * <p>
+   *    <strong>Note! </strong> The fragment <em>pre</em> value must match the fragment <em>post</em> string!
+   *    E.g: if the <em>pre</em> string is "&lt;em&gt;", the <em>post</em> string would typically be "&lt;/em&gt;".
+   * </p>
+   *
+   * <p>
+   *    <em>Solr note: this is the 'hl.simple.post' param</em>
+   * </p>
+   * @param aPostString a fragment end
+   * @return this builder
+   */
+  setFragmentPostString(aPostString: java.lang.String): HighlightBuilder;
+
+  /**
+   * Creates a Highlight component instance using currently specified state/behaviour.
+   * @return a Highlight component
+   * @throws IllegalStateException if no highlighted field is specified, or if pre and post strings doesn't match (e.g. one of them is null)
+   */
+  build(): Highlight;
+}

package/hidden/senselogic/sitevision/api/search/searcher/builder/MonitorBuilder/index.d.ts

@@ -0,0 +1,47 @@
+import Monitor from "../../component/Monitor";
+import Builder from "../../../../base/Builder";
+
+/**
+ * <p>
+ *    Builder for creating a {@link senselogic.sitevision.api.search.searcher.component.Monitor} component.
+ * </p>
+ *
+ * <p>
+ *    MonitorBuilder has one <em>optional</em> attribute:
+ * </p>
+ * <ul>
+ *    <li>
+ *       <em>query logging</em> - the query logging mode. Default is on (i.e. <code>true</code>).
+ *       <em>Important note!</em> Even though the query logging is enabled, it does not necessarily mean that the query actually will be logged
+ *       (actual logging requires the <em>Search package 1</em> license).
+ *    </li>
+ * </ul>
+ *
+ * <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#getMonitorBuilder()}.
+ *    See {@link senselogic.sitevision.api.search.SearchFactory} for how to obtain an instance of the <code>SearchFactory</code> interface.
+ * </p>
+ * @author Magnus Lövgren
+ * @since Sitevision 4.1
+ */
+
+interface MonitorBuilder {
+  /**
+   * Sets the query logging mode on or off.
+   * @param aEnableQueryLogging whether or not the query logging mode should be turned on (true) or off (false).
+   * @return this builder
+   */
+  setEnableQueryLogging(aEnableQueryLogging: boolean): MonitorBuilder;
+
+  /**
+   * Creates a Monitor component instance using currently specified state/behaviour.
+   * @return a monitor component
+   */
+  build(): Monitor;
+}