Implement "List Branches" API

src/main/java/com/jcabi/github/Branch.java

@@ -0,0 +1,65 @@
+/**
+ * Copyright (c) 2013-2015, 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 javax.validation.constraints.NotNull;
+
+/**
+ * Git branch.
+ *
+ * @author Chris Rebert ([email protected])
+ * @version $Id$
+ * @since 0.24
+ * @see <a href="https://developer.github.com/v3/repos/#list-branches">List Branches API</a>
+ */
+@Immutable
+public interface Branch {
+    /**
+     * The repo we're in.
+     * @return Repo
+     */
+    @NotNull(message = "repo is never NULL")
+    Repo repo();
+
+    /**
+     * Name of the branch.
+     * @return Branch name
+     */
+    @NotNull(message = "name is never NULL")
+    String name();
+
+    /**
+     * Commit that the branch currently points to.
+     * @return Commit the branch currently points to
+     */
+    @NotNull(message = "commit is never NULL")
+    Commit commit();
+}

src/main/java/com/jcabi/github/Branches.java

@@ -0,0 +1,59 @@
+/**
+ * Copyright (c) 2013-2015, 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 javax.validation.constraints.NotNull;
+
+/**
+ * Git branches.
+ *
+ * @author Chris Rebert ([email protected])
+ * @version $Id$
+ * @since 0.24
+ * @see <a href="https://developer.github.com/v3/repos/#list-branches">List Branches API</a>
+ */
+@Immutable
+public interface Branches {
+    /**
+     * Repo which the branches are in.
+     * @return Repo
+     */
+    @NotNull(message = "repository is never NULL")
+    Repo repo();
+
+    /**
+     * Iterate over all branches in the repo.
+     * @return Iterator of branches
+     * @see <a href="https://developer.github.com/v3/repos/#list-branches">List Branches API</a>
+     */
+    @NotNull(message = "iterable is never NULL")
+    Iterable<Branch> iterate();
+}

src/main/java/com/jcabi/github/Repo.java

@@ -45,7 +45,7 @@
  * @since 0.1
  */
 @Immutable
