Implement starring API

The starring API has changed:
https://developer.github.com/changes/2012-9-5-watcher-api/

This commit deprecates the old class WatcherService and adds the new
implementation StargazerService.

Change-Id: Ice276b27880f75bb7847140c1534c5fc2705865d
Signed-off-by: Jon Ander Peñalba <jonan88@gmail.com>
Signed-off-by: Matthias Sohn <matthias.sohn@sap.com>

3 files changed, 337 insertions, 2 deletions

diff --git a/org.eclipse.egit.github.core/src/org/eclipse/egit/github/core/client/IGitHubConstants.java b/org.eclipse.egit.github.core/src/org/eclipse/egit/github/core/client/IGitHubConstants.java
index eb0518b9..a902eeb5 100644
--- a/org.eclipse.egit.github.core/src/org/eclipse/egit/github/core/client/IGitHubConstants.java
+++ b/org.eclipse.egit.github.core/src/org/eclipse/egit/github/core/client/IGitHubConstants.java
@@ -162,6 +162,8 @@ public interface IGitHubConstants {
 	String SEGMENT_SHOW = "/show"; //$NON-NLS-1$
 	/** */
 	String SEGMENT_STAR = "/star"; //$NON-NLS-1$
+	/** @since 4.2 */
+	String SEGMENT_STARGAZERS = "/stargazers"; //$NON-NLS-1$
 	/** */
 	String SEGMENT_STARRED = "/starred"; //$NON-NLS-1$
 	/** */
diff --git a/org.eclipse.egit.github.core/src/org/eclipse/egit/github/core/service/StargazerService.java b/org.eclipse.egit.github.core/src/org/eclipse/egit/github/core/service/StargazerService.java
new file mode 100644
index 00000000..ce7dcd54
--- /dev/null
+++ b/org.eclipse.egit.github.core/src/org/eclipse/egit/github/core/service/StargazerService.java
@@ -0,0 +1,313 @@
+/******************************************************************************
+ *  Copyright (c) 2015 Jon Ander Peñalba
+ *  All rights reserved. This program and the accompanying materials
+ *  are made available under the terms of the Eclipse Public License v1.0
+ *  which accompanies this distribution, and is available at
+ *  http://www.eclipse.org/legal/epl-v10.html
+ *
+ *  Contributors:
+ *    Jon Ander Peñalba - initial API and implementation
+ *****************************************************************************/
+package org.eclipse.egit.github.core.service;
+
+import static org.eclipse.egit.github.core.client.IGitHubConstants.SEGMENT_REPOS;
+import static org.eclipse.egit.github.core.client.IGitHubConstants.SEGMENT_STARGAZERS;
+import static org.eclipse.egit.github.core.client.IGitHubConstants.SEGMENT_STARRED;
+import static org.eclipse.egit.github.core.client.IGitHubConstants.SEGMENT_USER;
+import static org.eclipse.egit.github.core.client.IGitHubConstants.SEGMENT_USERS;
+import static org.eclipse.egit.github.core.client.PagedRequest.PAGE_FIRST;
+import static org.eclipse.egit.github.core.client.PagedRequest.PAGE_SIZE;
+
+import java.io.IOException;
+import java.util.List;
+
+import org.eclipse.egit.github.core.IRepositoryIdProvider;
+import org.eclipse.egit.github.core.Repository;
+import org.eclipse.egit.github.core.User;
+import org.eclipse.egit.github.core.client.GitHubClient;
+import org.eclipse.egit.github.core.client.PageIterator;
+import org.eclipse.egit.github.core.client.PagedRequest;
+
+import com.google.gson.reflect.TypeToken;
+
+/**
+ * Service class for dealing with users starring GitHub repositories.
+ *
+ * @see <a href="https://developer.github.com/v3/activity/starring/">GitHub stargazer
+ *      API documentation</a>
+ * @since 4.2
+ */
+public class StargazerService extends GitHubService {
+
+	/**
+	 * Create stargazer service
+	 */
+	public StargazerService() {
+		super();
+	}
+
+	/**
+	 * Create stargazer service
+	 *
+	 * @param client
+	 */
+	public StargazerService(GitHubClient client) {
+		super(client);
+	}
+
+	/**
+	 * Create page stargazer request
+	 *
+	 * @param repository
+	 * @param start
+	 * @param size
+	 * @return request
+	 */
+	protected PagedRequest<User> createStargazerRequest(
+			IRepositoryIdProvider repository, int start, int size) {
+		String id = getId(repository);
+		PagedRequest<User> request = createPagedRequest(start, size);
+		StringBuilder uri = new StringBuilder(SEGMENT_REPOS);
+		uri.append('/').append(id);
+		uri.append(SEGMENT_STARGAZERS);
+		request.setUri(uri);
+		request.setType(new TypeToken<List<User>>() {
+		}.getType());
+		return request;
+	}
+
+	/**
+	 * Get users starring the given repository
+	 *
+	 * @param repository
+	 * @return non-null but possibly empty list of users
+	 * @throws IOException
+	 */
+	public List<User> getStargazers(IRepositoryIdProvider repository)
+			throws IOException {
+		PagedRequest<User> request = createStargazerRequest(repository,
+				PAGE_FIRST, PAGE_SIZE);
+		return getAll(request);
+	}
+
+	/**
+	 * Page stargazers of given repository
+	 *
+	 * @param repository
+	 * @return page iterator
+	 */
+	public PageIterator<User> pageStargazers(IRepositoryIdProvider repository) {
+		return pageStargazers(repository, PAGE_SIZE);
+	}
+
+	/**
+	 * Page stargazers of given repository
+	 *
+	 * @param repository
+	 * @param size
+	 * @return page iterator
+	 */
+	public PageIterator<User> pageStargazers(IRepositoryIdProvider repository,
+			int size) {
+		return pageStargazers(repository, PAGE_FIRST, size);
+	}
+
+	/**
+	 * Page stargazers of given repository
+	 *
+	 * @param repository
+	 * @param start
+	 * @param size
+	 * @return page iterator
+	 */
+	public PageIterator<User> pageStargazers(IRepositoryIdProvider repository,
+			int start, int size) {
+		PagedRequest<User> request = createStargazerRequest(repository, start,
+				size);
+		return createPageIterator(request);
+	}
+
+	/**
+	 * Create page starred request
+	 *
+	 * @param user
+	 * @param start
+	 * @param size
+	 * @return request
+	 */
+	protected PagedRequest<Repository> createStarredRequest(String user,
+			int start, int size) {
+		if (user == null)
+			throw new IllegalArgumentException("User cannot be null"); //$NON-NLS-1$
+		if (user.length() == 0)
+			throw new IllegalArgumentException("User cannot be empty"); //$NON-NLS-1$
+
+		PagedRequest<Repository> request = createPagedRequest(start, size);
+		StringBuilder uri = new StringBuilder(SEGMENT_USERS);
+		uri.append('/').append(user);
+		uri.append(SEGMENT_STARRED);
+		request.setUri(uri);
+		request.setType(new TypeToken<List<Repository>>() {
+		}.getType());
+		return request;
+	}
+
+	/**
+	 * Create page starred request
+	 *
+	 * @param start
+	 * @param size
+	 * @return request
+	 */
+	protected PagedRequest<Repository> createStarredRequest(int start, int size) {
+		PagedRequest<Repository> request = createPagedRequest(start, size);
+		request.setUri(SEGMENT_USER + SEGMENT_STARRED);
+		request.setType(new TypeToken<List<Repository>>() {
+		}.getType());
+		return request;
+	}
+
+	/**
+	 * Get repositories starred by the given user
+	 *
+	 * @param user
+	 * @return non-null but possibly empty list of repositories
+	 * @throws IOException
+	 */
+	public List<Repository> getStarred(String user) throws IOException {
+		PagedRequest<Repository> request = createStarredRequest(user,
+				PAGE_FIRST, PAGE_SIZE);
+		return getAll(request);
+	}
+
+	/**
+	 * Page repositories starred by given user
+	 *
+	 * @param user
+	 * @return page iterator
+	 * @throws IOException
+	 */
+	public PageIterator<Repository> pageStarred(String user) throws IOException {
+		return pageStarred(user, PAGE_SIZE);
+	}
+
+	/**
+	 * Page repositories starred by given user
+	 *
+	 * @param user
+	 * @param size
+	 * @return page iterator
+	 * @throws IOException
+	 */
+	public PageIterator<Repository> pageStarred(String user, int size)
+			throws IOException {
+		return pageStarred(user, PAGE_FIRST, size);
+	}
+
+	/**
+	 * Page repositories starred by given user
+	 *
+	 * @param user
+	 * @param start
+	 * @param size
+	 * @return page iterator
+	 * @throws IOException
+	 */
+	public PageIterator<Repository> pageStarred(String user, int start, int size)
+			throws IOException {
+		PagedRequest<Repository> request = createStarredRequest(user, start,
+				size);
+		return createPageIterator(request);
+	}
+
+	/**
+	 * Get repositories starred by the currently authenticated user
+	 *
+	 * @return non-null but possibly empty list of repositories
+	 * @throws IOException
+	 */
+	public List<Repository> getStarred() throws IOException {
+		PagedRequest<Repository> request = createStarredRequest(PAGE_FIRST,
+				PAGE_SIZE);
+		return getAll(request);
+	}
+
+	/**
+	 * Page repositories starred by the currently authenticated user
+	 *
+	 * @return page iterator
+	 * @throws IOException
+	 */
+	public PageIterator<Repository> pageStarred() throws IOException {
+		return pageStarred(PAGE_SIZE);
+	}
+
+	/**
+	 * Page repositories starred by the currently authenticated user
+	 *
+	 * @param size
+	 * @return page iterator
+	 * @throws IOException
+	 */
+	public PageIterator<Repository> pageStarred(int size) throws IOException {
+		return pageStarred(PAGE_FIRST, size);
+	}
+
+	/**
+	 * Page repositories starred by the currently authenticated user
+	 *
+	 * @param start
+	 * @param size
+	 * @return page iterator
+	 * @throws IOException
+	 */
+	public PageIterator<Repository> pageStarred(int start, int size)
+			throws IOException {
+		PagedRequest<Repository> request = createStarredRequest(start, size);
+		return createPageIterator(request);
+	}
+
+	/**
+	 * Is currently authenticated user starring given repository?
+	 *
+	 * @param repository
+	 * @return {@code true} if starred, {@code false} otherwise
+	 * @throws IOException
+	 */
+	public boolean isStarring(IRepositoryIdProvider repository)
+			throws IOException {
+		String id = getId(repository);
+		StringBuilder uri = new StringBuilder(SEGMENT_USER);
+		uri.append(SEGMENT_STARRED);
+		uri.append('/').append(id);
+		return check(uri.toString());
+	}
+
+	/**
+	 * Add currently authenticated user as a stargazer of the given repository
+	 *
+	 * @param repository
+	 * @throws IOException
+	 */
+	public void star(IRepositoryIdProvider repository) throws IOException {
+		String id = getId(repository);
+		StringBuilder uri = new StringBuilder(SEGMENT_USER);
+		uri.append(SEGMENT_STARRED);
+		uri.append('/').append(id);
+		client.put(uri.toString());
+	}
+
+	/**
+	 * Remove currently authenticated user as a stargazer of the given repository
+	 *
+	 * @param repository
+	 * @throws IOException
+	 */
+	public void unstar(IRepositoryIdProvider repository) throws IOException {
+		String id = getId(repository);
+		StringBuilder uri = new StringBuilder(SEGMENT_USER);
+		uri.append(SEGMENT_STARRED);
+		uri.append('/').append(id);
+		client.delete(uri.toString());
+	}
+}
diff --git a/org.eclipse.egit.github.core/src/org/eclipse/egit/github/core/service/WatcherService.java b/org.eclipse.egit.github.core/src/org/eclipse/egit/github/core/service/WatcherService.java
index a341ded5..1d41c348 100644
--- a/org.eclipse.egit.github.core/src/org/eclipse/egit/github/core/service/WatcherService.java
+++ b/org.eclipse.egit.github.core/src/org/eclipse/egit/github/core/service/WatcherService.java
@@ -18,8 +18,6 @@ import static org.eclipse.egit.github.core.client.IGitHubConstants.SEGMENT_WATCH
 import static org.eclipse.egit.github.core.client.PagedRequest.PAGE_FIRST;
 import static org.eclipse.egit.github.core.client.PagedRequest.PAGE_SIZE;
 
-import com.google.gson.reflect.TypeToken;
-
 import java.io.IOException;
 import java.util.List;
 
@@ -30,12 +28,16 @@ import org.eclipse.egit.github.core.client.GitHubClient;
 import org.eclipse.egit.github.core.client.PageIterator;
 import org.eclipse.egit.github.core.client.PagedRequest;
 
+import com.google.gson.reflect.TypeToken;
+
 /**
  * Service class for dealing with users watching GitHub repositories.
  *
  * @see <a href="http://developer.github.com/v3/repos/watching">GitHub watcher
  *      API documentation</a>
+ * @deprecated use {@link StargazerService} instead
  */
+@Deprecated
 public class WatcherService extends GitHubService {
 
 	/**
@@ -61,6 +63,7 @@ public class WatcherService extends GitHubService {
 	 * @param start
 	 * @param size
 	 * @return request
+	 * @deprecated use {@link StargazerService#createStargazerRequest}
 	 */
 	protected PagedRequest<User> createWatcherRequest(
 			IRepositoryIdProvider repository, int start, int size) {
@@ -81,6 +84,7 @@ public class WatcherService extends GitHubService {
 	 * @param repository
 	 * @return non-null but possibly empty list of users
 	 * @throws IOException
+	 * @deprecated use {@link StargazerService#getStargazers} instead
 	 */
 	public List<User> getWatchers(IRepositoryIdProvider repository)
 			throws IOException {
@@ -94,6 +98,7 @@ public class WatcherService extends GitHubService {
 	 *
 	 * @param repository
 	 * @return page iterator
+	 * @deprecated use {@link StargazerService#pageStargazers}
 	 */
 	public PageIterator<User> pageWatchers(IRepositoryIdProvider repository) {
 		return pageWatchers(repository, PAGE_SIZE);
@@ -105,6 +110,7 @@ public class WatcherService extends GitHubService {
 	 * @param repository
 	 * @param size
 	 * @return page iterator
+	 * @deprecated use {@link StargazerService#pageStargazers}
 	 */
 	public PageIterator<User> pageWatchers(IRepositoryIdProvider repository,
 			int size) {
@@ -118,6 +124,7 @@ public class WatcherService extends GitHubService {
 	 * @param start
 	 * @param size
 	 * @return page iterator
+	 * @deprecated use {@link StargazerService#pageStargazers}
 	 */
 	public PageIterator<User> pageWatchers(IRepositoryIdProvider repository,
 			int start, int size) {
@@ -133,6 +140,7 @@ public class WatcherService extends GitHubService {
 	 * @param start
 	 * @param size
 	 * @return request
+	 * @deprecated use {@link StargazerService#createStarredRequest}
 	 */
 	protected PagedRequest<Repository> createWatchedRequest(String user,
 			int start, int size) {
@@ -157,6 +165,7 @@ public class WatcherService extends GitHubService {
 	 * @param start
 	 * @param size
 	 * @return request
+	 * @deprecated use {@link StargazerService#createStarredRequest}
 	 */
 	protected PagedRequest<Repository> createWatchedRequest(int start, int size) {
 		PagedRequest<Repository> request = createPagedRequest(start, size);
@@ -172,6 +181,7 @@ public class WatcherService extends GitHubService {
 	 * @param user
 	 * @return non-null but possibly empty list of repositories
 	 * @throws IOException
+	 * @deprecated use {@link StargazerService#getStarred}
 	 */
 	public List<Repository> getWatched(String user) throws IOException {
 		PagedRequest<Repository> request = createWatchedRequest(user,
@@ -185,6 +195,7 @@ public class WatcherService extends GitHubService {
 	 * @param user
 	 * @return page iterator
 	 * @throws IOException
+	 * @deprecated use {@link StargazerService#pageStarred}
 	 */
 	public PageIterator<Repository> pageWatched(String user) throws IOException {
 		return pageWatched(user, PAGE_SIZE);
@@ -197,6 +208,7 @@ public class WatcherService extends GitHubService {
 	 * @param size
 	 * @return page iterator
 	 * @throws IOException
+	 * @deprecated use {@link StargazerService#pageStarred}
 	 */
 	public PageIterator<Repository> pageWatched(String user, int size)
 			throws IOException {
@@ -211,6 +223,7 @@ public class WatcherService extends GitHubService {
 	 * @param size
 	 * @return page iterator
 	 * @throws IOException
+	 * @deprecated use {@link StargazerService#pageStarred}
 	 */
 	public PageIterator<Repository> pageWatched(String user, int start, int size)
 			throws IOException {
@@ -224,6 +237,7 @@ public class WatcherService extends GitHubService {
 	 *
 	 * @return non-null but possibly empty list of repositories
 	 * @throws IOException
+	 * @deprecated use {@link StargazerService#getStarred}
 	 */
 	public List<Repository> getWatched() throws IOException {
 		PagedRequest<Repository> request = createWatchedRequest(PAGE_FIRST,
@@ -236,6 +250,7 @@ public class WatcherService extends GitHubService {
 	 *
 	 * @return page iterator
 	 * @throws IOException
+	 * @deprecated use {@link StargazerService#pageStarred}
 	 */
 	public PageIterator<Repository> pageWatched() throws IOException {
 		return pageWatched(PAGE_SIZE);
@@ -247,6 +262,7 @@ public class WatcherService extends GitHubService {
 	 * @param size
 	 * @return page iterator
 	 * @throws IOException
+	 * @deprecated use {@link StargazerService#pageStarred}
 	 */
 	public PageIterator<Repository> pageWatched(int size) throws IOException {
 		return pageWatched(PAGE_FIRST, size);
@@ -259,6 +275,7 @@ public class WatcherService extends GitHubService {
 	 * @param size
 	 * @return page iterator
 	 * @throws IOException
+	 * @deprecated use {@link StargazerService#pageStarred}
 	 */
 	public PageIterator<Repository> pageWatched(int start, int size)
 			throws IOException {
@@ -272,6 +289,7 @@ public class WatcherService extends GitHubService {
 	 * @param repository
 	 * @return true if watch, false otherwise
 	 * @throws IOException
+	 * @deprecated use {@link StargazerService#isStarring}
 	 */
 	public boolean isWatching(IRepositoryIdProvider repository)
 			throws IOException {
@@ -287,6 +305,7 @@ public class WatcherService extends GitHubService {
 	 *
 	 * @param repository
 	 * @throws IOException
+	 * @deprecated use {@link StargazerService#star}
 	 */
 	public void watch(IRepositoryIdProvider repository) throws IOException {
 		String id = getId(repository);
@@ -301,6 +320,7 @@ public class WatcherService extends GitHubService {
 	 *
 	 * @param repository
 	 * @throws IOException
+	 * @deprecated use {@link StargazerService#unstar}
 	 */
 	public void unwatch(IRepositoryIdProvider repository) throws IOException {
 		String id = getId(repository);