Coverage Report - com.jcabi.github.Issues
 
Classes in this File Line Coverage Branch Coverage Complexity
Issues
N/A
N/A
1
Issues$Qualifier
92%
12/13
N/A
1
Issues$Sort
100%
9/9
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 java.util.Map;
 36  
 import javax.validation.constraints.NotNull;
 37  
 
 38  
 /**
 39  
  * Github issues.
 40  
  *
 41  
  * @author Yegor Bugayenko (yegor@tpc2.com)
 42  
  * @author Chris Rebert (github@chrisrebert.com)
 43  
  * @version $Id$
 44  
  * @since 0.1
 45  
  * @see <a href="http://developer.github.com/v3/issues/">Issues API</a>
 46  
  */
 47  
 @Immutable
 48  
 public interface Issues {
 49  
 
 50  
     /**
 51  
      * Owner of them.
 52  
      * @return Repo
 53  
      */
 54  
     @NotNull(message = "repository is never NULL")
 55  
     Repo repo();
 56  
 
 57  
     /**
 58  
      * Get specific issue by number.
 59  
      * @param number Issue number
 60  
      * @return Issue
 61  
      * @see <a href="http://developer.github.com/v3/issues/#get-a-single-issue">Get a Single Issue</a>
 62  
      */
 63  
     @NotNull(message = "issue is never NULL")
 64  
     Issue get(int number);
 65  
 
 66  
     /**
 67  
      * Create new issue.
 68  
      * @param title Title
 69  
      * @param body Body of it
 70  
      * @return Issue just created
 71  
      * @throws IOException If there is any I/O problem
 72  
      * @see <a href="http://developer.github.com/v3/issues/#create-an-issue">Create an Issue</a>
 73  
      */
 74  
     @NotNull(message = "issue is never NULL")
 75  
     Issue create(
 76  
         @NotNull(message = "issue title is never NULL") String title,
 77  
         @NotNull(message = "issue body is never NULL") String body)
 78  
         throws IOException;
 79  
 
 80  
     /**
 81  
      * Iterate them all.
 82  
      * @param params Iterating parameters, as requested by API
 83  
      * @return Iterator of issues
 84  
      * @see <a href="http://developer.github.com/v3/issues/#list-issues">List Issues</a>
 85  
      */
 86  
     @NotNull(message = "iterable is never NULL")
 87  
     Iterable<Issue> iterate(@NotNull(message = "map of params can't be NULL")
 88  
         Map<String, String> params);
 89  
 
 90  
     /**
 91  
      * Search for issues within the given repository.
 92  
      *
 93  
      * @param sort The sort field
 94  
      * @param direction The sort direction
 95  
      * @param qualifiers The search qualifier
 96  
      * @return Issues
 97  
      * @throws java.io.IOException If there is any I/O problem
 98  
      * @since 0.22.0
 99  
      * @see <a href="https://developer.github.com/v3/issues/#list-issues-for-a-repository">List issues for a repository</a>
 100  
      */
 101  
     @NotNull(message = "Iterable of issues is never NULL")
 102  
     Iterable<Issue> search(
 103  
         @NotNull(message = "Sort field can't be NULL") Sort sort,
 104  
         @NotNull(message = "Sort direction can't be NULL")
 105  
         Search.Order direction,
 106  
         @NotNull(message = "Search qualifiers can't be NULL")
 107  
         EnumMap<Qualifier, String> qualifiers)
 108  
         throws IOException;
 109  
 
 110  2
     enum Qualifier implements StringEnum {
 111  
         /**
 112  
          * Filter issues based on which milestone they are assigned to.
 113  
          * "none" means no assigned milestone. "*" means any milestone.
 114  
          */
 115  1
         MILESTONE("milestone"),
 116  
         /**
 117  
          * Filter issues based on whether they're open or closed.
 118  
          */
 119  1
         STATE("state"),
 120  
         /**
 121  
          * Finds issues that are assigned to a certain user.
 122  
          * "none" means no assigned user. "*" means assigned to any user.
 123  
          */
 124  1
         ASSIGNEE("assignee"),
 125  
         /**
 126  
          * Finds issues created by a certain user.
 127  
          */
 128  1
         CREATOR("creator"),
 129  
         /**
 130  
          * Finds issues that mention a certain user.
 131  
          */
 132  1
         MENTIONED("mentioned"),
 133  
         /**
 134  
          * Filters issues based on their labels,
 135  
          * as a comma-separated list of label names.
 136  
          * An issue must have all of the labels in the list in order to
 137  
          * appear in the search results.
 138  
          */
 139  1
         LABELS("labels"),
 140  
         /**
 141  
          * Filters issues based on date last updated (as an ISO 8601 timestamp).
 142  
          */
 143  1
         SINCE("since");
 144  
 
 145  
         /**
 146  
          * Search qualifier.
 147  
          */
 148  
         private final transient String qualifier;
 149  
 
 150  
         /**
 151  
          * Ctor.
 152  
          * @param key Search qualifier
 153  
          */
 154  7
         Qualifier(final String key) {
 155  7
             this.qualifier = key;
 156  7
         }
 157  
 
 158  
         /**
 159  
          * Get search qualifier.
 160  
          * @return String
 161  
          */
 162  
         @Override
 163  
         @NotNull(message = "identifier string is never NULL")
 164  
         public String identifier() {
 165  0
             return this.qualifier;
 166  
         }
 167  
     }
 168  
 
 169  1
     enum Sort implements StringEnum {
 170  
         /**
 171  
          * Issue creation timestamp.
 172  
          */
 173  1
         CREATED("created"),
 174  
         /**
 175  
          * Issue last updated timestamp.
 176  
          */
 177  1
         UPDATED("updated"),
 178  
         /**
 179  
          * Number of comments on the issue.
 180  
          */
 181  1
         COMMENTS("comments");
 182  
 
 183  
         /**
 184  
          * Search results sort field.
 185  
          */
 186  
         private final transient String sort;
 187  
 
 188  
         /**
 189  
          * Ctor.
 190  
          * @param field Search results sort field
 191  
          */
 192  3
         Sort(final String field) {
 193  3
             this.sort = field;
 194  3
         }
 195  
 
 196  
         /**
 197  
          * Get search results sort field.
 198  
          * @return String
 199  
          */
 200  
         @Override
 201  
         @NotNull(message = "identifier string is never NULL")
 202  
         public String identifier() {
 203  1
             return this.sort;
 204  
         }
 205  
     }
 206  
 }