-@SuppressWarnings("PMD.TooManyMethods")
+@SuppressWarnings({ "PMD.TooManyMethods", "PMD.ExcessivePublicCount" })
 public interface Repo extends JsonReadable, JsonPatchable, Comparable<Repo> {
 
     /**
@@ -148,6 +148,14 @@ public interface Repo extends JsonReadable, JsonPatchable, Comparable<Repo> {
     @NotNull(message = "RepoCommits are never NULL")
     RepoCommits commits();
 
+    /**
+     * Get repository's branches.
+     * @return Branches
+     * @see <a href="https://developer.github.com/v3/repos/#list-branches">List Branches API</a>
+     */
+    @NotNull(message = "Branches are never NULL")
+    Branches branches();
+
     /**
      * Get all contents of the repo.
      * @return Contents
@@ -346,6 +354,11 @@ public RepoCommits commits() {
             return this.repo.commits();
         }
         @Override
+        @NotNull(message = "branches is never NULL")
+        public Branches branches() {
+            return this.repo.branches();
+        }
+        @Override
         @NotNull(message = "JSON is never NULL")
         public JsonObject json() throws IOException {
             return this.repo.json();

src/main/java/com/jcabi/github/RtBranch.java

@@ -0,0 +1,107 @@
+/**
+ * Copyright (c) 2013-2015, 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.aspects.Loggable;
+import com.jcabi.http.Request;
+import javax.validation.constraints.NotNull;
+import lombok.EqualsAndHashCode;
+
+/**
+ * Git branch.
+ *
+ * @author Chris Rebert ([email protected])
+ * @version $Id$
+ * @since 0.24
+ */
+@Immutable
+@Loggable(Loggable.DEBUG)
+@EqualsAndHashCode(of = { "entry", "owner", "nam", "hash" })
+public final class RtBranch implements Branch {
+    /**
+     * API entry point.
+     */
+    private final transient Request entry;
+
+    /**
+     * Repository we're in.
+     */
+    private final transient Repo owner;
+
+    /**
+     * Name of this branch.
+     */
+    private final transient String nam;
+
+    /**
+     * Commit SHA hash.
+     */
+    private final transient String hash;
+
+    /**
+     * Public ctor.
+     * @param req Request
+     * @param repo Repository
+     * @param nom Name of branch
+     * @param sha Commit SHA hash
+     * @todo #1085:30m Refactor to reduce number of arguments to avoid
+     *  ParameterNumberCheck warning.
+     * @checkstyle ParameterNumberCheck (6 lines)
+     */
+    RtBranch(
+        final Request req,
+        final Repo repo,
+        final String nom,
+        final String sha) {
+        this.entry = req;
+        this.owner = repo;
+        this.nam = nom;
+        this.hash = sha;
+    }
+
+    @Override
+    @NotNull(message = "repo is never NULL")
+    public Repo repo() {
+        return this.owner;
+    }
+
+    @Override
+    @NotNull(message = "name is never NULL")
+    public String name() {
+        return this.nam;
+    }
+
+    @Override
+    @NotNull(message = "commit is never NULL")
+    public Commit commit() {
+        return new RtCommit(this.entry, this.owner, this.hash);
+    }
+}

src/main/java/com/jcabi/github/RtBranches.java

@@ -0,0 +1,106 @@
+/**
+ * Copyright (c) 2013-2015, 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.aspects.Loggable;
+import com.jcabi.http.Request;
+import javax.json.JsonObject;
+import javax.validation.constraints.NotNull;
+import lombok.EqualsAndHashCode;
+
+/**
+ * Git branches.
+ *
+ * @author Chris Rebert ([email protected])
+ * @version $Id$
+ * @since 0.24
+ */
+@Immutable
+@Loggable(Loggable.DEBUG)
+@EqualsAndHashCode(of = {"entry", "request", "owner" })
+final class RtBranches implements Branches {
+    /**
+     * RESTful API entry point.
+     */
+    private final transient Request entry;
+
+    /**
+     * RESTful request for the branches.
+     */
+    private final transient Request request;
+
+    /**
+     * Parent repository.
+     */
+    private final transient Repo owner;
+
+    /**
+     * Public ctor.
+     * @param req Entry point of API
+     * @param repo Repository
+     */
+    RtBranches(final Request req, final Repo repo) {
+        this.entry = req;
+        this.owner = repo;
+        final Coordinates coords = repo.coordinates();
+        this.request = this.entry.uri()
+            .path("/repos")
+            .path(coords.user())
+            .path(coords.repo())
+            .path("/branches")
+            .back();
+    }
+
+    @Override
+    @NotNull(message = "repository is never NULL")
+    public Repo repo() {
+        return this.owner;
+    }
+
+    @Override
+    @NotNull(message = "iterable is never NULL")
+    public Iterable<Branch> iterate() {
+        return new RtPagination<Branch>(
+            this.request,
+            new RtValuePagination.Mapping<Branch, JsonObject>() {
+                @Override
+                public Branch map(final JsonObject object) {
+                    return new RtBranch(
+                        RtBranches.this.entry,
+                        RtBranches.this.owner,
+                        object.getString("name"),
+                        object.getJsonObject("commit").getString("sha")
+                    );
+                }
+            }
+        );
+    }
+}

src/main/java/com/jcabi/github/RtRepo.java

@@ -239,6 +239,12 @@ public RepoCommits commits() {
         return new RtRepoCommits(this.entry, this);
     }
 
+    @Override
+    @NotNull(message = "Branches is never NULL")
+    public Branches branches() {
+        return new RtBranches(this.entry, this);
+    }
+
     @Override
     @NotNull(message = "JSON is never NULL")
     public JsonObject json() throws IOException {