New default timeouts and fix javadoc errors

Specific Rate Limit exceptions added

ApiClient - updated connectionTimeout and readTimeout default to 180000 milliseconds (3 min). You can override and set as high as 5 min.

Added missing comments to reduce the number of warning during build of JavaDocs

Author: SidneyAllen

pom.xml

@@ -5,7 +5,7 @@
     <artifactId>xero-java</artifactId>
     <packaging>jar</packaging>
     <name>xero-java</name>
-    <version>4.7.2</version>
+    <version>4.8.0</version>
     <url>https://github.com/XeroAPI/Xero-Java</url>
     <description>This is the official Java SDK for Xero API</description>
     <licenses>

src/main/java/com/xero/api/ApiClient.java

@@ -28,14 +28,16 @@
 import java.net.URL;
 import java.security.interfaces.RSAPublicKey;
 
-
+/** 
+ * ApiClient for managing global http client and object mapper
+*/
 public class ApiClient {
     private final String basePath;
     private final HttpRequestFactory httpRequestFactory;
     private final ObjectMapper objectMapper;
     private HttpTransport httpTransport = new NetHttpTransport();
-    private int connectionTimeout = 20000;
-    private int readTimeout = 20000;
+    private int connectionTimeout = 180000;
+    private int readTimeout = 180000;
 
     private static final String defaultBasePath = "https://api.xero.com/api.xro/2.0";
 
@@ -53,10 +55,18 @@ private static ObjectMapper createDefaultObjectMapper() {
         return objectMapper;
     }
 
+    /** method for initiazing object instance with default properties */
     public ApiClient() {
         this(null, null, null, null,null);
     }
 
+    /** ApiClient method for initiazing object instance with custom properties 
+    * @param basePath String that defines the base path for each API request
+    * @param transport HttpTransport required for creating the httpRequestFactory
+    * @param initializer HttpRequestInitializer for additional configuration during creation of httpRequestFactory
+    * @param objectMapper ObjectMapper object used to serialize and deserialize using model classes.
+    * @param reqFactory HttpRequestFactory is the thread-safe light-weight HTTP request factory layer on top of the HTTP transport  
+    */
     public ApiClient(
         String basePath,
         HttpTransport transport,
@@ -74,46 +84,77 @@ public ApiClient(
         this.objectMapper = (objectMapper == null ? createDefaultObjectMapper() : objectMapper);
     }
 
+    /** method for retrieving the httpRequestFactory property
+    * @return HttpRequestFactory
+    */
     public HttpRequestFactory getHttpRequestFactory() {
         return httpRequestFactory;
     }
 
+    /** method for retrieving the connectionTimeout property 
+    * @return int
+    */
     public int getConnectionTimeout() {
         return connectionTimeout;
     }
 
+    /** method for setting the connectionTimeout property 
+    * @param connectionTimeout int defines in milliseconds the time allowed making the initial connection to the server.
+    */
     public void setConnectionTimeout(int connectionTimeout) {
         this.connectionTimeout = connectionTimeout;
     }
 
+    /** method for retrieving the readTimeout property
+    * @return int
+    */
     public int getReadTimeout() {
         return readTimeout;
     }
 
+    /** method for setting the readTimeout property 
+    * @param readTimeout int defines in milliseconds the time allowed to complete reading data from the server.
+    */
     public void setReadTimeout(int readTimeout) {
         this.readTimeout = readTimeout;
     }
 
+    /** method for retrieving the httpTransport property 
+    * @return HttpTransport
+    */
     public HttpTransport getHttpTransport() {
         return httpTransport;
     }
 
+    /** method for setting the httpTransport property 
+    * @param transport HttpTransport required for creating the httpRequestFactory
+    */
     public void setHttpTransport(HttpTransport transport) {
         this.httpTransport = transport;
     }
 
+    /** method for retrieving the basePath property 
+    * @return String
+    */
     public String getBasePath() {
         return basePath;
     }
 
+    /** method for retrieving the objectMapper property 
+    * @return ObjectMapper
+    */
     public ObjectMapper getObjectMapper() {
         return objectMapper;
     }
 
+    /** method for managing objects to be serialized */
     public class JacksonJsonHttpContent extends AbstractHttpContent {
         /* A POJO that can be serialized with a com.fasterxml Jackson ObjectMapper */
         private final Object data;
 
+        /**  method for taking native object and serializing into JSON data for use by http client 
+        * @param data Object 
+        */
         public JacksonJsonHttpContent(Object data) {
             super(Json.MEDIA_TYPE);
             this.data = data;
@@ -125,11 +166,19 @@ public void writeTo(OutputStream out) throws IOException {
         }
     }
 
-    // Builder pattern to get API instances for this client.
+    /**  Builder pattern to get API instances for this client. 
+    * @return AccountingApi
+    */
     public AccountingApi accountingApi() {
         return new AccountingApi(this);
     }
 
+    /** method for verifying an access token using RSA256 Algorithm
+    * @param accessToken String the JWT token used to access the API
+    * @return DecodedJWT
+    * @exception MalformedURLException Thrown to indicate that a malformed URL has occurred. 
+    * @exception JwkException thrown to indicate a problem while verifying a JWT
+    */
     public DecodedJWT verify(String accessToken) throws MalformedURLException, JwkException {
 
     	DecodedJWT unverifiedJWT = JWT.decode(accessToken);        

src/main/java/com/xero/api/RFC3339DateFormat.java

@@ -18,6 +18,7 @@
 import java.text.FieldPosition;
 import java.util.Date;
 
+/** RFC3339DateFormat method for serializing date into milliseconds */
 public class RFC3339DateFormat extends ISO8601DateFormat {
 
     // Same as ISO8601DateFormat but serializing milliseconds.

src/main/java/com/xero/api/StringUtil.java

@@ -22,6 +22,7 @@
 import org.threeten.bp.OffsetDateTime;
 import org.threeten.bp.ZoneOffset;
 
+/** StringUtil has helper methods for String and Date conversions  */
 public class StringUtil {
     /**
      * Check if the given array contains the given value (with case-insensitive
@@ -72,6 +73,11 @@ public static String join(String[] array, String separator) {
         return out.toString();
     }
 
+    /** Convert string to date
+    * @param date String is a date in MS DateFormat
+    * @return LocalDate a standard date  
+    * @exception IOException thown if string pattern matching and formatting fails
+    */
     public LocalDate convertStringToDate(String date)
             throws IOException {
         LocalDate formattedDate;
@@ -91,6 +97,11 @@ public LocalDate convertStringToDate(String date)
         return formattedDate;
     }
 
+    /** Convert string to datetime
+    * @param date String is a date in MS DateFormat
+    * @return OffsetDateTime an offset date time set to UTC  
+    * @exception IOException thown if string pattern matching and formatting fails
+    */
     public OffsetDateTime convertStringToOffsetDateTime(String date)
             throws IOException {
         OffsetDateTime formattedDate;
@@ -110,6 +121,11 @@ public OffsetDateTime convertStringToOffsetDateTime(String date)
         return formattedDate;
     }
 
+    /** Convert string to datetime
+    * @param date String is a date in MS DateFormat
+    * @return LocalDateTime an local date time   
+    * @exception IOException thown if string pattern matching and formatting fails
+    */
     public LocalDateTime convertStringToLocalDateTime(String date)
             throws IOException {
         LocalDateTime formattedDate;

src/main/java/com/xero/api/XeroApiException.java

@@ -5,6 +5,7 @@
 import java.util.HashMap;
 import java.util.Map;
 
+/** Legacy XeroApiException general exception class for returning exception details  */
 public class XeroApiException extends XeroException {
 
     private static final long serialVersionUID = 1L;
@@ -13,18 +14,29 @@ public class XeroApiException extends XeroException {
     private Map<String, String> messageMap = new HashMap<String, String>();
     private Error error;
 
-    // LEGACY ERROR HANDLER
+    /** Init Xero API Exception
+    * @param responseCode int of the status code returned by the API
+    */
     public XeroApiException(int responseCode) {
         super(responseCode + " response.");
         this.responseCode = responseCode;
     }
 
+    /** Init Xero API Exception
+    * @param responseCode int of the status code returned by the API
+    * @param message String details about the exception
+    * @param e Exception the original exception thrown
+    */
     public XeroApiException(int responseCode, String message, Exception e) {
         super(responseCode + " response: " + message, e);
         this.responseCode = responseCode;
         this.message = message;
     }
 
+    /** Init Xero API Exception
+    * @param responseCode int of the status code returned by the API
+    * @param map Map&lt;String, String&gt; array of details about the exception
+    */
     public XeroApiException(int responseCode, Map<String, String> map) {
         super(responseCode + "response");
         this.responseCode = responseCode;
@@ -38,31 +50,54 @@ public XeroApiException(int responseCode, Map<String, String> map) {
         this.messageMap = map;
     }
 
+    /** Init Xero API Exception
+    * @param responseCode int of the status code returned by the API
+    * @param error Error details about the exception
+    * @param e Exception the original exception thrown
+    */
     public XeroApiException(int responseCode, Error error, Exception e) {
         super(responseCode + " response: none", e);
         this.responseCode = responseCode;
         this.error = error;
     }
 
+    /** Init Xero API Exception
+    * @param responseCode int of the status code returned by the API
+    * @param message String details about the exception
+    * @param error Error details about the exception
+    * @param e Exception the original exception thrown
+    */
     public XeroApiException(int responseCode, String message, Error error, Exception e) {
         super(responseCode + " response: " + message, e);
         this.responseCode = responseCode;
         this.message = message;
         this.error = error;
     }
 
+    /** Init Xero API Exception
+    * @return int of the status code returned by the API
+    */
     public int getResponseCode() {
         return responseCode;
     }
 
+    /** Init Xero API Exception
+    * @return String with the details about the exception
+    */
     public String getMessage() {
         return message;
     }
 
+    /** Init Xero API Exception
+    * @return Map&lt;String, String&gt; array of messages about the exception
+    */
     public Map<String, String> getMessages() {
         return messageMap;
     }
 
+    /** Init Xero API Exception
+    * @return Error object with information about the exception
+    */
     public Error getError() {
         return error;
     }