Merge branch 'master' of github.com:kohsuke/github-api

johnou · johnou · commit a46c7acbd29e · 2013-01-24T16:58:42.000+01:00
diff --git a/pom.xml b/pom.xml
@@ -3,11 +3,11 @@
   <parent>
     <groupId>org.kohsuke</groupId>
     <artifactId>pom</artifactId>
-    <version>3</version>
+    <version>4</version>
   </parent>
 
   <artifactId>github-api</artifactId>
-  <version>1.35-SNAPSHOT</version>
+  <version>1.36-SNAPSHOT</version>
   <name>GitHub API for Java</name>
   <url>http://github-api.kohsuke.org/</url>
   <description>GitHub API for Java</description>
diff --git a/src/main/java/org/kohsuke/github/GitHub.java b/src/main/java/org/kohsuke/github/GitHub.java
@@ -55,6 +55,8 @@
  */
 public class GitHub {
     /*package*/ final String login;
+
+
     /*package*/ final String encodedAuthorization;
     /*package*/ final String apiToken;
 
@@ -65,7 +67,7 @@ public class GitHub {
 	private final String apiUrl;
 
 	private GitHub(String login, String apiToken, String password) {
-		this ("https://api.github.com", login, apiToken, password);
+		this (GITHUB_URL, login, apiToken, password);
 	}
 
     /**
@@ -112,7 +114,11 @@ public static GitHub connect() throws IOException {
         } finally {
             IOUtils.closeQuietly(in);
         }
-        return new GitHub(props.getProperty("login"),props.getProperty("token"),props.getProperty("password"));
+        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"));
     }
 
     /**
@@ -164,7 +170,7 @@ public static GitHub connectAnonymously() {
 
         if (tailApiUrl.startsWith("/")) {
             if ("github.com".equals(apiUrl)) {// backward compatibility
-                return new URL("https://api.github.com" + tailApiUrl);
+                return new URL(GITHUB_URL + tailApiUrl);
             } else {
                 return new URL(apiUrl + tailApiUrl);
             }
@@ -339,4 +345,6 @@ public boolean isCredentialValid() throws IOException {
         MAPPER.setVisibilityChecker(new Std(NONE, NONE, NONE, NONE, ANY));
         MAPPER.getDeserializationConfig().set(Feature.FAIL_ON_UNKNOWN_PROPERTIES, false);
     }
+
+    private static final String GITHUB_URL = "https://api.github.com";
 }
diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
@@ -0,0 +1,36 @@
+What is this?
+=====
+
+This library defines an object oriented representation of the GitHub API. By "object oriented" we mean
+there are classes that correspond to the domain model of GitHub (such as `GHUser` and `GHRepository`),
+operations that act on them as defined as methods (such as `GHUser.follow()`), and those object references
+are used in favor of using string handle (such as `GHUser.isMemberOf(GHOrganization)` instead of
+`GHUser.isMemberOf(String)`)
+
+There are some corners of the GitHub API that's not yet implemented, but
+the library is implemented with the right abstractions and libraries to make it very easy to improve the coverage.
+
+Sample Usage
+-----
+
+    GitHub github = GitHub.connect();
+    GHRepository repo = github.createRepository(
+      "new-repository","this is my new repository",
+      "http://www.kohsuke.org/",true/*public*/);
+    repo.addCollaborators(github.getUser("abayer"),github.getUser("rtyler"));
+    repo.delete();
+
+Credential
+----
+
+This library allows the caller to supply the credential as parameters, but it also defines a common convention
+so that applications using this library will look at the consistent location. In this convention, the library
+looks at `~/.github` property file, which should have the following two values:
+
+    login=kohsuke
+    password=012345678
+
+Alternatively, you can have just the OAuth token in this file:
+
+    oauth=4d98173f7c075527cb64878561d1fe70
+
