Merge pull request #15 from kbase/dev-new_client

Publish with jitpack.io

Author: MrCreosote

README.md

@@ -1,14 +1,64 @@
 # Auth2 client for Java
 
 This repo contains a minimal client for the [KBase Auth2 server](https://github.com/kbase/auth2),
-covering only the most common operations - e.g. validating tokens and user names.
+covering only the most common operations - e.g. validating tokens and user names. For those
+functions, it is backwards compatible with the prior version of the client.
 
 Most other uses are easily done with any http/REST client like the built in Java client
 in 11+ or the Jersey client.
 
+## Including the client in your build
 
-## Prior version
+See https://jitpack.io/#kbase/auth2_client_java for instructions on how to include JitPack
+built dependencies in your build.
+
+## JavaDoc
+
+JavaDoc is available at
+```
+https://javadoc.jitpack.io/com/github/kbase/auth2_client_java/<version>/javadoc/
+```
+
+For example:
+
+https://javadoc.jitpack.io/com/github/kbase/auth2_client_java/0.5.0/javadoc/
+
+## Usage
+
+If backwards compatibility with versions of the client prior to 0.5.0 is required, use the
+`us.kbase.auth.ConfigurableAuthService` class. Otherwise use the
+`us.kbase.auth.client.AuthClient` class.
 
-The prior version of the client is available at https://github.com/kbase/auth.
+Usage is fairly simple given a basic understanding of the auth2 server API - consult the
+JavaDocs for details.
 
+## Development
+
+### Adding and releasing code
+
+* Adding code
+  * All code additions and updates must be made as pull requests directed at the develop branch.
+    * All tests must pass and all new code must be covered by tests.
+    * All new code must be documented appropriately
+      * Javadoc
+      * General documentation if appropriate
+      * Release notes
+* Releases
+  * The main branch is the stable branch. Releases are made from the develop branch to the main
+    branch.
+  * Tag the version in git and github.
+  * Create a github release.
+  * Check that the javadoc is appropriately built on JitPack.
+
+### Testing
+
+Copy `test.cfg.example` to `test.cfg` and fill it in appropriately. Then:
+
+```
+./gradlew test
+```
+
+## Prior version
 
+The prior version of the client is available at https://github.com/kbase/auth for source code
+and in https://github.com/kbase/jars for built jars.

RELEASE_NOTES.md

@@ -0,0 +1,5 @@
+# 0.5.0
+
+* Complete rewrite of the auth client
+* Includes a backwards compatibility shim `ConfigurableAuthService`, that supports the the
+  most widely used operations

TODO.md

@@ -1,2 +1,7 @@
 * Use a standard library for the string and token caches. The were copied from the original
-  auth repo since they're known to work. Caffeine is nice
+  auth repo since they're known to work. Caffeine is nice
+* Once updated to Java 11+, use the built in http client vs. urlconnection
+* Start up a local auth server in test mode for tests, stop using GHA tokens
+  * Means fork PRs can pass tests
+  * Wait until the shadow jar is published on maven somewhere so we don't have to pollute the 
+    build with the jars repo

build.gradle

@@ -5,12 +5,10 @@
 plugins {
 	id 'java'
 	id 'jacoco'
+	id 'maven-publish'
 }
 
-// TODO NOW jar build
-// TODO NOW javadoc build
-// TODO NOW publish javadocs on release
-// TODO NOW publish jar on release
+group = 'com.github.kbase'
 
 repositories {
 	mavenCentral()
@@ -22,6 +20,11 @@ compileJava {
 	java.targetCompatibility = JavaVersion.VERSION_1_8
 }
 
+java {
+	withSourcesJar()
+	withJavadocJar()
+}
+
 test {
 	systemProperty "test.cfg", "./test.cfg"
 	testLogging {
@@ -45,6 +48,14 @@ javadoc {
 	}
 }
 
+publishing {
+	publications {
+		maven(MavenPublication) {
+		from components.java
+		}
+	}
+}
+
 dependencies {
 
 	// using older dependencies to not force upgrades on services that might not be able to

src/main/java/us/kbase/auth/client/AuthClient.java

@@ -48,6 +48,7 @@ public class AuthClient {
 	/** Create the client.
 	 * @param auth2RootURI the root URI of the auth service - for example,
 	 * https://appdev.kbase.us/services/auth
+	 * @return the client.
 	 * @throws IOException if an IOException occurs communicating with the auth service.
 	 * @throws AuthException if an auth exception occurs communicating with the auth service.
 	 */

src/main/java/us/kbase/auth/client/cache/StringCache.java

@@ -38,7 +38,7 @@ public class StringCache {
 
 	/**
 	 * Create a new StringCache.
-	 * @param size the nominal size of the cache in strings, which must be < maxsize
+	 * @param size the nominal size of the cache in strings, which must be &lt; maxsize
 	 * @param maxsize the maximum size of the cache in strings
 	 */
 	public StringCache(int size, int maxsize) {
@@ -55,7 +55,7 @@ public StringCache(int size, int maxsize) {
 
 	/**
 	 * Set the lifetime of a string in the cache.
-	 * @param seconds the lifetime of a string
+	 * @param seconds the lifetime of a string.
 	 */
 	public void setExpiry(final long seconds) {
 		if (seconds < 1) {
@@ -66,6 +66,7 @@ public void setExpiry(final long seconds) {
 
 	/**
 	 * Get the lifetime of a string in the cache.
+	 * @return the lifetime of a string.
 	 */
 	public long getExpiry() {
 		return expiry;

src/main/java/us/kbase/auth/client/cache/TokenCache.java

@@ -45,7 +45,7 @@ public class TokenCache {
 
 	/**
 	 * Create a new TokenCache.
-	 * @param size the nominal size of the cache in tokens, which must be < maxsize
+	 * @param size the nominal size of the cache in tokens, which must be &lt; maxsize
 	 * @param maxsize the maximum size of the cache in tokens
 	 */
 	public TokenCache(int size, int maxsize) {