Coverage Report

Coverage Report - com.jcabi.github.Github

Classes in this File

Line Coverage

Branch Coverage

100%

17/17

66%

4/6

 /**
  * Copyright (c) 2013-2017, jcabi.com
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
  * are met: 1) Redistributions of source code must retain the above
  * copyright notice, this list of conditions and the following
  * disclaimer. 2) Redistributions in binary form must reproduce the above
  * copyright notice, this list of conditions and the following
  * disclaimer in the documentation and/or other materials provided
  * with the distribution. 3) Neither the name of the jcabi.com nor
  * the names of its contributors may be used to endorse or promote
  * products derived from this software without specific prior written
  * permission.
  *
  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT
  * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
  * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
  * THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  * OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 package com.jcabi.github;
 
 import com.jcabi.aspects.Immutable;
 import com.jcabi.http.Request;
 import java.io.IOException;
 import java.text.DateFormat;
 import java.text.ParseException;
 import java.text.SimpleDateFormat;
 import java.util.Date;
 import java.util.Locale;
 import java.util.TimeZone;
 import javax.json.JsonObject;
 import lombok.EqualsAndHashCode;
 
 /**
  * Github client, starting point to the entire library.
  *
  * <p>This is how you start communicating with Github API:
  *
  * <pre> Github github = new RtGithub(oauthKey);
  * Repo repo = github.repos().get(
  *     new Coordinates.Simple("jcabi/jcabi-github")
  * );
  * Issues issues = repo.issues();
  * Issue issue = issues.post("issue title", "issue body");</pre>
  *
  * <p>It is strongly recommended to use
  * {@link com.jcabi.http.wire.RetryWire} to avoid
  * accidental I/O exceptions:
  *
  * <pre> Github github = new RtGithub(
  *   new RtGithub(oauthKey)
  *     .entry()
  *     .through(RetryWire.class)
  * );</pre>
  *
  * <p>The interfaces in this packages are trying to cover as much
  * as possible of Github API. However, there are parts of API that are
  * rarely used and making Java classes for them is not an effective
  * idea. That's why {@code Github} class has {@link #entry()} method,
  * which returns an entry point to the RESTful API. For example, you
  * want to use
  * <a href="http://developer.github.com/v3/search/#search-repositories">"Search
  * Repositories"</a> feature of Github:
  *
  * <pre> Github github = new RtGithub(oauthKey);
  * int found = github.entry()
  *   .uri().path("/search/repositories").back()
  *   .method(Request.GET)
  *   .fetch()
  *   .as(JsonResponse.class)
  *   .getJsonObject()
  *   .getNumber("total_count")
  *   .intValue();</pre>
  * @author Yegor Bugayenko (yegor@tpc2.com)
  * @version $Id: c94697acdfafbba73237b1560132fe8e887cbd37 $
  * @since 0.1
  */
 @Immutable
 @SuppressWarnings("PMD.TooManyMethods")
 public interface Github {
 
     /**
      * RESTful request, an entry point to the Github API.
      * @return Request
      */
     Request entry();
 
     /**
      * Get repositories.
      * @return Repositories
      */
     Repos repos();
 
     /**
      * Get Gists API entry point.
      * @return Gists API entry point
      */
     Gists gists();
 
     /**
      * Get Users API entry point.
      * @return Users API entry point
      * @since 0.4
      */
     Users users();
 
     /**
      * Get Organizations API entry point.
      * @return Organizations API entry point
      * @since 0.24
      */
     Organizations organizations();
 
     /**
      * Get Markdown API entry point.
      * @return Markdown API entry point
      * @since 0.6
      */
     Markdown markdown();
 
     /**
      * Rate limit API entry point.
      * @return Rate limit API
      * @since 0.6
      */
     Limits limits();
 
     /**
      * Search API entry point.
      * @return Search API
      * @since 0.8
      */
     Search search();
 
     /**
      * Get gitignores.
      * @return Gitignotes API
      * @throws IOException If there is any I/O problem
      * @see <a href="http://developer.github.com/v3/gitignore/">Gitignore API</a>
      * @since 0.8
      */
     Gitignores gitignores() throws IOException;
 
     /**
      * Get meta information.
      * @return JSON with meta
      * @throws IOException If there is any I/O problem
      * @see <a href="http://developer.github.com/v3/meta/">Meta API</a>
      * @since 0.6
      */
     JsonObject meta() throws IOException;
 
     /**
      * Get emojis.
      * @return JSON with emojis
      * @throws IOException If there is any I/O problem
      * @see <a href="http://developer.github.com/v3/emojis/">Emojis API</a>
      * @since 0.6
      */
     JsonObject emojis() throws IOException;
 
     /**
      * Time in Github JSON.
      * @see <a href="http://developer.github.com/v3/#schema">Schema</a>
      * @since 0.2
      */
     @Immutable
     @EqualsAndHashCode(of = { "msec" })
     final class Time {
         /**
          * Pattern to present day in ISO-8601.
          */
         public static final String FORMAT_ISO = "yyyy-MM-dd'T'HH:mm:ss'Z'";
         /**
          * The time zone we're in.
          */
         public static final TimeZone TIMEZONE = TimeZone.getTimeZone("UTC");
         /**
          * Encapsulated time in milliseconds.
          */
         private final transient long msec;
 
         /**
          * Ctor.
          */
         public Time() {
             this(new Date());
         }
 
         /**
          * Ctor.
          * @param text ISO date/time
          * @throws ParseException If fails
          */
         public Time(final String text) throws ParseException {
             this(Github.Time.format().parse(text));
         }
 
         /**
          * Ctor.
          * @param date Date to encapsulate
          */
         public Time(final Date date) {
             this(date.getTime());
         }
 
         /**
          * Ctor.
          * @param millis Milliseconds
          */
         public Time(final long millis) {
             this.msec = millis;
         }
 
         @Override
         public String toString() {
             return Github.Time.format().format(this.date());
         }
 
         /**
          * Get date.
          * @return Date
          */
         public Date date() {
             return new Date(this.msec);
         }
 
         /**
          * Make format.
          * @return Date format
          */
         private static DateFormat format() {
             final DateFormat fmt = new SimpleDateFormat(
                 Github.Time.FORMAT_ISO, Locale.ENGLISH
             );
             fmt.setTimeZone(Github.Time.TIMEZONE);
             return fmt;
         }
     }
 
 }

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 com.jcabi.http.Request;
34		import java.io.IOException;
35		import java.text.DateFormat;
36		import java.text.ParseException;
37		import java.text.SimpleDateFormat;
38		import java.util.Date;
39		import java.util.Locale;
40		import java.util.TimeZone;
41		import javax.json.JsonObject;
42		import lombok.EqualsAndHashCode;
43
44		/**
45		* Github client, starting point to the entire library.
46		*
47		* <p>This is how you start communicating with Github API:
48		*
49		* <pre> Github github = new RtGithub(oauthKey);
50		* Repo repo = github.repos().get(
51		* new Coordinates.Simple("jcabi/jcabi-github")
52		* );
53		* Issues issues = repo.issues();
54		* Issue issue = issues.post("issue title", "issue body");</pre>
55		*
56		* <p>It is strongly recommended to use
57		* {@link com.jcabi.http.wire.RetryWire} to avoid
58		* accidental I/O exceptions:
59		*
60		* <pre> Github github = new RtGithub(
61		* new RtGithub(oauthKey)
62		* .entry()
63		* .through(RetryWire.class)
64		* );</pre>
65		*
66		* <p>The interfaces in this packages are trying to cover as much
67		* as possible of Github API. However, there are parts of API that are
68		* rarely used and making Java classes for them is not an effective
69		* idea. That's why {@code Github} class has {@link #entry()} method,
70		* which returns an entry point to the RESTful API. For example, you
71		* want to use
72		* <a href="http://developer.github.com/v3/search/#search-repositories">"Search
73		* Repositories"</a> feature of Github:
74		*
75		* <pre> Github github = new RtGithub(oauthKey);
76		* int found = github.entry()
77		* .uri().path("/search/repositories").back()
78		* .method(Request.GET)
79		* .fetch()
80		* .as(JsonResponse.class)
81		* .getJsonObject()
82		* .getNumber("total_count")
83		* .intValue();</pre>
84		* @author Yegor Bugayenko (yegor@tpc2.com)
85		* @version $Id: c94697acdfafbba73237b1560132fe8e887cbd37 $
86		* @since 0.1
87		*/
88		@Immutable
89		@SuppressWarnings("PMD.TooManyMethods")
90		public interface Github {
91
92		/**
93		* RESTful request, an entry point to the Github API.
94		* @return Request
95		*/
96		Request entry();
97
98		/**
99		* Get repositories.
100		* @return Repositories
101		*/
102		Repos repos();
103
104		/**
105		* Get Gists API entry point.
106		* @return Gists API entry point
107		*/
108		Gists gists();
109
110		/**
111		* Get Users API entry point.
112		* @return Users API entry point
113		* @since 0.4
114		*/
115		Users users();
116
117		/**
118		* Get Organizations API entry point.
119		* @return Organizations API entry point
120		* @since 0.24
121		*/
122		Organizations organizations();
123
124		/**
125		* Get Markdown API entry point.
126		* @return Markdown API entry point
127		* @since 0.6
128		*/
129		Markdown markdown();
130
131		/**
132		* Rate limit API entry point.
133		* @return Rate limit API
134		* @since 0.6
135		*/
136		Limits limits();
137
138		/**
139		* Search API entry point.
140		* @return Search API
141		* @since 0.8
142		*/
143		Search search();
144
145		/**
146		* Get gitignores.
147		* @return Gitignotes API
148		* @throws IOException If there is any I/O problem
149		* @see <a href="http://developer.github.com/v3/gitignore/">Gitignore API</a>
150		* @since 0.8
151		*/
152		Gitignores gitignores() throws IOException;
153
154		/**
155		* Get meta information.
156		* @return JSON with meta
157		* @throws IOException If there is any I/O problem
158		* @see <a href="http://developer.github.com/v3/meta/">Meta API</a>
159		* @since 0.6
160		*/
161		JsonObject meta() throws IOException;
162
163		/**
164		* Get emojis.
165		* @return JSON with emojis
166		* @throws IOException If there is any I/O problem
167		* @see <a href="http://developer.github.com/v3/emojis/">Emojis API</a>
168		* @since 0.6
169		*/
170		JsonObject emojis() throws IOException;
171
172		/**
173		* Time in Github JSON.
174		* @see <a href="http://developer.github.com/v3/#schema">Schema</a>
175		* @since 0.2
176		*/
177		@Immutable
178	4	@EqualsAndHashCode(of = { "msec" })
179		final class Time {
180		/**
181		* Pattern to present day in ISO-8601.
182		*/
183		public static final String FORMAT_ISO = "yyyy-MM-dd'T'HH:mm:ss'Z'";
184		/**
185		* The time zone we're in.
186		*/
187	1	public static final TimeZone TIMEZONE = TimeZone.getTimeZone("UTC");
188		/**
189		* Encapsulated time in milliseconds.
190		*/
191		private final transient long msec;
192
193		/**
194		* Ctor.
195		*/
196		public Time() {
197	463	this(new Date());
198	463	}
199
200		/**
201		* Ctor.
202		* @param text ISO date/time
203		* @throws ParseException If fails
204		*/
205		public Time(final String text) throws ParseException {
206	32	this(Github.Time.format().parse(text));
207	32	}
208
209		/**
210		* Ctor.
211		* @param date Date to encapsulate
212		*/
213		public Time(final Date date) {
214	495	this(date.getTime());
215	495	}
216
217		/**
218		* Ctor.
219		* @param millis Milliseconds
220		*/
221	499	public Time(final long millis) {
222	499	this.msec = millis;
223	499	}
224
225		@Override
226		public String toString() {
227	466	return Github.Time.format().format(this.date());
228		}
229
230		/**
231		* Get date.
232		* @return Date
233		*/
234		public Date date() {
235	492	return new Date(this.msec);
236		}
237
238		/**
239		* Make format.
240		* @return Date format
241		*/
242		private static DateFormat format() {
243	498	final DateFormat fmt = new SimpleDateFormat(
244		Github.Time.FORMAT_ISO, Locale.ENGLISH
245		);
246	496	fmt.setTimeZone(Github.Time.TIMEZONE);
247	496	return fmt;
248		}
249		}
250
251		}