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