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