1 package com.atlassian.marketplace.client.api;
2
3 import com.atlassian.fugue.Option;
4
5 import com.google.common.collect.ImmutableList;
6
7 import static com.atlassian.fugue.Option.none;
8 import static com.google.common.base.Preconditions.checkNotNull;
9
10 /**
11 * Interfaces for common query builder criteria, allowing classes like {@link AddonQuery.Builder} to be treated abstractly.
12 * @since 2.0.0
13 */
14 public abstract class QueryBuilderProperties
15 {
16 private QueryBuilderProperties()
17 {
18 }
19
20 /**
21 * Common interface for query builders that have an "access token" parameter.
22 * @see QueryProperties.AccessToken
23 */
24 public static interface AccessToken<T extends AccessToken<T>>
25 {
26 /**
27 * Optionally includes an access token in the query, allowing access to any private add-on
28 * that has such a token.
29 * @param accessToken an access token string, or {@link Option#none}
30 * @return the same query builder
31 * @see QueryProperties.AccessToken#getAccessToken()
32 */
33 T accessToken(Option<String> accessToken);
34 }
35
36 /**
37 * Common interface for query builders that have "application" and "application build number" parameters.
38 * @see QueryProperties.ApplicationCriteria
39 */
40 public static interface ApplicationCriteria<T extends ApplicationCriteria<T>>
41 {
42 /**
43 * Restricts the query to add-ons that are compatible with the specified application.
44 * @param application an {@link ApplicationKey}, or {@link Option#none} for no application filter
45 * @return the same query builder
46 * @see QueryBuilderProperties.ApplicationCriteria#application(Option)
47 */
48 T application(Option<ApplicationKey> application);
49
50 /**
51 * Restricts the query to add-ons that are compatible with the specified application version.
52 * This is ignored if you have not specified {@link #application}.
53 * @param appBuildNumber the application build number, or {@link Option#none} for no application
54 * version filter
55 * @return the same query builder
56 * @see QueryBuilderProperties.ApplicationCriteria#appBuildNumber(Option)
57 */
58 T appBuildNumber(Option<Integer> appBuildNumber);
59 }
60
61 /**
62 * Common interface for query builders that have "offset" and "limit" parameters.
63 */
64 public static interface Bounds<T extends Bounds<T>>
65 {
66 /**
67 * Sets the starting offset and/or the maximum result page size for the query, from a
68 * {@link QueryBounds} instance.
69 * @param bounds a {@link QueryBounds} specifying an offset and/or limit
70 * @return the same query builder
71 */
72 T bounds(QueryBounds bounds);
73 }
74
75 /**
76 * Common interface for query builders that have a "cost" parameter.
77 */
78 public static interface Cost<T extends Cost<T>>
79 {
80 /**
81 * Restricts the query to add-ons/products that match the given {@link com.atlassian.marketplace.client.api.Cost} criteria.
82 * @param cost a {@link com.atlassian.marketplace.client.api.Cost} value, or {@link Option#none} for no cost filter
83 * @return the same query builder
84 */
85 T cost(Option<com.atlassian.marketplace.client.api.Cost> cost);
86 }
87
88 /**
89 * Common interface for query builders that have a "hosting" parameter.
90 */
91 public static interface Hosting<T extends Hosting<T>>
92 {
93 /**
94 * Restricts the query to add-ons that support the given hosting type.
95 * @param hosting a {@link HostingType} constant, or {@link Option#none} for no hosting filter
96 * @return the same query builder
97 */
98 T hosting(Option<HostingType> hosting);
99 }
100
101 /**
102 * Common interface for query builders that have a "withVersion" parameter.
103 */
104 public static interface WithVersion<T extends WithVersion<T>>
105 {
106 /**
107 * Specifies whether the result set should include version-level properties. This is false by default.
108 * @param withVersion true if the result set should include version data
109 * @return the same query builder
110 */
111 T withVersion(boolean withVersion);
112 }
113
114 // Helper classes beyond this point are used internally to simplify query builder implementations.
115
116 static class ApplicationCriteriaHelper
117 {
118 public final Option<ApplicationKey> application;
119 public final Option<Integer> appBuildNumber;
120
121 public ApplicationCriteriaHelper()
122 {
123 this(none(ApplicationKey.class), none(Integer.class));
124 }
125
126 private ApplicationCriteriaHelper(Option<ApplicationKey> application, Option<Integer> appBuildNumber)
127 {
128 this.application = application;
129 this.appBuildNumber = appBuildNumber;
130 }
131
132 public ApplicationCriteriaHelper application(Option<ApplicationKey> application)
133 {
134 return new ApplicationCriteriaHelper(checkNotNull(application), this.appBuildNumber);
135 }
136
137 public ApplicationCriteriaHelper appBuildNumber(Option<Integer> appBuildNumber)
138 {
139 return new ApplicationCriteriaHelper(this.application, checkNotNull(appBuildNumber));
140 }
141
142 public Iterable<String> describe()
143 {
144 ImmutableList.Builder<String> ret = ImmutableList.builder();
145 for (ApplicationKey a: application)
146 {
147 ret.add("application(" + a.getKey() + ")");
148 }
149 for (Integer ab: appBuildNumber)
150 {
151 ret.add("appBuildNumber(" + ab + ")");
152 }
153 return ret.build();
154 }
155 }
156 }