Documentation and Javadocs

README.md

@@ -6,7 +6,13 @@ accession management software in Java with [Genesys PGR portal](https://www.gene
 
 ## How to use `genesys-client-api`
 
-The genesys-client-api is 
+The genesys-client-api snapshots are published on [OSSRH](https://oss.sonatype.org/content/groups/public).
+
+	<dependency>
+		<groupId>org.genesys-pgr</groupId>
+		<artifactId>genesys-client-api</artifactId>
+		<version>0.0.3-SNAPSHOT</version>
+	</dependency>
 
 ### Your copy of the library
 
@@ -17,10 +23,12 @@ The genesys-client-api is
 ### Your new project
 
 * Create a new Maven project in Eclipse, if starting from scratch
-* Add dependency on org.genesys2:genesys-client-api artefact to your `pom.xml`
-```<dependency>
-	<groupId>org.genesys2</groupId>
-	<artifactId>genesys-client-api</artifactId>
-	<version>0.0.2-SNAPSHOT</version>
-</dependency>```
+* Add dependency on org.genesys-pgr:genesys-client-api artefact to your `pom.xml`
+
+	<dependency>
+		<groupId>org.genesys-pgr</groupId>
+		<artifactId>genesys-client-api</artifactId>
+		<version>0.0.3-SNAPSHOT</version>
+	</dependency>
+
 * Create your integration project

src/main/java/org/genesys2/client/oauth/CLI.java

@@ -48,7 +48,7 @@ import com.fasterxml.jackson.databind.node.ObjectNode;
 import com.fasterxml.jackson.databind.node.TextNode;
 
 /**
- * Command line interface to Genesys
+ * Simple command line interface to Genesys
  * 
  * @author matijaobreza
  * 

src/main/java/org/genesys2/client/oauth/GenesysApiException.java

@@ -16,12 +16,24 @@
 
 package org.genesys2.client.oauth;
 
+/**
+ * General GenesysApiException.
+ */
 public class GenesysApiException extends Exception {
+	
 	private static final long serialVersionUID = -6008425446284829953L;
 
+	/**
+	 * Instantiates a new general Genesys API exception.
+	 */
 	public GenesysApiException() {
 	}
 
+	/**
+	 * Instantiates a new general Genesys API exception.
+	 *
+	 * @param string the string
+	 */
 	public GenesysApiException(String string) {
 		super(string);
 	}

src/main/java/org/genesys2/client/oauth/OAuthAuthenticationException.java

@@ -16,12 +16,24 @@
 
 package org.genesys2.client.oauth;
 
+/**
+ * Exception for authentication exceptions. 
+ */
 public class OAuthAuthenticationException extends GenesysApiException {
+	
 	private static final long serialVersionUID = -6008425446284829953L;
 
+	/**
+	 * Instantiates a new o auth authentication exception.
+	 */
 	public OAuthAuthenticationException() {
 	}
 
+	/**
+	 * Instantiates a new o auth authentication exception.
+	 *
+	 * @param string the string
+	 */
 	public OAuthAuthenticationException(String string) {
 		super(string);
 	}

src/main/java/org/genesys2/client/oauth/PleaseRetryException.java

@@ -16,8 +16,18 @@
 
 package org.genesys2.client.oauth;
 
+/**
+ * API exception indicating that the operation failed due to concurrency issues
+ * and should be retried by the client.
+ */
 public class PleaseRetryException extends RuntimeException {
 
+	/**
+	 * Instantiates a new please retry exception.
+	 *
+	 * @param message
+	 *            the message
+	 */
 	public PleaseRetryException(String message) {
 		super(message);
 	}

src/main/java/org/genesys2/client/oauth/api/GenesysApi.java

@@ -19,7 +19,6 @@ package org.genesys2.client.oauth.api;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
-import org.genesys2.client.oauth.OAuthAuthenticationException;
 import org.scribe.builder.api.DefaultApi20;
 import org.scribe.extractors.AccessTokenExtractor;
 import org.scribe.extractors.JsonTokenExtractor;
@@ -30,17 +29,37 @@ import org.scribe.model.Response;
 import org.scribe.model.Token;
 import org.scribe.utils.OAuthEncoder;
 
+/**
+ * Genesys API v1.
+ */
 public class GenesysApi extends DefaultApi20 {
 
+	/** OAuth2 authorization endpoint that is appended to {@link #baseUrl} */
 	public static final String AUTHORIZE_URL = "/oauth/authorize?client_id=%s&client_secret=%s&response_type=code&redirect_uri=%s";
+	
+	/** OAuth2 access token endpoint that is appended to {@link #baseUrl} */
 	private static final String TOKEN_ENDPOINT = "/oauth/token";
 
+	/** The base URL of the Genesys server (e.g. https://www.genesys-pgr.org) */
 	private String baseUrl;
+	
+	/** The complete authorization url */
 	private String authorizeUrl;
+	
+	/** The scoped authorize url. */
 	private String scopedAuthorizeUrl;
+	
+	/** The access token endpoint. */
 	private String accessTokenEndpoint;
+	
+	/** The refresh token endpoint. */
 	private String refreshTokenEndpoint;
 
+	/**
+	 * Sets the base url.
+	 *
+	 * @param baseUrl the new base url
+	 */
 	public void setBaseUrl(String baseUrl) {
 		this.baseUrl = baseUrl;
 		this.authorizeUrl = this.baseUrl + AUTHORIZE_URL;
@@ -49,15 +68,26 @@ public class GenesysApi extends DefaultApi20 {
 		this.accessTokenEndpoint = this.baseUrl + TOKEN_ENDPOINT + "?grant_type=authorization_code";
 	}
 
+	/* (non-Javadoc)
+	 * @see org.scribe.builder.api.DefaultApi20#getAccessTokenEndpoint()
+	 */
 	@Override
 	public String getAccessTokenEndpoint() {
 		return this.accessTokenEndpoint;
 	}
 
+	/**
+	 * Gets the refresh token endpoint.
+	 *
+	 * @return the refresh token endpoint
+	 */
 	public String getRefreshTokenEndpoint() {
 		return this.refreshTokenEndpoint;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.scribe.builder.api.DefaultApi20#getAuthorizationUrl(org.scribe.model.OAuthConfig)
+	 */
 	@Override
 	public String getAuthorizationUrl(OAuthConfig config) {
 
@@ -65,11 +95,20 @@ public class GenesysApi extends DefaultApi20 {
 				: String.format(this.authorizeUrl, config.getApiKey(), config.getApiSecret(), OAuthEncoder.encode(config.getCallback()));
 	}
 
+	/* (non-Javadoc)
+	 * @see org.scribe.builder.api.DefaultApi20#getAccessTokenExtractor()
+	 */
 	@Override
 	public AccessTokenExtractor getAccessTokenExtractor() {
 		return new JsonTokenExtractor();
 	}
 
+	/**
+	 * Gets the refresh token.
+	 *
+	 * @param accessToken the access token
+	 * @return the refresh token
+	 */
 	public Token getRefreshToken(Token accessToken) {
 		Pattern refreshTokenPattern = Pattern.compile("\"refresh_token\":\\s*\"(\\S*?)\"");
 
@@ -85,10 +124,13 @@ public class GenesysApi extends DefaultApi20 {
 	 * http://stackoverflow.com/questions/20044222/spring-security-oauth-2-
 	 * implicit-grant-no-support-for-refresh-token
 	 * 
-	 * /oauth/token?client_id=MyClient&grant_type=refresh_token&client_secret=
-	 * mysecret&refresh_token=19698a4a-960a-4d24-a8cc-44d4b71df47b
-	 * 
-	 * @throws OAuthAuthenticationException
+	 * /oauth/token?client_id=MyClient&grant_type=refresh_token&client_secret=
+	 * mysecret&refresh_token=19698a4a-960a-4d24-a8cc-44d4b71df47b
+	 *
+	 * @param apiKey the api key
+	 * @param apiSecret the api secret
+	 * @param refreshToken the refresh token
+	 * @return the access token
 	 */
 	public Token getAccessToken(String apiKey, String apiSecret, Token refreshToken) {
 		OAuthRequest request = new OAuthRequest(getAccessTokenVerb(), this.refreshTokenEndpoint);
@@ -100,6 +142,11 @@ public class GenesysApi extends DefaultApi20 {
 		return getAccessTokenExtractor().extract(response.getBody());
 	}
 
+	/**
+	 * Gets the base url.
+	 *
+	 * @return the base url
+	 */
 	public String getBaseUrl() {
 		return baseUrl;
 	}