[maven-release-plugin] prepare release github-api-1.44

Commit's short info model

pom.xml

@@ -3,11 +3,11 @@
   <parent>
     <groupId>org.kohsuke</groupId>
     <artifactId>pom</artifactId>
-    <version>4</version>
+    <version>6</version>
   </parent>
 
   <artifactId>github-api</artifactId>
-  <version>1.35</version>
+  <version>1.44</version>
   <name>GitHub API for Java</name>
   <url>http://github-api.kohsuke.org/</url>
   <description>GitHub API for Java</description>
@@ -25,6 +25,10 @@
     </site>
   </distributionManagement>
 
+  <properties>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+  </properties>
+
   <build>
     <plugins>
       <plugin>

src/main/java/org/kohsuke/github/GHAuthorization.java

@@ -0,0 +1,94 @@
+package org.kohsuke.github;
+
+import java.net.URL;
+import java.util.Collection;
+import java.util.Date;
+import java.util.List;
+
+/**
+ * Generated OAuth token
+ *
+ * @author janinko
+ * @see GitHub#createToken(Collection, String, String)
+ * @see http://developer.github.com/v3/oauth/#create-a-new-authorization
+ */
+public class GHAuthorization {
+	public static final String USER = "user";
+	public static final String USER_EMAIL = "user:email";
+	public static final String USER_FOLLOW = "user:follow";
+	public static final String PUBLIC_REPO = "public_repo";
+	public static final String REPO = "repo";
+	public static final String REPO_STATUS = "repo:status";
+	public static final String DELETE_REPO = "delete_repo";
+	public static final String NOTIFICATIONS = "notifications";
+	public static final String GIST = "gist";
+
+	private GitHub root;
+	private int id;
+	private String url;
+	private List<String> scopes;
+	private String token;
+	private App app;
+	private String note;
+	private String note_url;
+	private String updated_at;
+	private String created_at;
+
+    public GitHub getRoot() {
+        return root;
+    }
+
+	public int getId() {
+		return id;
+	}
+
+	public List<String> getScopes() {
+		return scopes;
+	}
+
+	public String getToken(){
+		return token;
+	}
+
+	public URL getAppUrl(){
+        return GitHub.parseURL(app.url);
+	}
+
+	public String getAppName() {
+		return app.name;
+	}
+   
+	public URL getApiURL(){
+        return GitHub.parseURL(url);
+	}
+
+	public String getNote() {
+		return note;
+	}
+
+	public URL getNoteUrl(){
+        return GitHub.parseURL(note_url);
+	}
+	
+	public Date getCreatedAt() {
+        return GitHub.parseDate(created_at);
+    }
+
+    public Date getUpdatedAt() {
+        return GitHub.parseDate(updated_at);
+    }
+
+	/*package*/ GHAuthorization wrap(GitHub root) {
+		this.root = root;
+		return this;
+	}
+
+
+
+
+
+	private static class App{
+		private String url;
+		private String name;
+	}
+}

src/main/java/org/kohsuke/github/GHCommit.java

@@ -5,6 +5,7 @@ import java.net.URL;
 import java.util.AbstractList;
 import java.util.ArrayList;
 import java.util.Collections;
