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

package/hidden/senselogic/sitevision/api/search/SearchResult/index.d.ts

@@ -9,148 +9,13 @@ import SearchHighlighter from "../SearchHighlighter";
  * <p>
  *    <strong>Note!</strong> This object is short lived in that sense that it is invalid after a specified timespan.
  *    Make sure it's handled correspondingly (i.e. do <em>not</em> cache it).
- * </p><p>Accessor to the lazy loaded <code>Iterator</code> containing the search hits. Iterating the
- * <code>Iterator</code> potentially changes the status of the <code>SearchResult</code>object.</p>
- *
- * <p>
- *    <strong>IMPORTANT NOTE!</strong> You should only call this method <strong>once</strong>! Subsequent calls
- *    will throw an <code>IllegalStateException</code>.
- * </p><p>Convenience method for iterating search hits using the Java foreach loop construct.</p>
- *
- * <p>
- *    <strong>NOTE! This convenience method is just an ALIAS for the {@link #getHits()} method!<br>
- *    Restrictions and such that applies to {@link #getHits()} also applies to this method!</strong>
- * </p>
- *
- * <p>
- *    This is a convenience method for enabling iteration of search hits using the <em>foreach loop</em>:
- * </p>
- * <pre><code>
- *    SearchResult searchResult = ...
- *    for (SearchHit searchHit : searchResult) {
- *       ...
- *    }</code></pre>...so you don't have to use the <em>for loop</em> and iterate via the <code>getHits()</code> method:
- *    <pre><code><em>
- *    SearchResult searchResult = ...
- *    for (Iterator&lt;SearchHit&gt; searchHits = searchResult.getHits(); searchHits.hasNext();) {
- *       SearchHit searchHit = searchHits.next();
- *       ...
- *    }</em></code></pre>...or use the <em>while loop</em>:<pre><code><em>
- *    SearchResult searchResult = ...
- *    Iterator&lt;SearchHit&gt; searchHits = searchResult.getHits();
- *    while (searchHits.hasNext()) {
- *       SearchHit searchHit = searchHits.next();
- *       ...
- *    }</em></code></pre><p>Accessor to the exact number of hits. This operation renders the lazy loaded
- * optimization obsolete having to resolve each node to do authorization etc. The
- * value can be less than the value returned by {@link #getApproximateCount} for
- * authenticated users.</p>
- *
- * <p>
- *    <strong>Potentially a very expensive operation!</strong> To be used only when an
- *    exact count is really, REALLY needed. Normally {@link #getApproximateCount} will
- *    suffise (paging etc.).
- * </p>
- *
- * <p>
- *    <strong>Tip!</strong> If you require exact accuracy for "small" search results and accept
- *    potential inaccurate hit count for "large" results - use {@link #getEffectiveCount(int)} instead!
- * </p>
- *
- * <p>
- *    <strong>Note:</strong> If your only interest in this method is to check if the exact count is more
- *    than zero or not, you SHOULD use {@link #hasHits} instead.<br><br>In other words, this:
- * </p>
- * <pre><code>
- *    if (!mySearchResult.hasHits())
- *    {
- *       <em>// Handle no hits</em>
- *       ...
- *    }</code></pre>
- * <p>
- *    is always much, Much, MUCH preferred to this:
- * </p>
- * <pre><code>
- *    if (mySearchResult.getExactCount() == 0)
- *    {
- *       <em>// Handle no hits</em>
- *       ...
- *    }</code></pre><p>Whether the search result contains hits or not.</p>
- *
- * <p>
- *    This is a convenience method that enables you to check if there are any hits, without obtaining a (possibly unneeded)
- *    iterator via {@link #getHits}.
- * </p>
- * <p>
- *    In other words, this:
- * </p>
- * <pre><code>
- *    if (mySearchResult.hasHits())
- *    {
- *       <em>// Handle hits</em>
- *       Iterator&lt;SearchHit&gt; hitIterator = mySearchResult.getHits();
- *       ...
- *    }</code></pre>
- * <p>
- *    is preferred to this:
- * </p>
- * <pre><code>
- *    Iterator&lt;SearchHit&gt; hitIterator = mySearchResult.getHits();
- *    if (hitIterator.hasNext())
- *    {
- *       <em>// Handle hits</em>
- *       ...
- *    }</code></pre>
- *
- * <p>
- *    <strong>Note:</strong> This method <em>must</em> be called before iterating the hits. If you already have started iterating
- *    the hits, the result of this method is indeterminate.
- * </p>
- *
- * <p>
- *    <strong>Note:</strong> If your only interest is to check if exact count is more than zero or not, this method
- *    is much, much less expensive than calling {@link #getExactCount} and comparing the result to zero.
- * </p><p>Predicts the number of hits by disregarding expensive operations like node authorization etc.
- * This value can be higher than the value returned by {@link #getExactCount} for authenticated users.</p>
- *
- * <p>
- *    <strong>Tip!</strong> If you require exact accuracy for "small" search results and accept approximate hit count for
- *    "large" results, you would typically use the {@link #getEffectiveCount(int)} method!
- * </p><p>Returns the <em>exact</em> hit count or the <em>approximate</em> hit count, given a specified count threshold.</p>
- *
- * <p>
- *    This method enables you to get accurate hit count for "small" search results and estimated hit count for "large" search results.
- *    A "silver bullet" method when deciding between using the potentially less performant (but exact) {@link #getExactCount()} and the
- *    well performant (but potentially inexact) {@link #getApproximateCount()}
- * </p>
- *
- * <p>
- *    <strong>An example: </strong><code>getEffectiveCount(100)</code>
- * </p>
- * <ul>
- *    <li>returns <code>exactCount</code> if the estimated hit count is <em>lower</em> than 100</li>
- *    <li>returns <code>approximateCount</code> if the estimated hit count is <em>equal or higher</em> than 100</li>
- * </ul><p>
- *    The search query that was used to create this search result.
- * </p><p>
- *    The "human friendly" variant of the query to display in search results.
- * </p>
- * <p>
- *    Note! if no specific <em>display query</em> was specified when assembling/executing the search
- *    (see {@link senselogic.sitevision.api.search.searcher.Searcher}), this method will
- *    return same value as {@link #getQuery()}.
- * </p><p>The current status of the search. This value might change when iterating the
- * <code>Iterator</code> containing the {@link SearchHit} objects.</p><p>
- *    Accessor to a string representation of the status code.
- * </p>Returns the facet fields for this search result.Returns suggestions for this search result.Returns the custom sorts for this search result.<em><strong>Note! Do not use this method. This method will return a deprecated and non-functional object instance.
- * It will be completely removed in future versions of Sitevision!</strong></em><em><strong>Note! Do not use this method. It will be completely removed in future versions of Sitevision!</strong></em>
- *
- * <p>
- *    Use {@link senselogic.sitevision.api.script.ScriptUtil#getFormatPattern(java.util.Locale)}
- *    and {@link senselogic.sitevision.api.script.ScriptUtil#getDateAsString(String, java.util.Date)} instead to format dates for search hits.
  * </p>Search is successful.Search is unsuccessful due to a missing index.Search is unsuccessful due to an invalid search query.Search is unsuccessful due to an unexpected error.
  * @author Mikael Wikblom
  * @since Sitevision 2.6_06
+ * @see #getStatus()
+ * @see #getStatus()
+ * @see #getStatus()
+ * @see #getStatus()
  */
 interface SearchResult {
   /**
@@ -371,21 +236,21 @@ interface SearchResult {
    * @return a list of search facet fields, or <code>null</code> if there are no facet fields
    * @since Sitevision 3.0
    */
-  getFacetFields(): unknown[];
+  getFacetFields(): unknown;
 
   /**
    * Returns suggestions for this search result.
    * @return a list of suggestions, or <code>null</code> if there are no suggestions
    * @since Sitevision 3.0
    */
-  getSuggestions(): unknown[];
+  getSuggestions(): unknown;
 
   /**
    * Returns the custom sorts for this search result.
    * @return a list of custom sorts, or <code>null</code> if there are no custom sorts
    * @since Sitevision 3.2
    */
-  getCustomSorts(): unknown[];
+  getCustomSorts(): unknown;
 
   /**
    * <em><strong>Note! Do not use this method. This method will return a deprecated and non-functional object instance.

package/hidden/senselogic/sitevision/api/search/SearchResult/index.js

@@ -0,0 +1,24 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports["default"] = void 0;
+var _default = {
+  getHits: function getHits() {},
+  iterator: function iterator() {},
+  getExactCount: function getExactCount() {},
+  hasHits: function hasHits() {},
+  getApproximateCount: function getApproximateCount() {},
+  getEffectiveCount: function getEffectiveCount() {},
+  getQuery: function getQuery() {},
+  getDisplayQuery: function getDisplayQuery() {},
+  getStatus: function getStatus() {},
+  getStatusMessage: function getStatusMessage() {},
+  getFacetFields: function getFacetFields() {},
+  getSuggestions: function getSuggestions() {},
+  getCustomSorts: function getCustomSorts() {},
+  getSearchHighlighter: function getSearchHighlighter() {},
+  getDateFormatter: function getDateFormatter() {}
+};
+exports["default"] = _default;

package/hidden/senselogic/sitevision/api/search/SearchUtil/index.d.ts

@@ -0,0 +1,126 @@
+import SearchResult from "../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>
+ * @author Mikael Wikblom
+ * @since Sitevision 2.6_06
+ * @see senselogic.sitevision.api.search.searcher.Searcher
+ */
+
+interface SearchUtil {
+  /**
+   * <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>
+   */
+  search(
+    aQuery: java.lang.String,
+    sortFields: java.util.List,
+    aStartAtHit: int,
+    aMaxHitsToReturn: int
+  ): 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
+   */
+  search(
+    aQuery: java.lang.String,
+    aFieldName: java.lang.String,
+    sortFields: java.util.List,
+    aStartAtHit: int,
+    aMaxHitsToReturn: int
+  ): SearchResult;
+}

package/hidden/senselogic/sitevision/api/search/facet/SearchFacetField/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * A facet field of a search result.Returns the name of this facet field.Returns the facet values for this facet field.Convenience method for getting the number of values for this facet field.
+ * A facet field of a search result.
  * @author Niclas Hedlund
  * @since Sitevision 3.0
  * @see senselogic.sitevision.api.search.SearchResult#getFacetFields()
@@ -15,7 +15,7 @@ interface SearchFacetField {
    * Returns the facet values for this facet field.
    * @return the list of values for this facet field, or <code>null</code> if there are no values
    */
-  getFacetValues(): unknown[];
+  getFacetValues(): unknown;
 
   /**
    * Convenience method for getting the number of values for this facet field.

package/hidden/senselogic/sitevision/api/search/facet/SearchFacetField/index.js

@@ -0,0 +1,12 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports["default"] = void 0;
+var _default = {
+  getName: function getName() {},
+  getFacetValues: function getFacetValues() {},
+  getValueCount: function getValueCount() {}
+};
+exports["default"] = _default;

package/hidden/senselogic/sitevision/api/search/facet/SearchFacetValue/index.d.ts

@@ -1,16 +1,5 @@
 /**
- * A facet value of a facet field.Returns the number of occurrences (number of expected hits when searching with this facet value).Returns the name of this facet valueReturns the relative URL for executing a query for this facet value.Returns the query parameters for this facet value.
- * <p>
- * The filter query params is a sub-set of the filter URL.
- * </p>
- *
- * <p>An example: If the filterURL is:<br>
- *    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<code>/a/b/c.html?query=d&amp;e=f&amp;g=h</code><br>
- *    the filterQueryParams will be:<br>
- *    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<code>d&amp;e=f&amp;g=h</code><br>
- *    <em>(Note that the value starts with the "query" parameter, but <strong>without</strong> the actual query
- *    parameter name: '<span style="text-decoration:line-through">query=</span>')</em>
- * </p>Returns whether or not this facet value is selected.
+ * A facet value of a facet field.
  * @author Magnus Lövgren
  * @since Sitevision 3.0
  * @see senselogic.sitevision.api.search.facet.SearchFacetField#getFacetValues()

package/hidden/senselogic/sitevision/api/search/facet/SearchFacetValue/index.js

@@ -0,0 +1,14 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports["default"] = void 0;
+var _default = {
+  getCount: function getCount() {},
+  getName: function getName() {},
+  getFilterURL: function getFilterURL() {},
+  getFilterQueryParams: function getFilterQueryParams() {},
+  isSelected: function isSelected() {}
+};
+exports["default"] = _default;

package/hidden/senselogic/sitevision/api/search/index/IndexUtil/index.d.ts

@@ -0,0 +1,50 @@
+import Node from "../../../../../../javax/jcr/Node";
+
+/**
+ * Index utility interface.
+ *
+ * <p>
+ *    An instance of the Sitevision class implementing this interface can be obtained via
+ *    {@link senselogic.sitevision.api.search.SearchFactory#getIndexUtil()}.
+ *    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 IndexUtil {
+  /**
+   * Gets the default index for a specified index type.
+   *
+   * <p>
+   *    <strong>Note!</strong>The default user identity index is only handled if a <em>Social Collaboration</em> license is in use.
+   *    The default user-generated content (UGC) index is only handled if a <em>Social Collaboration</em> license is in use.
+   * </p>
+   * @param aIndexType type of index
+   * @return the default index for <code>aIndexType</code>, or <code>null</code> if not available
+   */
+  getDefaultIndex(
+    aIndexType: senselogic.sitevision.api.search.index.IndexUtil.IndexType
+  ): Node;
+
+  /**
+   * Gets an index by name.
+   *
+   * <p>
+   *    Lookup order:
+   * </p>
+   * <ol>
+   *    <li>Custom <em>site</em> index</li>
+   *    <li>Custom <em>server</em> index</li>
+   *    <li><em>Default</em> index(-es), types specified by {@link senselogic.sitevision.api.search.index.IndexUtil.IndexType}</li>
+   * </ol>
+   * <p>
+   *    <strong>Note!</strong> Custom index is only handled if a <em>Search Package 2</em> license is in use.
+   *    The default user identity index is only handled if a <em>Social Collaboration</em> license is in use.
+   *    The default user-generated content (UGC) index is only handled if a <em>Social Collaboration</em> license is in use.
+   * </p>
+   * @param aIndexName the name of the index
+   * @return the index or <code>null</code> if no index matches <code>aIndexName</code>
+   */
+  getIndexByName(aIndexName: java.lang.String): Node;
+}

package/hidden/senselogic/sitevision/api/search/index/IndexingUtil/index.d.ts

@@ -0,0 +1,59 @@
+import Node from "../../../../../../javax/jcr/Node";
+
+/**
+ * Indexing utility interface.
+ *
+ * <p>
+ *    An instance of the Sitevision class implementing this interface can be obtained via
+ *    {@link senselogic.sitevision.api.search.SearchFactory#getIndexingUtil()}.
+ *    See {@link senselogic.sitevision.api.search.SearchFactory} for how to obtain an instance of the <code>SearchFactory</code> interface.
+ * </p>The minimum resource priority.
+ *
+ * A resource indexed with this priority value will get a document boost of <code>0.1F</code>.The default resource priority.
+ *
+ * A resource indexed with this priority value will get the default document boost of <code>1.0F</code>.The maximum resource priority.
+ *
+ * A resource indexed with this priority value will get a document boost of <code>2.0F</code>.
+ * @author Magnus Lövgren
+ * @since Sitevision 3.6.4
+ */
+
+interface IndexingUtil {
+  /**
+   * Sets the resource priority for an indexable node.
+   *
+   * <p>
+   *    The <em>resource priority</em> of a node will influence its <em>document boost</em> when indexed.
+   * </p>
+   *
+   * <p>
+   *    <strong>Note!</strong> Method invocations that doesn't fulfill these 3 criteria will always fail (i.e. return <code>false</code>):
+   * </p>
+   * <ul>
+   *    <li>
+   *       The <code>aNode</code> must be an indexable node, typically a <code>sv:page</code>, <code>sv:article</code>,
+   *       <code>sv:file</code> or <code>sv:image</code>.
+   *    </li>
+   *    <li>
+   *       The <code>aPriority</code> must be in interval: [ {@link #MIN_RESOURCE_PRIORITY} .. {@link #MAX_RESOURCE_PRIORITY} ].
+   *    </li>
+   *    <li>
+   *       Current user must have {@link senselogic.sitevision.api.security.PermissionUtil.Permission#WRITE} and
+   *       {@link senselogic.sitevision.api.security.PermissionUtil.Permission#MODIFY_SEARCH_PRIORITY}
+   *       on <code>aNode</code>.
+   *    </li>
+   * </ul>
+   * <p>
+   *    This method tries to acquire a <em>lock</em> on <code>aNode</code> in order to mutate its resource priority.
+   *    Mutation will fail (i.e. this method will return <code>false</code>) if <code>aNode</code> is already locked.
+   * </p>
+   *
+   * <p>
+   *    <em>Indexing note!</em> Changing the value of the resource priority of a node will automatically trigger a re-index of the node.
+   * </p>
+   * @param aNode the indexable node
+   * @param aPriority the priority, i.e. in interval: [ {@link #MIN_RESOURCE_PRIORITY} .. {@link #MAX_RESOURCE_PRIORITY} ]
+   * @return <code>true</code> if the operation succeeded, <code>false</code> otherwise
+   */
+  setResourcePriority(aNode: Node, aPriority: int): boolean;
+}