1 /** 2 * Copyright (c) 2013-2023, 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.util.EnumMap; 34 35 /** 36 * Github search. 37 * 38 * @author Carlos Miranda (miranda.cma@gmail.com) 39 * @version $Id: 29aefcbb7aeaf41c02d28f921743b04e0e1cd75a $ 40 * @since 0.8 41 * @see <a href="https://developer.github.com/v3/search/">Search API</a> 42 */ 43 @Immutable 44 @SuppressWarnings("PMD.AvoidDuplicateLiterals") 45 public interface Search { 46 47 /** 48 * Github we're in. 49 * 50 * @return Github 51 */ 52 Github github(); 53 54 /** 55 * Search repositories. 56 * 57 * @param keywords The search keywords 58 * @param sort The sort field 59 * @param order The sort order 60 * @return Repos 61 * @see <a href="https://developer.github.com/v3/search/#search-repositories">Search repositories</a> 62 */ 63 Iterable<Repo> repos( 64 String keywords, 65 String sort, 66 Order order 67 ); 68 69 /** 70 * Search issues. 71 * 72 * @param keywords The search keywords 73 * @param sort The sort field 74 * @param order The sort order 75 * @param qualifiers The search qualifier 76 * @return Issues 77 * @see <a href="https://developer.github.com/v3/search/#search-issues">Search issues</a> 78 * @checkstyle ParameterNumberCheck (7 lines) 79 */ 80 Iterable<Issue> issues( 81 String keywords, 82 String sort, 83 Order order, 84 EnumMap<Qualifier, String> qualifiers); 85 86 /** 87 * Search users. 88 * 89 * @param keywords The search keywords 90 * @param sort The sort field 91 * @param order The sort order 92 * @return Users 93 * @see <a href="https://developer.github.com/v3/search/#search-users">Search users</a> 94 */ 95 Iterable<User> users( 96 String keywords, 97 String sort, 98 Order order); 99 100 /** 101 * Search code. 102 * 103 * @param keywords The search keywords 104 * @param sort The sort field 105 * @param order The sort order 106 * @return Contents 107 * @see <a href="https://developer.github.com/v3/search/#search-code">Search code</a> 108 */ 109 Iterable<Content> codes( 110 String keywords, 111 String sort, 112 Order order); 113 114 enum Qualifier implements StringEnum { 115 /** 116 * The search by issues or pull request only. 117 */ 118 TYPE("type"), 119 /** 120 * Qualifies which fields are searched. 121 * <p>With this qualifier you can restrict the search to just 122 * the title, body, comments, or any combination of these.</p> 123 */ 124 IN("in"), 125 /** 126 * Finds issues created by a certain user. 127 */ 128 AUTHOR("author"), 129 /** 130 * Finds issues that are assigned to a certain user. 131 */ 132 ASSIGNEE("assignee"), 133 /** 134 * Finds issues that mention a certain user. 135 */ 136 MENTIONS("mentions"), 137 /** 138 * Finds issues that a certain user commented on. 139 */ 140 COMMENTER("commenter"), 141 /** 142 * Finds issues that were either created by a certain user. 143 * <p>Or assigned to that user, mention that user, 144 * or were commented on by that user.</p> 145 */ 146 INVOLVES("involves"), 147 /** 148 * Finds issues or pull requests which mention a particular team within 149 * an organization which the user is a member of. 150 */ 151 TEAM("team"), 152 /** 153 * Filter issues based on whether they’re open or closed. 154 */ 155 STATE("state"), 156 /** 157 * Filters issues based on their labels. 158 */ 159 LABEL("label"), 160 /** 161 * Filters items missing certain metadata. 162 */ 163 NO("no"), 164 /** 165 * Searches for issues within repositories matching a certain language. 166 */ 167 LANGUAGE("language"), 168 /** 169 * Searches for items within repositories that match a certain state. 170 */ 171 IS("is"), 172 /** 173 * Filters issues based on date of creation. 174 */ 175 CREATED("created"), 176 /** 177 * Filters issues based on date last updated. 178 */ 179 UPDATED("updated"), 180 /** 181 * Filters pull requests based on the date when they were merged. 182 */ 183 MERGED("merged"), 184 /** 185 * Filters issues based on the date when they were closed. 186 */ 187 CLOSED("closed"), 188 /** 189 * Filters issues based on the quantity of comments. 190 */ 191 COMMENTS("comments"), 192 /** 193 * Limits searches to a specific user. 194 */ 195 USER("user"), 196 /** 197 * Limits searches to a specific repository. 198 */ 199 REPO("repo"); 200 201 /** 202 * Search qualifier. 203 */ 204 private final transient String qualifier; 205 206 /** 207 * Ctor. 208 * @param key Search qualifier 209 */ 210 Qualifier(final String key) { 211 this.qualifier = key; 212 } 213 214 /** 215 * Get search qualifier. 216 * @return String 217 */ 218 @Override 219 public String identifier() { 220 return this.qualifier; 221 } 222 } 223 224 enum Order implements StringEnum { 225 /** 226 * Sorting ascending. 227 */ 228 ASC("asc"), 229 /** 230 * Sorting descending. 231 */ 232 DESC("desc"); 233 234 /** 235 * The sort order. 236 */ 237 private final transient String order; 238 239 /** 240 * Ctor. 241 * @param key The sort order 242 */ 243 Order(final String key) { 244 this.order = key; 245 } 246 247 /** 248 * Get sort order. 249 * @return String 250 */ 251 @Override 252 public String identifier() { 253 return this.order; 254 } 255 } 256 }