+import java.util.Date;
 import java.util.List;
 
 /**
@@ -16,6 +17,55 @@ import java.util.List;
  */
 public class GHCommit {
     private GHRepository owner;
+    
+    private ShortInfo commit;
+
+    /**
+     * Short summary of this commit.
+     */
+    public static class ShortInfo {
+        private GHAuthor author;
+        private GHAuthor committer;
+        
+        private String message;
+        
+        private int comment_count;
+
+    	public GHAuthor getAuthor() {
+    		return author;
+    	}
+
+		public GHAuthor getCommitter() {
+			return committer;
+		}
+
+        /**
+         * Commit message.
+         */
+		public String getMessage() {
+			return message;
+		}
+
+		public int getCommentCount() {
+			return comment_count;
+		}
+    }
+    
+    public static class GHAuthor {
+    	private String name,email,date;
+
+    	public String getName() {
+    		return name;
+    	}
+
+    	public String getEmail() {
+    		return email;
+    	}
+
+        public Date getDate() {
+            return GitHub.parseDate(date);
+        }
+    }
 
     public static class Stats {
         int total,additions,deletions;
@@ -110,8 +160,14 @@ public class GHCommit {
     Stats stats;
     List<Parent> parents;
     User author,committer;
+    
+    
 
-    /**
+    public ShortInfo getCommitShortInfo() {
+		return commit;
+	}
+
+	/**
      * The repository that contains the commit.
      */
     public GHRepository getOwner() {

src/main/java/org/kohsuke/github/GHCompare.java

@@ -0,0 +1,156 @@
+package org.kohsuke.github;
+
+import java.net.URL;
+import java.util.Date;
+
+/**
+ * The model user for comparing 2 commits in the GitHub API.
+ *
+ * @author Michael Clarke
+ */
+public class GHCompare {
+
+    private String url, html_url, permalink_url, diff_url, patch_url;
+    public Status status;
+    private int ahead_by, behind_by, total_commits;
+    private Commit base_commit, merge_base_commit;
+    private Commit[] commits;
+    private GHCommit.File[] files;
+
+    private GHRepository owner;
+
+    public URL getUrl() {
+        return GitHub.parseURL(url);
+    }
+
+    public URL getHtmlUrl() {
+        return GitHub.parseURL(html_url);
+    }
+
+    public URL getPermalinkUrl() {
+        return GitHub.parseURL(permalink_url);
+    }
+
+    public URL getDiffUrl() {
+        return GitHub.parseURL(diff_url);
+    }
+
+    public URL getPatchUrl() {
+        return GitHub.parseURL(patch_url);
+    }
+
+    public Status getStatus() {
+        return status;
+    }
+
+    public int getAheadBy() {
+        return ahead_by;
+    }
+
+    public int getBehindBy() {
+        return behind_by;
+    }
+
+    public int getTotalCommits() {
+        return total_commits;
+    }
+
+    public Commit getBaseCommit() {
+        return base_commit;
+    }
+
+    public Commit getMergeBaseCommit() {
+        return merge_base_commit;
+    }
+
+    public Commit[] getCommits() {
+        return commits;
+    }
+
+
+    public GHCompare wrap(GHRepository owner) {
+        this.owner = owner;
+        for (Commit commit : commits) {
+            commit.wrapUp(owner);
+        }
+        merge_base_commit.wrapUp(owner);
+        base_commit.wrapUp(owner);
+        return this;
+    }
+
+    /**
+     * Compare commits had a child commit element with additional details we want to capture.
+     * This extenstion of GHCommit provides that.
+     */
+    public static class Commit extends GHCommit {
+
+        private InnerCommit commit;
+
+        public InnerCommit getCommit() {
+            return commit;
+        }
+    }
+
+
+    public static class InnerCommit {
+        private String url, sha, message;
+        private User author, committer;
+        private Tree tree;
+
+        public String getUrl() {
+            return url;
+        }
+
+        public String getSha() {
+            return sha;
+        }
+
+        public String getMessage() {
+            return message;
+        }
+
+        public User getAuthor() {
+            return author;
+        }
+
+        public User getCommitter() {
+            return committer;
+        }
+
+        public Tree getTree() {
+            return tree;
+        }
+    }
+
+    public static class Tree {
+        private String url, sha;
+
+        public String getUrl() {
+            return url;
+        }
+
+        public String getSha() {
+            return sha;
+        }
+    }
+
+    public static class User {
+        private String name, email, date;
+
+        public String getName() {
+            return name;
+        }
+
+        public String getEmail() {
+            return email;
+        }
+
+        public Date getDate() {
+            return GitHub.parseDate(date);
+        }
+    }
+
+    public static enum Status {
+        behind, ahead, identical;
+    }
+}

src/main/java/org/kohsuke/github/GHEventPayload.java

@@ -18,10 +18,16 @@ public abstract class GHEventPayload {
         this.root = root;
     }
 
+    /**
+     * A pull request status has changed.
+     *
+     * @see http://developer.github.com/v3/activity/events/types/#pullrequestevent
+     */
     public static class PullRequest extends GHEventPayload {
         private String action;
         private int number;
-        GHPullRequest pull_request;
+        private GHPullRequest pull_request;
+        private GHRepository repository;
 
         public String getAction() {
             return action;
@@ -36,11 +42,67 @@ public abstract class GHEventPayload {
             return pull_request;
         }
 
+        public GHRepository getRepository() {
+            return repository;
+        }
+
         @Override
         void wrapUp(GitHub root) {
             super.wrapUp(root);
-            pull_request.wrapUp(root);
+            if (repository!=null) {
+                repository.wrap(root);
+                pull_request.wrap(repository);
+            } else {
+                pull_request.wrapUp(root);
+            }
         }
     }
 
+    /**
+     * A comment was added to an issue
+     *
+     * @see http://developer.github.com/v3/activity/events/types/#issuecommentevent
+     */
+    public static class IssueComment extends GHEventPayload {
+        private String action;
+        private GHIssueComment comment;
+        private GHIssue issue;
+        private GHRepository repository;
+
+        public String getAction() {
+            return action;
+        }
+
+        public GHIssueComment getComment() {
+            return comment;
+        }
+
+        public void setComment(GHIssueComment comment) {
+            this.comment = comment;
+        }
+
+        public GHIssue getIssue() {
+            return issue;
+        }
+
+        public void setIssue(GHIssue issue) {
+            this.issue = issue;
+        }
+
+        public GHRepository getRepository() {
+            return repository;
+        }
+
+        public void setRepository(GHRepository repository) {
+            this.repository = repository;
+        }
+
+        @Override
+        void wrapUp(GitHub root) {
+            super.wrapUp(root);
+            repository.wrap(root);
+            issue.wrap(repository);
+            comment.wrapUp(issue);
+        }
+    }
 }

src/main/java/org/kohsuke/github/GHIssue.java

@@ -138,7 +138,7 @@ public class GHIssue {
      * Updates the issue by adding a comment.
      */
     public void comment(String message) throws IOException {
-        new Requester(root).with("body",message).to(getApiRoute() + "/comments");
+        new Requester(root).with("body",message).to(getIssuesApiRoute() + "/comments");
     }
 
     private void edit(String key, Object value) throws IOException {
@@ -190,7 +190,7 @@ public class GHIssue {
     public PagedIterable<GHIssueComment> listComments() throws IOException {
         return new PagedIterable<GHIssueComment>() {
             public PagedIterator<GHIssueComment> iterator() {
-                return new PagedIterator<GHIssueComment>(root.retrieve().asIterator(getApiRoute() + "/comments", GHIssueComment[].class)) {
+                return new PagedIterator<GHIssueComment>(root.retrieve().asIterator(getIssuesApiRoute() + "/comments", GHIssueComment[].class)) {
                     protected void wrapUp(GHIssueComment[] page) {
                         for (GHIssueComment c : page)
                             c.wrapUp(GHIssue.this);
@@ -200,7 +200,11 @@ public class GHIssue {
         };
     }
 
-    private String getApiRoute() {
+    protected String getApiRoute() {
+        return getIssuesApiRoute();
+    }
+
+    private String getIssuesApiRoute() {
         return "/repos/"+owner.getOwnerName()+"/"+owner.getName()+"/issues/"+number;
     }
 
@@ -250,4 +254,4 @@ public class GHIssue {
 			return GitHub.parseURL(html_url);
 		}
 	}
-}
+}

src/main/java/org/kohsuke/github/GHMyself.java

@@ -3,7 +3,12 @@ package org.kohsuke.github;
 import java.io.IOException;
 import java.util.Arrays;
 import java.util.Collections;
+import java.util.HashSet;
+import java.util.Iterator;
 import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.TreeMap;
 
 /**
  * Represents the account that's logging into GitHub.
@@ -35,7 +40,50 @@ public class GHMyself extends GHUser {
     public List<GHKey> getPublicKeys() throws IOException {
         return Collections.unmodifiableList(Arrays.asList(root.retrieve().to("/user/keys", GHKey[].class)));
     }
-    
+
+    /**
+     * Gets the organization that this user belongs to.
+     */
+    public GHPersonSet<GHOrganization> getAllOrganizations() throws IOException {
+        GHPersonSet<GHOrganization> orgs = new GHPersonSet<GHOrganization>();
+        Set<String> names = new HashSet<String>();
+        for (GHOrganization o : root.retrieve().to("/user/orgs", GHOrganization[].class)) {
+            if (names.add(o.getLogin()))    // in case of rumoured duplicates in the data
+                orgs.add(root.getOrganization(o.getLogin()));
+        }
+        return orgs;
+    }
+
+    /**
+     * Gets the all repositories this user owns (public and private).
+     */
+    public synchronized Map<String,GHRepository> getAllRepositories() throws IOException {
+        Map<String,GHRepository> repositories = new TreeMap<String, GHRepository>();
+        for (GHRepository r : listAllRepositories()) {
+            repositories.put(r.getName(),r);
+        }
+        return Collections.unmodifiableMap(repositories);
+    }
+
+    /**
+     * Lists up all repositories this user owns (public and private).
+     *
+     * Unlike {@link #getAllRepositories()}, this does not wait until all the repositories are returned.
+     */
+    public PagedIterable<GHRepository> listAllRepositories() {
+        return new PagedIterable<GHRepository>() {
+            public PagedIterator<GHRepository> iterator() {
+                return new PagedIterator<GHRepository>(root.retrieve().asIterator("/user/repos", GHRepository[].class)) {
+                    @Override
+                    protected void wrapUp(GHRepository[] page) {
+                        for (GHRepository c : page)
+                            c.wrap(root);
+                    }
+                };
+            }
+        };
+    }
+
 //    public void addEmails(Collection<String> emails) throws IOException {
 ////        new Requester(root,ApiVersion.V3).withCredential().to("/user/emails");
 //        root.retrieveWithAuth3()

src/main/java/org/kohsuke/github/GHOrganization.java

@@ -130,10 +130,14 @@ public class GHOrganization extends GHPerson {
 
     /**
      * List up repositories that has some open pull requests.
+     *
+     * This used to be an efficient method that didn't involve traversing every repository, but now
+     * it doesn't do any optimization.
      */
     public List<GHRepository> getRepositoriesWithOpenPullRequests() throws IOException {
         List<GHRepository> r = new ArrayList<GHRepository>();
-        for (GHRepository repository : root.retrieve().to("/orgs/" + login + "/repos", GHRepository[].class)) {
+        for (GHRepository repository : listRepositories()) {
+            repository.wrap(root);
             List<GHPullRequest> pullRequests = repository.getPullRequests(GHIssueState.OPEN);
             if (pullRequests.size() > 0) {
                 r.add(repository);

src/main/java/org/kohsuke/github/GHPerson.java

@@ -54,6 +54,25 @@ public abstract class GHPerson {
         return Collections.unmodifiableMap(repositories);
     }
 
+    /**
+     * Lists up all the repositories.
+     *
+     * Unlike {@link #getRepositories()}, this does not wait until all the repositories are returned.
+     */
+    public PagedIterable<GHRepository> listRepositories() {
+        return new PagedIterable<GHRepository>() {
+            public PagedIterator<GHRepository> iterator() {
+                return new PagedIterator<GHRepository>(root.retrieve().asIterator("/users/" + login + "/repos", GHRepository[].class)) {
+                    @Override
+                    protected void wrapUp(GHRepository[] page) {
+                        for (GHRepository c : page)
+                            c.wrap(root);
+                    }
+                };
+            }
+        };
+    }
+
     /**
      * Loads repository list in a pagenated fashion.
      * 
@@ -63,6 +82,9 @@ public abstract class GHPerson {
      * 
      * Every {@link Iterator#next()} call results in I/O. Exceptions that occur during the processing is wrapped
      * into {@link Error}.
+     *
+     * @deprecated
+     *      Use {@link #listRepositories()}
      */
     public synchronized Iterable<List<GHRepository>> iterateRepositories(final int pageSize) {
         return new Iterable<List<GHRepository>>() {

src/main/java/org/kohsuke/github/GHPullRequest.java

@@ -63,7 +63,12 @@ public class GHPullRequest extends GHIssue {
         if (merged_by != null) merged_by.wrapUp(root);
         return this;
     }
-	
+
+    @Override
+    protected String getApiRoute() {
+        return "/repos/"+owner.getOwnerName()+"/"+owner.getName()+"/pulls/"+number;
+    }
+
     /**
      * The URL of the patch file.
      * like https://github.com/jenkinsci/jenkins/pull/100.patch

src/main/java/org/kohsuke/github/GHRef.java

@@ -0,0 +1,61 @@
+package org.kohsuke.github;
+
+import java.net.URL;
+
+/**
+ * Provides information on a Git ref from GitHub.
+ *
+ * @author Michael Clarke
+ */
+public class GHRef {
+
+    private String ref, url;
+    private GHObject object;
+
+    /**
+     * Name of the ref, such as "refs/tags/abc"
+     */
+    public String getRef() {
+        return ref;
+    }
+
+    /**
+     * The API URL of this tag, such as https://api.github.com/repos/jenkinsci/jenkins/git/refs/tags/1.312
+     */
+    public URL getUrl() {
+        return GitHub.parseURL(url);
+    }
+
+    /**
+     * The object that this ref points to.
+     */
+    public GHObject getObject() {
+        return object;
+    }
+
+
+    public static class GHObject {
+         private String type, sha, url;
+
+        /**
+         * Type of the object, such as "commit"
+         */
+        public String getType() {
+            return type;
+        }
+
+        /**
+         * SHA1 of this object.
+         */
+        public String getSha() {
+            return sha;
+        }
+
+        /**
+         * API URL to this Git data, such as https://api.github.com/repos/jenkinsci/jenkins/git/commits/b72322675eb0114363a9a86e9ad5a170d1d07ac0
+         */
+        public URL getUrl() {
+            return GitHub.parseURL(url);
+        }
+    }
+}

src/main/java/org/kohsuke/github/GHRepository.java

@@ -393,6 +393,46 @@ public class GHRepository {
         return root.retrieve().to(String.format("/repos/%s/%s/hooks/%d", owner.login, name, id), GHHook.class).wrap(this);
     }
 
+    /**
+     * Gets a comparison between 2 points in the repository. This would be similar
+     * to calling <tt>git log id1...id2</tt> against a local repository.
+     * @param id1 an identifier for the first point to compare from, this can be a sha1 ID (for a commit, tag etc) or a direct tag name
+     * @param id2 an identifier for the second point to compare to. Can be the same as the first point.
+     * @return the comparison output
+     * @throws IOException on failure communicating with GitHub
+     */
+    public GHCompare getCompare(String id1, String id2) throws IOException {
+        GHCompare compare = root.retrieve().to(String.format("/repos/%s/%s/compare/%s...%s", owner.login, name, id1, id2), GHCompare.class);
+        return compare.wrap(this);
+    }
+
+    public GHCompare getCompare(GHCommit id1, GHCommit id2) throws IOException {
+        return getCompare(id1.getSHA1(),id2.getSHA1());
+    }
+
+    public GHCompare getCompare(GHBranch id1, GHBranch id2) throws IOException {
+        return getCompare(id1.getName(),id2.getName());
+    }
+
+    /**
+     * Retrieves all refs for the github repository.
+     * @return an array of GHRef elements coresponding with the refs in the remote repository.
+     * @throws IOException on failure communicating with GitHub
+     */
+    public GHRef[] getRefs() throws IOException {
+       return root.retrieve().to(String.format("/repos/%s/%s/git/refs", owner.login, name), GHRef[].class);
+    }
+
+    /**
+     * Retrienved all refs of the given type for the current GitHub repository.
+     * @param refType the type of reg to search for e.g. <tt>tags</tt> or <tt>commits</tt>
+     * @return an array of all refs matching the request type
+     * @throws IOException on failure communicating with GitHub, potentially due to an invalid ref type being requested
+     */
+    public GHRef[] getRefs(String refType) throws IOException {
+        return root.retrieve().to(String.format("/repos/%s/%s/git/refs/%s", owner.login, name, refType), GHRef[].class);
+    }
+
     /**
      * Gets a commit object in this repository.
      */

src/main/java/org/kohsuke/github/GitHub.java

@@ -39,6 +39,7 @@ import java.net.URL;
 import java.text.ParseException;
 import java.text.SimpleDateFormat;
 import java.util.Arrays;
+import java.util.Collection;
 import java.util.Date;
 import java.util.HashMap;
 import java.util.List;
@@ -56,52 +57,77 @@ import static org.codehaus.jackson.annotate.JsonAutoDetect.Visibility.*;
 public class GitHub {
     /*package*/ final String login;
 
-
+    /**
+     * Value of the authorization header to be sent with the request.
+     */
     /*package*/ final String encodedAuthorization;
-    /*package*/ final String apiToken;
 
     private final Map<String,GHUser> users = new HashMap<String, GHUser>();
     private final Map<String,GHOrganization> orgs = new HashMap<String, GHOrganization>();
-	/*package*/ String oauthAccessToken;
-	
-	private final String apiUrl;
 
-	private GitHub(String login, String apiToken, String password) {
-		this (GITHUB_URL, login, apiToken, password);
-	}
+    private final String apiUrl;
 
     /**
+     * Connects to GitHub.com
+     */
+    private GitHub(String login, String oauthAccessToken, String password) throws IOException {
+      this (GITHUB_URL, login, oauthAccessToken, password);
+    }
+
+    /**
+     * Creates a client API root object.
+     *
+     * <p>
+     * Several different combinations of the login/oauthAccessToken/password parameters are allowed
+     * to represent different ways of authentication.
+     *
+     * <dl>
+     *     <dt>Loging anonymously
+     *     <dd>Leave all three parameters null and you will be making HTTP requests without any authentication.
+     *
+     *     <dt>Log in with password
+     *     <dd>Specify the login and password, then leave oauthAccessToken null.
+     *         This will use the HTTP BASIC auth with the GitHub API.
+     *
+     *     <dt>Log in with OAuth token
+     *     <dd>Specify oauthAccessToken, and optionally specify the login. Leave password null.
+     *         This will send OAuth token to the GitHub API. If the login parameter is null,
+     *         The constructor makes an API call to figure out the user name that owns the token.
+     * </dl>
      *
      * @param apiUrl
      *      The URL of GitHub (or GitHub enterprise) API endpoint, such as "https://api.github.com" or
      *      "http://ghe.acme.com/api/v3". Note that GitHub Enterprise has <tt>/api/v3</tt> in the URL.
      *      For historical reasons, this parameter still accepts the bare domain name, but that's considered deprecated.
      *      Password is also considered deprecated as it is no longer required for api usage.
+     * @param login
+     *      The use ID on GitHub that you are logging in as. Can be omitted if the OAuth token is
+     *      provided or if logging in anonymously. Specifying this would save one API call.
+     * @param oauthAccessToken
+     *      Secret OAuth token.
+     * @param password
+     *      User's password. Always used in conjunction with the {@code login} parameter
      */
-    private GitHub(String apiUrl, String login, String apiToken, String password) {
+    private GitHub(String apiUrl, String login, String oauthAccessToken, String password) throws IOException {
         if (apiUrl.endsWith("/")) apiUrl = apiUrl.substring(0, apiUrl.length()-1); // normalize
         this.apiUrl = apiUrl;
-		this.login = login;
-        this.apiToken = apiToken;
 
-        if (apiToken!=null || password!=null) {
-            String authorization = password==null ? (login + "/token" + ":" + apiToken) : (login + ':'+password);
-            encodedAuthorization = new String(Base64.encodeBase64(authorization.getBytes()));
-        } else
-            encodedAuthorization = null;
+        if (oauthAccessToken!=null) {
+            encodedAuthorization = "token "+oauthAccessToken;
+        } else {
+            if (password!=null) {
+                String authorization = (login + ':' + password);
+                encodedAuthorization = "Basic "+new String(Base64.encodeBase64(authorization.getBytes()));
+            } else {// anonymous access
+                encodedAuthorization = null;
+            }
+        }
+
+        if (login==null && encodedAuthorization!=null)
+            login = getMyself().getLogin();
+        this.login = login;
     }
 
-    private GitHub (String apiUrl, String oauthAccessToken) throws IOException {
-    	
-		this.apiUrl = apiUrl;
-		this.encodedAuthorization = null;
-		
-		this.oauthAccessToken = oauthAccessToken;
-        this.apiToken = oauthAccessToken;
-		
-		this.login = getMyself().getLogin();
-    }
-    
     /**
      * Obtains the credential from "~/.github"
      */
@@ -114,11 +140,7 @@ public class GitHub {
         } finally {
             IOUtils.closeQuietly(in);
         }
-        String oauth = props.getProperty("oauth");
-        if (oauth!=null)
-            return new GitHub(GITHUB_URL,oauth);
-        else
-            return new GitHub(props.getProperty("login"),props.getProperty("token"),props.getProperty("password"));
+        return new GitHub(GITHUB_URL,props.getProperty("login"), props.getProperty("oauth"),props.getProperty("password"));
     }
 
     /**
@@ -129,45 +151,61 @@ public class GitHub {
      *      "http://ghe.acme.com/api/v3". Note that GitHub Enterprise has <tt>/api/v3</tt> in the URL.
      *      For historical reasons, this parameter still accepts the bare domain name, but that's considered deprecated.
      */
-    public static GitHub connectToEnterprise(String apiUrl, String login, String apiToken) {
-        return new GitHub(apiUrl,login,apiToken,null);
+    public static GitHub connectToEnterprise(String apiUrl, String oauthAccessToken) throws IOException {
+        return connectUsingOAuth(apiUrl, oauthAccessToken);
     }
 
-    public static GitHub connect(String login, String apiToken){
-        return new GitHub(login,apiToken,null);
+    public static GitHub connectToEnterprise(String apiUrl, String login, String password) throws IOException {
+        return new GitHub(apiUrl, login, null, password);
     }
 
-    public static GitHub connect(String login, String apiToken, String password){
-        return new GitHub(login,apiToken,password);
+    public static GitHub connect(String login, String oauthAccessToken) throws IOException {
+        return new GitHub(login,oauthAccessToken,null);
     }
 
-    public static GitHub connectUsingOAuth (String accessToken) throws IOException {
-    	return connectUsingOAuth("github.com", accessToken);
+    /**
+     * @deprecated
+     *      Either OAuth token or password is sufficient, so there's no point in passing both.
+     *      Use {@link #connectUsingPassword(String, String)} or {@link #connectUsingOAuth(String)}.
+     */
+    public static GitHub connect(String login, String oauthAccessToken, String password) throws IOException {
+        return new GitHub(login,oauthAccessToken,password);
     }
-    
-    public static GitHub connectUsingOAuth (String githubServer, String accessToken) throws IOException {
-    	return new GitHub(githubServer, accessToken);
+
+    public static GitHub connectUsingPassword(String login, String password) throws IOException {
+        return new GitHub(login,null,password);
+    }
+
+    public static GitHub connectUsingOAuth(String oauthAccessToken) throws IOException {
+    	return new GitHub(null, oauthAccessToken, null);
+    }
+
+    public static GitHub connectUsingOAuth(String githubServer, String oauthAccessToken) throws IOException {
+    	return new GitHub(githubServer,null, oauthAccessToken,null);
     }
     /**
      * Connects to GitHub anonymously.
      *
      * All operations that requires authentication will fail.
      */
-    public static GitHub connectAnonymously() {
+    public static GitHub connectAnonymously() throws IOException {
         return new GitHub(null,null,null);
     }
 
+    /**
+     * Is this an anonymous connection
+     * @return {@code true} if operations that require authentication will fail.
+     */
+    public boolean isAnonymous() {
+        return login==null && encodedAuthorization==null;
+    }
+
     /*package*/ void requireCredential() {
-        if ((login==null || encodedAuthorization==null) && oauthAccessToken == null)
+        if (isAnonymous())
             throw new IllegalStateException("This operation requires a credential but none is given to the GitHub constructor");
     }
 
     /*package*/ URL getApiURL(String tailApiUrl) throws IOException {
-    	if (oauthAccessToken != null) {
-    		// append the access token
-    		tailApiUrl = tailApiUrl +  (tailApiUrl.indexOf('?')>=0 ?'&':'?') + "access_token=" + oauthAccessToken;
-    	}
-
         if (tailApiUrl.startsWith("/")) {
             if ("github.com".equals(apiUrl)) {// backward compatibility
                 return new URL(GITHUB_URL + tailApiUrl);
@@ -289,7 +327,7 @@ public class GitHub {
         t.wrapUp(this);
         return t;
     }
-    
+
     /**
      * Creates a new repository.
      *
@@ -303,6 +341,22 @@ public class GitHub {
         return requester.method("POST").to("/user/repos", GHRepository.class).wrap(this);
     }
 
+    /**
+     * Creates a new authorization.
+     *
+     * The token created can be then used for {@link GitHub#connectUsingOAuth(String)} in the future.
+     *
+     * @see <a href="http://developer.github.com/v3/oauth/#create-a-new-authorization">Documentation</a>
+     */
+	public GHAuthorization createToken(Collection<String> scope, String note, String noteUrl) throws IOException{
+		Requester requester = new Requester(this)
+				.with("scopes", scope)
+				.with("note", note)
+				.with("note_url", noteUrl);
+
+		return requester.method("POST").to("/authorizations", GHAuthorization.class).wrap(this);
+	}
+
     /**
      * Ensures that the credential is valid.
      */

src/main/java/org/kohsuke/github/Requester.java

@@ -39,10 +39,12 @@ import java.net.URL;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.HashMap;
+import java.util.HashSet;
 import java.util.Iterator;
 import java.util.List;
 import java.util.Map;
 import java.util.NoSuchElementException;
+import java.util.Set;
 import java.util.zip.GZIPInputStream;
 
 import static org.kohsuke.github.GitHub.*;
@@ -271,9 +273,8 @@ class Requester {
 
         // if the authentication is needed but no credential is given, try it anyway (so that some calls
         // that do work with anonymous access in the reduced form should still work.)
-        // if OAuth token is present, it'll be set in the URL, so need to set the Authorization header
-        if (root.encodedAuthorization!=null && root.oauthAccessToken == null)
-            uc.setRequestProperty("Authorization", "Basic " + root.encodedAuthorization);
+        if (root.encodedAuthorization!=null)
+            uc.setRequestProperty("Authorization", root.encodedAuthorization);
 
         try {
             uc.setRequestMethod(method);
@@ -345,4 +346,11 @@ class Requester {
             IOUtils.closeQuietly(es);
         }
     }
+
+    private Set<String> toSet(String s) {
+        Set<String> r = new HashSet<String>();
+        for (String t : s.split(","))
+            r.add(t.trim());
+        return r;
+    }
 }

src/test/java/Foo.java

@@ -0,0 +1,13 @@
+import org.kohsuke.github.GitHub;
+
+import java.util.Arrays;
+
+/**
+ * @author Kohsuke Kawaguchi
+ */
+public class Foo {
+    public static void main(String[] args) throws Exception {
+        System.out.println(GitHub.connect().createToken(
+                Arrays.asList("user", "repo", "delete_repo", "notifications", "gist"), "GitHub API", null).getToken());
+    }
+}

src/test/java/org/kohsuke/AppTest.java

@@ -332,6 +332,12 @@ public class AppTest extends TestCase {
         assertEquals("oops!",state.getDescription());
         assertEquals("http://jenkins-ci.org/",state.getTargetUrl());
     }
+    
+    public void testCommitShortInfo() throws Exception {
+        GHCommit commit = gitHub.getUser("kohsuke").getRepository("test").getCommit("c77360d6f2ff2c2e6dd11828ad5dccf72419fa1b");
+        assertEquals(commit.getCommitShortInfo().getAuthor().getName(), "Kohsuke Kawaguchi");
+        assertEquals(commit.getCommitShortInfo().getMessage(), "Added a file");
+    }
 
     public void testPullRequestPopulate() throws Exception {
         GHRepository r = gitHub.getUser("kohsuke").getRepository("github-api");

src/test/java/org/kohsuke/github/GitHubTest.java

@@ -8,17 +8,17 @@ import junit.framework.TestCase;
 public class GitHubTest extends TestCase {
 
     public void testGitHubServerWithHttp() throws Exception {
-        GitHub hub = GitHub.connectToEnterprise("http://enterprise.kohsuke.org/api/v3", "kohsuke", "token");
+        GitHub hub = GitHub.connectToEnterprise("http://enterprise.kohsuke.org/api/v3", "bogus","bogus");
         assertEquals("http://enterprise.kohsuke.org/api/v3/test", hub.getApiURL("/test").toString());
     }
 
     public void testGitHubServerWithHttps() throws Exception {
-        GitHub hub = GitHub.connectToEnterprise("https://enterprise.kohsuke.org/api/v3", "kohsuke", "token");
+        GitHub hub = GitHub.connectToEnterprise("https://enterprise.kohsuke.org/api/v3", "bogus","bogus");
         assertEquals("https://enterprise.kohsuke.org/api/v3/test", hub.getApiURL("/test").toString());
     }
 
     public void testGitHubServerWithoutServer() throws Exception {
-        GitHub hub = GitHub.connect("kohsuke", "token", "password");
+        GitHub hub = GitHub.connectUsingPassword("kohsuke", "bogus");
         assertEquals("https://api.github.com/test", hub.getApiURL("/test").toString());
     }
 }