Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
Search |
|
| 1.0;1 | ||||
Search$Order |
|
| 1.0;1 | ||||
Search$Qualifier |
|
| 1.0;1 |
1 | /** | |
2 | * Copyright (c) 2013-2017, jcabi.com | |
3 | * All rights reserved. | |
4 | * | |
5 | * Redistribution and use in source and binary forms, with or without | |
6 | * modification, are permitted provided that the following conditions | |
7 | * are met: 1) Redistributions of source code must retain the above | |
8 | * copyright notice, this list of conditions and the following | |
9 | * disclaimer. 2) Redistributions in binary form must reproduce the above | |
10 | * copyright notice, this list of conditions and the following | |
11 | * disclaimer in the documentation and/or other materials provided | |
12 | * with the distribution. 3) Neither the name of the jcabi.com nor | |
13 | * the names of its contributors may be used to endorse or promote | |
14 | * products derived from this software without specific prior written | |
15 | * permission. | |
16 | * | |
17 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | |
18 | * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT | |
19 | * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND | |
20 | * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL | |
21 | * THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, | |
22 | * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES | |
23 | * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR | |
24 | * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
25 | * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, | |
26 | * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) | |
27 | * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED | |
28 | * OF THE POSSIBILITY OF SUCH DAMAGE. | |
29 | */ | |
30 | package com.jcabi.github; | |
31 | ||
32 | import com.jcabi.aspects.Immutable; | |
33 | import java.io.IOException; | |
34 | import java.util.EnumMap; | |
35 | ||
36 | /** | |
37 | * Github search. | |
38 | * | |
39 | * @author Carlos Miranda (miranda.cma@gmail.com) | |
40 | * @version $Id: f941049846a34b1934328fe288032e76c7f4ad82 $ | |
41 | * @since 0.8 | |
42 | * @see <a href="http://developer.github.com/v3/search/">Search API</a> | |
43 | */ | |
44 | @Immutable | |
45 | @SuppressWarnings("PMD.AvoidDuplicateLiterals") | |
46 | public interface Search { | |
47 | ||
48 | /** | |
49 | * Github we're in. | |
50 | * | |
51 | * @return Github | |
52 | */ | |
53 | Github github(); | |
54 | ||
55 | /** | |
56 | * Search repositories. | |
57 | * | |
58 | * @param keywords The search keywords | |
59 | * @param sort The sort field | |
60 | * @param order The sort order | |
61 | * @return Repos | |
62 | * @throws IOException If there is any I/O problem | |
63 | * @see <a href="http://developer.github.com/v3/search/#search-repositories">Search repositories</a> | |
64 | */ | |
65 | Iterable<Repo> repos( | |
66 | String keywords, | |
67 | String sort, | |
68 | Order order | |
69 | ) throws IOException; | |
70 | ||
71 | /** | |
72 | * Search issues. | |
73 | * | |
74 | * @param keywords The search keywords | |
75 | * @param sort The sort field | |
76 | * @param order The sort order | |
77 | * @param qualifiers The search qualifier | |
78 | * @return Issues | |
79 | * @throws IOException If there is any I/O problem | |
80 | * @see <a href="http://developer.github.com/v3/search/#search-issues">Search issues</a> | |
81 | * @checkstyle ParameterNumberCheck (7 lines) | |
82 | */ | |
83 | Iterable<Issue> issues( | |
84 | String keywords, | |
85 | String sort, | |
86 | Order order, | |
87 | EnumMap<Qualifier, String> qualifiers) | |
88 | throws IOException; | |
89 | ||
90 | /** | |
91 | * Search users. | |
92 | * | |
93 | * @param keywords The search keywords | |
94 | * @param sort The sort field | |
95 | * @param order The sort order | |
96 | * @return Users | |
97 | * @throws IOException If there is any I/O problem | |
98 | * @see <a href="http://developer.github.com/v3/search/#search-users">Search users</a> | |
99 | */ | |
100 | Iterable<User> users( | |
101 | String keywords, | |
102 | String sort, | |
103 | Order order) | |
104 | throws IOException; | |
105 | ||
106 | /** | |
107 | * Search code. | |
108 | * | |
109 | * @param keywords The search keywords | |
110 | * @param sort The sort field | |
111 | * @param order The sort order | |
112 | * @return Contents | |
113 | * @throws IOException If there is any I/O problem | |
114 | * @see <a href="http://developer.github.com/v3/search/#search-code">Search code</a> | |
115 | */ | |
116 | Iterable<Content> codes( | |
117 | String keywords, | |
118 | String sort, | |
119 | Order order) | |
120 | throws IOException; | |
121 | ||
122 | 2 | enum Qualifier implements StringEnum { |
123 | /** | |
124 | * The search by issues or pull request only. | |
125 | */ | |
126 | 1 | TYPE("type"), |
127 | /** | |
128 | * Qualifies which fields are searched. | |
129 | * <p>With this qualifier you can restrict the search to just | |
130 | * the title, body, comments, or any combination of these.</p> | |
131 | */ | |
132 | 1 | IN("in"), |
133 | /** | |
134 | * Finds issues created by a certain user. | |
135 | */ | |
136 | 1 | AUTHOR("author"), |
137 | /** | |
138 | * Finds issues that are assigned to a certain user. | |
139 | */ | |
140 | 1 | ASSIGNEE("assignee"), |
141 | /** | |
142 | * Finds issues that mention a certain user. | |
143 | */ | |
144 | 1 | MENTIONS("mentions"), |
145 | /** | |
146 | * Finds issues that a certain user commented on. | |
147 | */ | |
148 | 1 | COMMENTER("commenter"), |
149 | /** | |
150 | * Finds issues that were either created by a certain user. | |
151 | * <p>Or assigned to that user, mention that user, | |
152 | * or were commented on by that user.</p> | |
153 | */ | |
154 | 1 | INVOLVES("involves"), |
155 | /** | |
156 | * Finds issues or pull requests which mention a particular team within | |
157 | * an organization which the user is a member of. | |
158 | */ | |
159 | 1 | TEAM("team"), |
160 | /** | |
161 | * Filter issues based on whether they’re open or closed. | |
162 | */ | |
163 | 1 | STATE("state"), |
164 | /** | |
165 | * Filters issues based on their labels. | |
166 | */ | |
167 | 1 | LABEL("label"), |
168 | /** | |
169 | * Filters items missing certain metadata. | |
170 | */ | |
171 | 1 | NO("no"), |
172 | /** | |
173 | * Searches for issues within repositories matching a certain language. | |
174 | */ | |
175 | 1 | LANGUAGE("language"), |
176 | /** | |
177 | * Searches for items within repositories that match a certain state. | |
178 | */ | |
179 | 1 | IS("is"), |
180 | /** | |
181 | * Filters issues based on date of creation. | |
182 | */ | |
183 | 1 | CREATED("created"), |
184 | /** | |
185 | * Filters issues based on date last updated. | |
186 | */ | |
187 | 1 | UPDATED("updated"), |
188 | /** | |
189 | * Filters pull requests based on the date when they were merged. | |
190 | */ | |
191 | 1 | MERGED("merged"), |
192 | /** | |
193 | * Filters issues based on the date when they were closed. | |
194 | */ | |
195 | 1 | CLOSED("closed"), |
196 | /** | |
197 | * Filters issues based on the quantity of comments. | |
198 | */ | |
199 | 1 | COMMENTS("comments"), |
200 | /** | |
201 | * Limits searches to a specific user. | |
202 | */ | |
203 | 1 | USER("user"), |
204 | /** | |
205 | * Limits searches to a specific repository. | |
206 | */ | |
207 | 1 | REPO("repo"); |
208 | ||
209 | /** | |
210 | * Search qualifier. | |
211 | */ | |
212 | private final transient String qualifier; | |
213 | ||
214 | /** | |
215 | * Ctor. | |
216 | * @param key Search qualifier | |
217 | */ | |
218 | 20 | Qualifier(final String key) { |
219 | 20 | this.qualifier = key; |
220 | 20 | } |
221 | ||
222 | /** | |
223 | * Get search qualifier. | |
224 | * @return String | |
225 | */ | |
226 | @Override | |
227 | public String identifier() { | |
228 | 0 | return this.qualifier; |
229 | } | |
230 | } | |
231 | ||
232 | 1 | enum Order implements StringEnum { |
233 | /** | |
234 | * Sorting ascending. | |
235 | */ | |
236 | 1 | ASC("asc"), |
237 | /** | |
238 | * Sorting descending. | |
239 | */ | |
240 | 1 | DESC("desc"); |
241 | ||
242 | /** | |
243 | * The sort order. | |
244 | */ | |
245 | private final transient String order; | |
246 | ||
247 | /** | |
248 | * Ctor. | |
249 | * @param key The sort order | |
250 | */ | |
251 | 2 | Order(final String key) { |
252 | 2 | this.order = key; |
253 | 2 | } |
254 | ||
255 | /** | |
256 | * Get sort order. | |
257 | * @return String | |
258 | */ | |
259 | @Override | |
260 | public String identifier() { | |
261 | 5 | return this.order; |
262 | } | |
263 | } | |
264 | } |