Adding ref parameter on SearchAPI on projects (#544) (#545)

src/main/java/org/gitlab4j/api/SearchApi.java

@@ -208,9 +208,29 @@ public class SearchApi extends AbstractApi {
      * @since GitLab 10.5
      */
     public List<?> projectSearch(Object projectIdOrPath, ProjectSearchScope scope, String search) throws GitLabApiException {
-        return (projectSearch(projectIdOrPath, scope, search, this.getDefaultPerPage()).all());
+        return (projectSearch(projectIdOrPath, scope, search, null, this.getDefaultPerPage()).all());
     }
 
+    /**
+     * Search within the specified project.  If a user is not a member of a project and the project is private,
+     * a request on that project will result to a 404 status code.
+     *
+     * <pre><code>GitLab Endpoint: POST /projects/:projectId/search?scope=:scope&amp;search=:search-query&amp;ref=ref</code></pre>
+     *
+     * @param projectIdOrPath the project in the form of an Integer(ID), String(path), or Project instance, required
+     * @param scope search the expression within the specified scope. Currently these scopes are supported:
+     *               issues, merge_requests, milestones, notes, wiki_blobs, commits, blobs, users
+     * @param search the search query
+     * @param ref the name of a repository branch or tag to search on. The project’s default branch is used by 
+     *             default. This is only applicable for scopes: commits, blobs, and wiki_blobs.
+     * @return a List containing the object type specified by the scope
+     * @throws GitLabApiException if any exception occurs
+     * @since GitLab 10.5
+     */
+    public List<?> projectSearch(Object projectIdOrPath, ProjectSearchScope scope, String search, String ref) throws GitLabApiException {
+        return (projectSearch(projectIdOrPath, scope, search, ref, this.getDefaultPerPage()).all());
+    }
+    
     /**
      * Search within the specified project.  If a user is not a member of a project and the project is private,
      * a request on that project will result to a 404 status code.
@@ -226,9 +246,30 @@ public class SearchApi extends AbstractApi {
      * @since GitLab 10.5
      */
     public Stream<?> projectSearchStream(Object projectIdOrPath, ProjectSearchScope scope, String search) throws GitLabApiException {
-        return (projectSearch(projectIdOrPath, scope, search, getDefaultPerPage()).stream());
+        return (projectSearch(projectIdOrPath, scope, search, null, getDefaultPerPage()).stream());
+    }
+
+    /**
+     * Search within the specified project.  If a user is not a member of a project and the project is private,
+     * a request on that project will result to a 404 status code.
+     *
+     * <pre><code>GitLab Endpoint: POST /projects/:projectId/search?scope=:scope&amp;search=:search-query&amp;ref=ref</code></pre>
+     *
+     * @param projectIdOrPath the project in the form of an Integer(ID), String(path), or Project instance, required
+     * @param scope search the expression within the specified scope. Currently these scopes are supported:
+     *               issues, merge_requests, milestones, notes, wiki_blobs, commits, blobs, users
+     * @param search the search query
+     * @param ref the name of a repository branch or tag to search on. The project’s default branch is used by 
+     *             default. This is only applicable for scopes: commits, blobs, and wiki_blobs.
+     * @return a Stream containing the object type specified by the scope
+     * @throws GitLabApiException if any exception occurs
+     * @since GitLab 10.5
+     */
+    public Stream<?> projectSearchStream(Object projectIdOrPath, ProjectSearchScope scope, String search, String ref) throws GitLabApiException {
+        return (projectSearch(projectIdOrPath, scope, search, ref, getDefaultPerPage()).stream());
     }
 
+
     /**
      * Search within the specified project.  If a user is not a member of a project and the project is private,
      * a request on that project will result to a 404 status code.
@@ -245,10 +286,39 @@ public class SearchApi extends AbstractApi {
      * @since GitLab 10.5
      */
     public Pager<?> projectSearch(Object projectIdOrPath, ProjectSearchScope scope, String search, int itemsPerPage) throws GitLabApiException {
+        return projectSearch(projectIdOrPath, scope, search, null, itemsPerPage);
+    }
+
+    
+    /**
+     * Search within the specified project.  If a user is not a member of a project and the project is private,
+     * a request on that project will result to a 404 status code.
+     *
+     * <pre><code>GitLab Endpoint: POST /project/:projectId/search?scope=:scope&amp;search=:search-query&amp;ref=ref</code></pre>
+     *
+     * @param projectIdOrPath the project in the form of an Integer(ID), String(path), or Project instance, required
+     * @param scope search the expression within the specified scope. Currently these scopes are supported:
+     *               issues, merge_requests, milestones, notes, wiki_blobs, commits, blobs, users
+     * @param search the search query
+     * @param ref the name of a repository branch or tag to search on. The project’s default branch is used by 
+     *             default. This is only applicable for scopes: commits, blobs, and wiki_blobs.
+     * @param itemsPerPage the number of items that will be fetched per page
+     * @return a Pager containing the object type specified by the scope
+     * @throws GitLabApiException if any exception occurs
+     * @since GitLab 10.5
+     */
+    public Pager<?> projectSearch(Object projectIdOrPath, ProjectSearchScope scope, String search, String ref, int itemsPerPage) throws GitLabApiException {
 
         GitLabApiForm formData = new GitLabApiForm()
                 .withParam("scope", scope, true)
-                .withParam("search", search, true);
+                .withParam("search", search, true)
+                .withParam("ref", ref, false);
+        
+        if (ref != null) {
+            if (!scope.equals(ProjectSearchScope.BLOBS) && !scope.equals(ProjectSearchScope.WIKI_BLOBS) && !scope.equals(ProjectSearchScope.COMMITS)) {
+                throw new GitLabApiException("Ref parameter is only applicable for scopes: commits, blobs, and wiki_blobs");
+            }
+        }
 
         switch (scope) {
             case BLOBS: