View Javadoc
1   package com.atlassian.sal.api.search.query;
2   
3   
4   /**
5    * Utility class to help with creating a query string for the
6    * {@link com.atlassian.sal.api.search.SearchProvider#search(String, String)} method.
7    * <p>
8    * Query strings will have the form:
9    * &lt;searchString&gt;&amp;&lt;param1&gt;=&lt;value1&gt;&amp;&lt;param2&gt;=&lt;value2&gt;...
10   *
11   * @see com.atlassian.sal.api.search.query.SearchQueryParser
12   * @since 2.0
13   */
14  public interface SearchQuery {
15      /**
16       * The parameter separator value
17       */
18      String PARAMETER_SEPARATOR = "&";
19  
20      /**
21       * Sets an arbitrary search parameter to the query string. If parameter with given name
22       * exists, it will be overriden
23       *
24       * @param name  the search parameter name
25       * @param value the search parameter value
26       * @return a reference to this query creator
27       */
28      SearchQuery setParameter(String name, String value);
29  
30      /**
31       * Returns value of the parameter
32       *
33       * @param name the parameter name
34       * @return the parameter value
35       */
36      String getParameter(String name);
37  
38      /**
39       * Appends string query to current query object. New parameters in query will override old ones.
40       *
41       * @param query un-encoded query
42       * @return the created and parsed search query
43       */
44      SearchQuery append(String query);
45  
46  
47      /**
48       * Builds a url-encoded queryString to use with the
49       * {@link com.atlassian.sal.api.search.SearchProvider#search(String, String)} method. <code>queryString</code>
50       * consists of searchString and parameters.
51       *
52       * @return queryString created by this SearchQuery.
53       */
54      String buildQueryString();
55  
56      /**
57       * @return the original string that user is searching for. Same as {@link #buildQueryString()} without parameters and
58       * not url-encoded
59       */
60      String getSearchString();
61  
62      /**
63       * Convenient method to return integer value of parameter. If parameter does not exist, or is not parsable as Integer it returns <code>defaultValue</code>.
64       *
65       * @param name         The parameter name
66       * @param defaultValue The default value if that parameter is not specified
67       * @return the integer value
68       */
69      int getParameter(String name, int defaultValue);
70  }