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