Rename enum, fix docs, and make accessors package private

Author: Ajay Kannan

gcloud-java-core/src/main/java/com/google/gcloud/BaseServiceException.java

@@ -17,7 +17,7 @@
 package com.google.gcloud;
 
 /**
- * Base service exception.
+ * Base class for all service exceptions.
  */
 public class BaseServiceException extends RuntimeException {
 
@@ -45,6 +45,9 @@ public int code() {
     return code;
   }
 
+  /**
+   * Returns {@code true} when it is safe to retry the operation that caused this exception.
+   */
   public boolean retryable() {
     return retryable;
   }

gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/DatastoreException.java

@@ -30,18 +30,18 @@
 public class DatastoreException extends BaseServiceException {
 
   private static final long serialVersionUID = -2336749234060754893L;
-  private static final ImmutableMap<String, ErrorInfo> REASON_TO_CODE;
-  private static final ImmutableMap<Integer, ErrorInfo> HTTP_TO_CODE;
+  private static final ImmutableMap<String, DatastoreError> REASON_TO_CODE;
+  private static final ImmutableMap<Integer, DatastoreError> HTTP_TO_CODE;
 
-  private final ErrorInfo errorInfo;
+  private final DatastoreError error;
 
   /**
-   * Represent metadata about {@link DatastoreException}s.
+   * Represents Datastore errors.
    *
    * @see <a href="https://cloud.google.com/datastore/docs/concepts/errors#Error_Codes">Google Cloud
    *     Datastore error codes</a>
    */
-  public enum ErrorInfo {
+  public enum DatastoreError {
 
     ABORTED(Reason.ABORTED),
     DEADLINE_EXCEEDED(Reason.DEADLINE_EXCEEDED),
@@ -58,29 +58,25 @@ public enum ErrorInfo {
     private final String description;
     private final int httpStatus;
 
-    ErrorInfo(Reason reason) {
+    DatastoreError(Reason reason) {
       this(reason.retryable(), reason.description(), reason.httpStatus());
     }
 
-    ErrorInfo(boolean retryable, String description, int httpStatus) {
+    DatastoreError(boolean retryable, String description, int httpStatus) {
       this.retryable = retryable;
       this.description = description;
       this.httpStatus = httpStatus;
     }
 
-    public String description() {
+    String description() {
       return description;
     }
 
-    public int httpStatus() {
+    int httpStatus() {
       return httpStatus;
     }
 
-    /**
-     * Returns {@code true} if this exception is transient and the same request could be retried.
-     * For any retry it is highly recommended to apply an exponential backoff.
-     */
-    public boolean retryable() {
+    boolean retryable() {
       return retryable;
     }
 
@@ -90,31 +86,31 @@ DatastoreException translate(DatastoreRpcException exception, String message) {
   }
 
   static {
-    ImmutableMap.Builder<String, ErrorInfo> builder = ImmutableMap.builder();
-    Map<Integer, ErrorInfo> httpCodes = new HashMap<>();
-    for (ErrorInfo code : ErrorInfo.values()) {
+    ImmutableMap.Builder<String, DatastoreError> builder = ImmutableMap.builder();
+    Map<Integer, DatastoreError> httpCodes = new HashMap<>();
+    for (DatastoreError code : DatastoreError.values()) {
       builder.put(code.name(), code);
       httpCodes.put(code.httpStatus(), code);
     }
     REASON_TO_CODE = builder.build();
     HTTP_TO_CODE = ImmutableMap.copyOf(httpCodes);
   }
 
-  public DatastoreException(ErrorInfo errorInfo, String message, Exception cause) {
+  public DatastoreException(DatastoreError errorInfo, String message, Exception cause) {
     super(errorInfo.httpStatus(), MoreObjects.firstNonNull(message, errorInfo.description),
         errorInfo.retryable(), cause);
-    this.errorInfo = errorInfo;
+    this.error = errorInfo;
   }
 
-  public DatastoreException(ErrorInfo errorInfo, String message) {
+  public DatastoreException(DatastoreError errorInfo, String message) {
     this(errorInfo, message, null);
   }
 
   /**
    * Returns the code associated with this exception.
    */
-  public ErrorInfo errorInfo() {
-    return errorInfo;
+  public DatastoreError datastoreError() {
+    return error;
   }
 
   static DatastoreException translateAndThrow(RetryHelperException ex) {
@@ -124,7 +120,7 @@ static DatastoreException translateAndThrow(RetryHelperException ex) {
     if (ex instanceof RetryHelper.RetryInterruptedException) {
       RetryHelper.RetryInterruptedException.propagate();
     }
-    throw new DatastoreException(ErrorInfo.UNKNOWN, ex.getMessage(), ex);
+    throw new DatastoreException(DatastoreError.UNKNOWN, ex.getMessage(), ex);
   }
 
   /**
@@ -135,9 +131,9 @@ static DatastoreException translateAndThrow(RetryHelperException ex) {
    */
   static DatastoreException translateAndThrow(DatastoreRpcException exception) {
     String message = exception.getMessage();
-    ErrorInfo code = REASON_TO_CODE.get(exception.reason());
+    DatastoreError code = REASON_TO_CODE.get(exception.reason());
     if (code == null) {
-      code = MoreObjects.firstNonNull(HTTP_TO_CODE.get(exception.httpStatus()), ErrorInfo.UNKNOWN);
+      code = MoreObjects.firstNonNull(HTTP_TO_CODE.get(exception.httpStatus()), DatastoreError.UNKNOWN);
     }
     throw code.translate(exception, message);
   }
@@ -149,10 +145,10 @@ static DatastoreException translateAndThrow(DatastoreRpcException exception) {
    * @throws DatastoreException every time
    */
   static DatastoreException throwInvalidRequest(String massage, Object... params) {
-    throw new DatastoreException(ErrorInfo.FAILED_PRECONDITION, String.format(massage, params));
+    throw new DatastoreException(DatastoreError.FAILED_PRECONDITION, String.format(massage, params));
   }
 
   static DatastoreException propagateUserException(Exception ex) {
-    throw new DatastoreException(ErrorInfo.UNKNOWN, ex.getMessage(), ex);
+    throw new DatastoreException(DatastoreError.UNKNOWN, ex.getMessage(), ex);
   }
 }

gcloud-java-datastore/src/test/java/com/google/gcloud/datastore/DatastoreExceptionTest.java

@@ -19,7 +19,7 @@
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.fail;
 
-import com.google.gcloud.datastore.DatastoreException.ErrorInfo;
+import com.google.gcloud.datastore.DatastoreException.DatastoreError;
 import com.google.gcloud.spi.DatastoreRpc.DatastoreRpcException;
 import com.google.gcloud.spi.DatastoreRpc.DatastoreRpcException.Reason;
 
@@ -30,14 +30,14 @@ public class DatastoreExceptionTest {
   @Test
   public void testCode() throws Exception {
     for (Reason reason : Reason.values()) {
-      ErrorInfo code = ErrorInfo.valueOf(reason.name());
+      DatastoreError code = DatastoreError.valueOf(reason.name());
       assertEquals(reason.retryable(), code.retryable());
       assertEquals(reason.description(), code.description());
       assertEquals(reason.httpStatus(), code.httpStatus());
     }
 
-    DatastoreException exception = new DatastoreException(ErrorInfo.ABORTED, "bla");
-    assertEquals(ErrorInfo.ABORTED, exception.errorInfo());
+    DatastoreException exception = new DatastoreException(DatastoreError.ABORTED, "bla");
+    assertEquals(DatastoreError.ABORTED, exception.datastoreError());
   }
 
   @Test
@@ -47,7 +47,7 @@ public void testTranslateAndThrow() throws Exception {
         DatastoreException.translateAndThrow(new DatastoreRpcException(reason));
         fail("Exception expected");
       } catch (DatastoreException ex) {
-        assertEquals(reason.name(), ex.errorInfo().name());
+        assertEquals(reason.name(), ex.datastoreError().name());
       }
     }
   }
@@ -58,7 +58,7 @@ public void testThrowInvalidRequest() throws Exception {
       DatastoreException.throwInvalidRequest("message %s %d", "a", 1);
       fail("Exception expected");
     } catch (DatastoreException ex) {
-      assertEquals(ErrorInfo.FAILED_PRECONDITION, ex.errorInfo());
+      assertEquals(DatastoreError.FAILED_PRECONDITION, ex.datastoreError());
       assertEquals("message a 1", ex.getMessage());
     }
   }

gcloud-java-datastore/src/test/java/com/google/gcloud/datastore/DatastoreTest.java

@@ -197,7 +197,7 @@ public void testTransactionWithRead() {
       transaction.commit();
       fail("Expecting a failure");
     } catch (DatastoreException expected) {
-      assertEquals(DatastoreException.ErrorInfo.ABORTED, expected.errorInfo());
+      assertEquals(DatastoreException.DatastoreError.ABORTED, expected.datastoreError());
     }
   }
 
@@ -225,7 +225,7 @@ public void testTransactionWithQuery() {
       transaction.commit();
       fail("Expecting a failure");
     } catch (DatastoreException expected) {
-      assertEquals(DatastoreException.ErrorInfo.ABORTED, expected.errorInfo());
+      assertEquals(DatastoreException.DatastoreError.ABORTED, expected.datastoreError());
     }
   }