JavaDoc Cleanup (#42)

Author: rs017991

CHANGELOG.md

@@ -302,7 +302,7 @@ MapValue  instances created from JSON to maintain the insertion order of fields
 in the map so that iteration is predictable.
 
 ### Fixed
-- Don't validate request sizes. On-premise only
+- Don't validate request sizes. On-premises only
 - JsonOptions.setPrettyPrint(true) now works
 - Request timeouts now operate correctly on milliseconds instead of rounding up to seconds
 - Changed min/max implementation to make them deterministic
@@ -317,7 +317,7 @@ removed in a future version.
 - Fix another memory leak that could occur on the receive side when the response
 was discarded due to unmatched request Id.
 - Fixed a problem where the HTTP Host header was not being adding in all request
-cases. This prevented use of an intermediate proxy such as Nginx, which validates headers. On-premise only.
+cases. This prevented use of an intermediate proxy such as Nginx, which validates headers. On-premises only.
 - TableUsageRequest: added validation check that startTime, endTime and limit
 must not be negative value.
 
@@ -363,16 +363,16 @@ exact schema match is required on a put. The default behavior is false.
 - Added a new, simpler TableResult.waitForCompletion() interface to wait for the completion of a TableRequest vs waiting for a specific state.
 - Added NoSQLHandle.doTableRequest to encapsulate a TableRequest and waiting for
   its completion in a single, synchronous call.
-- Added OperationNotSupportedException to handle operations that are specific to on-premise and cloud service environments
+- Added OperationNotSupportedException to handle operations that are specific to on-premises and cloud service environments
 
-- Support for both the Oracle NoSQL Database Cloud Service and the on-premise Oracle NoSQL Database product.
-  - Added StoreAccessTokenProvider for authentication of access to an on-premise store
+- Support for both the Oracle NoSQL Database Cloud Service and the on-premises Oracle NoSQL Database product.
+  - Added StoreAccessTokenProvider for authentication of access to an on-premises store
   - Added AuthenticationException to encapsulate authentication problems when
-  accessing an on-premise store.
+  accessing an on-premises store.
   - Added SystemRequest, SystemStatusRequest, and SystemResult for administrative
   operations that are not table-specific.
   - Added NoSQLHandle.doSystemRequest to encapsulate a SystemRequest and waiting for its completion in a single, synchronous call.
-  -   Now that the driver can access both the cloud service and an on-premise store
+  -   Now that the driver can access both the cloud service and an on-premises store
   some operations, classes and exceptions are specific to each environment. These are
   noted in updated javadoc.
 

README.md

@@ -119,7 +119,7 @@ See the Quickstart example below for code details for using a Resource Principal
 
 ### Connecting to the Oracle NoSQL Database On-premise
 
-The on-premise configuration requires a running instance of Oracle NoSQL
+The on-premises configuration requires a running instance of Oracle NoSQL
 Database. In addition a running proxy service is required. See
 [Oracle NoSQL Database Downloads](https://www.oracle.com/database/technologies/nosql-database-server-downloads.html) for downloads, and see
 [Information about the proxy](https://docs.oracle.com/en/database/other-databases/nosql-database/22.1/admin/proxy-and-driver.html)
@@ -149,7 +149,7 @@ Addional logging can be enabled using a java properties file. For full details,
 
 The following is a quick start tutorial to run a simple program in all supported
 environments. It requires access to the Oracle NoSQL Database Cloud Service,
-a running on-premise Oracle NoSQL Database instance, or a running Oracle
+a running on-premises Oracle NoSQL Database instance, or a running Oracle
 NoSQL Cloud Simulator instance. As a standalone program it will run most easily
 using a download version of the Oracle NoSQL SDK for Java.
 
@@ -166,7 +166,7 @@ Using the cloud service on region us-ashburn-1
 ```
 $ java -cp .:<path-to-nosqldriver.jar> Quickstart -service cloud -endpoint us-ashburn-1
 ```
-Using a non-secure on-premise service on endpoint http://localhost:8090
+Using a non-secure on-premises service on endpoint http://localhost:8090
 ```
 $ java -cp .:<path-to-nosqldriver.jar> Quickstart -service onprem -endpoint http://localhost:8090
 ```
@@ -225,7 +225,7 @@ import oracle.nosql.driver.values.MapValue;
  *
  * This program can be run against:
  *  1. the cloud service
- *  2. the on-premise proxy and Oracle NoSQL Database instance, secure or
+ *  2. the on-premises proxy and Oracle NoSQL Database instance, secure or
  *  not secure.
  *  3. the cloud simulator (CloudSim)
  *
@@ -512,7 +512,7 @@ $ mvn -pl examples exec:java -Dexec.mainClass=BasicTableExample \
   -Dexec.args="http://localhost:8080"
 ```
 
-Run BasicTableExample using an on-premise  instance on endpoint
+Run BasicTableExample using an on-premises instance on endpoint
 localhost:8090
 
 ```
@@ -559,7 +559,7 @@ The region argument will change depending on which region you use.
 
 #### Run using the Oracle NoSQL Database On-premise
 
-Running against the on-premise Oracle NoSQL Database on-premise requires
+Running against the on-premises Oracle NoSQL Database on-premises requires
 a running instance of the database and running proxy service. See above.
 
 Run against a not-secure proxy and store, with the proxy running on port 80:

driver/pom.xml

@@ -57,7 +57,7 @@
   <profiles>
 
     <!-- test profiles used with the test target
-         Running tests requires a running on-premise service and httpproxy
+         Running tests requires a running on-premises service and httpproxy
          or a running cloud simulator. Required information:
             o endpoint
          Examples:
@@ -85,7 +85,7 @@
         <secure>false</secure>
         <onprem>false</onprem>
         <serverType>cloudsim</serverType>
-        <!-- exclude non-server tests and on-premise tests -->
+        <!-- exclude non-server tests and on-premises tests -->
         <excluded.tests>
           StoreAccessTokenProviderTest.java, ResourcePrincipalProviderTest.java,
           ConfigFileTest.java, SignatureProviderTest.java,

driver/src/main/java/oracle/nosql/driver/NoSQLHandle.java

@@ -46,7 +46,7 @@
  * information to be used by the handle.
  * <p>
  * The same interface is available to both users of the Oracle NoSQL Database
- * Cloud Service and the on-premise Oracle NoSQL Database; however, some methods
+ * Cloud Service and the on-premises Oracle NoSQL Database; however, some methods
  * and/or parameters are specific to each environment. The documentation has notes
  * about whether a class, method, or parameter is environment-specific. Unless
  * otherwise noted they are applicable to both environments.
@@ -280,12 +280,12 @@ public interface NoSQLHandle extends AutoCloseable {
     /**
      * Queries a table based on the query statement specified in the
      * {@link QueryRequest}.
-     *
+     * <p>
      * Queries that include a full shard key will execute much more efficiently
      * than more distributed queries that must go to multiple shards.
      * <p>
      * Table- and system-style queries such as "CREATE TABLE ..." or "DROP TABLE .."
-     * are not supported by this interfaces. Those operations must be performed using
+     * are not supported by this interface. Those operations must be performed using
      * {@link #tableRequest} or {@link #systemRequest} as appropriate.
      * <p>
      * The amount of data read by a single query request is limited by a system
@@ -315,7 +315,7 @@ public interface NoSQLHandle extends AutoCloseable {
     /**
      * Queries a table based on the query statement specified in the
      * {@link QueryRequest} while returning an iterable result.
-     *
+     * <p>
      * Queries that include a full shard key will execute much more efficiently
      * than more distributed queries that must go to multiple shards.
      * <p>
@@ -325,7 +325,7 @@ public interface NoSQLHandle extends AutoCloseable {
      * and not this method.
      * <p>
      * Table- and system-style queries such as "CREATE TABLE ..." or "DROP TABLE .."
-     * are not supported by this interfaces. Those operations must be performed using
+     * are not supported by this interface. Those operations must be performed using
      * {@link #tableRequest} or {@link #systemRequest} as appropriate.
      * <p>
      * The results are returned through an iterator, if connected to the
@@ -428,7 +428,7 @@ TableResult doTableRequest(TableRequest request,
                                int pollIntervalMs);
 
     /**
-     * On-premise only.
+     * On-premises only.
      * <p>
      * Performs a system operation on the system, such as
      * administrative operations that don't affect a specific table. For
@@ -460,7 +460,7 @@ TableResult doTableRequest(TableRequest request,
     SystemResult systemRequest(SystemRequest request);
 
     /**
-     * On-premise only.
+     * On-premises only.
      * <p>
      * Checks the status of an operation previously performed using
      * {@link #systemRequest}.
@@ -482,7 +482,7 @@ TableResult doTableRequest(TableRequest request,
      * state, provisioned throughput and capacity and schema. Dynamic
      * information such as usage is obtained using {@link #getTableUsage}.
      * Throughput, capacity and usage information is only available when using
-     * the Cloud Service and will be null or not defined on-premise.
+     * the Cloud Service and will be null or not defined on-premises.
      *
      * @param request the input parameters for the operation
      *
@@ -556,7 +556,7 @@ TableResult doTableRequest(TableRequest request,
     GetIndexesResult getIndexes(GetIndexesRequest request);
 
     /**
-     * On-premise only.
+     * On-premises only.
      * <p>
      * Returns the namespaces in a store as an array of String.
      *
@@ -565,16 +565,16 @@ TableResult doTableRequest(TableRequest request,
     String[] listNamespaces();
 
     /**
-     * On-premise only.
-     *
+     * On-premises only.
+     * <p>
      * Returns the roles in a store as an array of String.
      *
      * @return the list of roles or null if none are found
      */
     String[] listRoles();
 
     /**
-     * On-premise only.
+     * On-premises only.
      * <p>
      * Returns the users in a store as an array of {@link UserInfo}.
      *
@@ -583,7 +583,7 @@ TableResult doTableRequest(TableRequest request,
     UserInfo[] listUsers();
 
     /**
-     * On-premise only.
+     * On-premises only.
      * <p>
      * A convenience method that performs a SystemRequest and waits for
      * completion of the operation. This is the same as calling {@link

driver/src/main/java/oracle/nosql/driver/NoSQLHandleConfig.java

@@ -770,7 +770,7 @@ public NoSQLHandleConfig setPoolMaxPending(int poolMaxPending) {
 
     /**
      * Sets the maximum size in bytes of request/response payloads.
-     * On-premise only. This setting is ignored for cloud operations.
+     * On-premises only. This setting is ignored for cloud operations.
      * If not set, or set to zero, the default value of 32MB is used.
      *
      * @param maxContentLength the maximum bytes allowed in
@@ -790,7 +790,7 @@ public NoSQLHandleConfig setMaxContentLength(int maxContentLength) {
 
     /**
      * Returns the maximum size, in bytes, of a request operation payload.
-     * On-premise only. This value is ignored for cloud operations.
+     * On-premises only. This value is ignored for cloud operations.
      *
      * @return the size
      */

driver/src/main/java/oracle/nosql/driver/Nson.java

@@ -428,7 +428,7 @@ public static String toJsonString(ByteInputStream in) {
      *
      * @param in the input stream of NSON bytes
      * @param options {@link JsonOptions} to use for the serialization, or
-     * null for default behavior.Th
+     * null for default behavior
      * @return the JSON string
      * @throws IllegalArgumentException if there's a problem with serializing
      * NSON to JSON string

driver/src/main/java/oracle/nosql/driver/OperationNotSupportedException.java

@@ -9,7 +9,7 @@
 
 /**
  * The operation attempted is not supported. This may be related to
- * on-premise vs cloud service configurations.
+ * on-premises vs cloud service configurations.
  */
 public class OperationNotSupportedException extends NoSQLException {
 

driver/src/main/java/oracle/nosql/driver/UserInfo.java

@@ -8,7 +8,7 @@
 package oracle.nosql.driver;
 
 /**
- * On-premise only.
+ * On-premises only.
  * <p>
  * A class that encapsulates the information associated with a user including
  * the id and user name in the system.

driver/src/main/java/oracle/nosql/driver/http/Client.java

@@ -333,13 +333,15 @@ private int nextRequestId() {
     /**
      * Execute the KV request and return the response. This is the top-level
      * method for request execution.
-     *
+     * <p>
      * This method handles exceptions to distinguish between what can be retried
-     * what what cannot, making sure that root cause exceptions are
+     * and what cannot, making sure that root cause exceptions are
      * kept. Examples:
-     *  o can't connect (host, port, etc)
-     *  o throttling exceptions
-     *  o general networking issues, IOException
+     * <ul>
+     *  <li>can't connect (host, port, etc)</li>
+     *  <li>throttling exceptions</li>
+     *  <li>general networking issues, IOException</li>
+     * </ul>
      *
      * RequestTimeoutException needs a cause, or at least needs to include the
      * message from the causing exception.
@@ -576,7 +578,7 @@ public Result execute(Request kvRequest) {
                 serialVersionUsed = writeContent(buffer, kvRequest);
 
                 /*
-                 * If on-premise the authProvider will always be a
+                 * If on-premises the authProvider will always be a
                  * StoreAccessTokenProvider. If so, check against
                  * configurable limit. Otherwise check against internal
                  * hardcoded cloud limit.
@@ -948,7 +950,7 @@ private RateLimiter getQueryRateLimiter(Request request, boolean read) {
     }
 
     /**
-     * Comsume rate limiter units after successful operation.
+     * Consume rate limiter units after successful operation.
      * @return the number of milliseconds delayed due to rate limiting
      */
     private int consumeLimiterUnits(RateLimiter rl,
@@ -961,7 +963,7 @@ private int consumeLimiterUnits(RateLimiter rl,
         /*
          * The logic consumes units (and potentially delays) _after_ a
          * successful operation for a couple reasons:
-         * 1) We don't know the actual number of units an op uses unitl
+         * 1) We don't know the actual number of units an op uses until
          *    after the operation successfully finishes
          * 2) Delaying after the op keeps the application from immediately
          *    trying the next op and ending up waiting along with other
@@ -1105,7 +1107,7 @@ final Result processResponse(HttpResponseStatus status,
      *
      * @return the result of processing the successful request
      *
-     * @throws IOException if the stream could not be read for some reason
+     * @throws NoSQLException if the stream could not be read for some reason
      */
     Result processOKResponse(ByteInputStream in, Request kvRequest) {
         try {
@@ -1547,9 +1549,9 @@ void doRefresh(long refreshMs) {
     /**
      * Look for the compartment,table combination in the list. If
      * present, do nothing. If not, add that combination to the list.
-     * This is not particular efficient but it is not expected that a given
+     * This is not particularly efficient but it is not expected that a given
      * handle will be accessing a large number of tables.
-     *
+     * <p>
      * The operation type is not checked -- all 3 types of requests are created
      * no matter the access. This simplifies the logic and if a given type is
      * not given to this Principal it doesn't hurt.

driver/src/main/java/oracle/nosql/driver/httpclient/HttpClient.java

@@ -36,28 +36,30 @@
 import io.netty.util.concurrent.Future;
 /*
  * If this code is ever made generic, the proxy information obtained
- * from this config needs to be be abstracted to a generic class.
+ * from this config needs to be abstracted to a generic class.
  */
 import oracle.nosql.driver.NoSQLHandleConfig;
 
 /**
  * Netty HTTP client. Initialization process:
- *
- * 1. create event loop for handling connections and requests. Assign it
- * a number of threads.
- * 2. bootstrap a client, setting the event loop group, socket options, and
- * remote address.
- * 3. create a ChannelPoolHandler instance to handle callback events from
+ * <p>
+ * <ol>
+ *   <li>create event loop for handling connections and requests. Assign it
+ * a number of threads.</li>
+ *   <li>bootstrap a client, setting the event loop group, socket options, and
+ * remote address.</li>
+ *   <li>create a ChannelPoolHandler instance to handle callback events from
  * a ChannelPool. The pool is used to allow the client to create new
  * connections on demand if one is busy. HTTP/1.1 doesn't allow concurrent
  * use of a single connection. This handler must be prepared to initialize
- * each new connection on creation.
- * 4. create a ChannelPool instance used to acquire and release channels for
- * use by requests.
- *
+ * each new connection on creation.</li>
+ *   <li>create a ChannelPool instance used to acquire and release channels for
+ * use by requests.</li>
+ * </ol>
+ * <p>
  * Using the client to send request and get a synchronous response. The
  * request must be an instance of HttpRequest:
- *
+ * <p>
  * 1. Get a Channel.
  *   Channel channel = client.getChannel(timeoutMs);
  * 2. Create a ResponseHandler to handle a response.