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