Merge pull request #67 from scalar-labs/add-updated-docs

Add updated docs for adding ScalarDB and ScalarDB SQL to builds
scalar-labs · Aug 31, 2023 · d0ec8a2 · d0ec8a2
2 parents 460ce9e + 29e703b
commit d0ec8a2
Show file tree

Hide file tree

Showing 34 changed files with 515 additions and 793 deletions.
diff --git a/docs/3.10/add-scalardb-to-your-build.md b/docs/3.10/add-scalardb-to-your-build.md
@@ -1,20 +1,37 @@
-# Add ScalarDB to your build
+# Add ScalarDB to Your Build
 
-The library is available on [maven central repository](https://mvnrepository.com/artifact/com.scalar-labs/scalardb).
-You can install it in your application using your build tool such as Gradle and Maven. 
+The ScalarDB library is available on the [Maven Central Repository](https://mvnrepository.com/artifact/com.scalar-labs/scalardb). You can add the library as a build dependency to your application by using Gradle or Maven.
+
+## Configure your application based on your build tool
+
+Select your build tool, and follow the instructions to add the build dependency for ScalarDB to your application.
+
+<div id="tabset-1">
+<div class="tab">
+  <button class="tablinks" onclick="openTab(event, 'Gradle', 'tabset-1')" id="defaultOpen-1">Gradle</button>
+  <button class="tablinks" onclick="openTab(event, 'Maven', 'tabset-1')">Maven</button>
+</div>
+
+<div id="Gradle" class="tabcontent" markdown="1">
+
+To add the build dependency for ScalarDB by using Gradle, add the following to `build.gradle` in your application, replacing `<VERSION>` with the version of ScalarDB that you want to use:
 
-To add a dependency on ScalarDB using Gradle, use the following:
 ```gradle
 dependencies {
-    implementation 'com.scalar-labs:scalardb:3.10.1'
+  implementation 'com.scalar-labs:scalardb:<VERSION>'
 }
 ```
+</div>
+<div id="Maven" class="tabcontent" markdown="1">
+
+To add the build dependency for ScalarDB by using Maven, add the following to `pom.xml` in your application, replacing `<VERSION>` with the version of ScalarDB that you want to use:
 
-To add a dependency using Maven:
 ```xml
 <dependency>
   <groupId>com.scalar-labs</groupId>
   <artifactId>scalardb</artifactId>
-  <version>3.10.1</version>
+  <version><VERSION></version>
 </dependency>
 ```
+</div>
+</div>
diff --git a/docs/3.10/scalardb-sql/add-scalardb-sql-to-your-build.md b/docs/3.10/scalardb-sql/add-scalardb-sql-to-your-build.md
@@ -1,39 +1,93 @@
-# Add ScalarDB SQL to your build
+# Add ScalarDB SQL to Your Build
 
-The libraries for ScalarDB SQL are available on [Packages in this repository](https://github.com/orgs/scalar-labs/packages?repo_name=scalardb-sql).
-Since they are available under a commercial license, you need to get the license and permission to access them.
-For more details, please [contact us](https://scalar-labs.com/contact_us/).
+The ScalarDB SQL libraries are available as [packages on GitHub](https://github.com/orgs/scalar-labs/packages?repo_name=scalardb-sql). You can add the libraries as a build dependency to your application by using Gradle or Maven.
 
-Before you add the dependency, you need to add the Maven repository using your build tool such as Gradle and Maven.
+{% capture notice--warning %}
+**Attention**
+
+You must have a commmercial license and permission to access the ScalarDB SQL libraries. If you need a commercial license, please [contact us](https://scalar-labs.com/contact_us/).
+{% endcapture %}
+
+<div class="notice--warning">{{ notice--warning | markdownify }}</div>
+
+## Configure your application based on your build tool
+
+Select your build tool, and follow the instructions to add the build dependency for ScalarDB SQL for your application.
+
+<div id="tabset-1">
+<div class="tab">
+  <button class="tablinks" onclick="openTab(event, 'Gradle', 'tabset-1')" id="defaultOpen-1">Gradle</button>
+  <button class="tablinks" onclick="openTab(event, 'Maven', 'tabset-1')">Maven</button>
+</div>
+
+<div id="Gradle" class="tabcontent" markdown="1">
+
+The following instructions describe how to add the build dependency for ScalarDB SQL to your application by using Gradle. For details about using package repositories with Gradle, see [Working with the Gradle registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-gradle-registry).
+
+## Configure your GitHub credentials for Gradle
+{:.no_toc}
+
+Before adding the build dependency for ScalarDB SQL to your application by using Gradle, you need to configure your GitHub credentials to access the package repository.
+
+To access the dependency on GitHub, add the following to `build.gradle` in your application:
 
-To add the Maven repository using Gradle, add the following repository to your `build.gradle`:
 ```gradle
 repositories {
-    maven {
-        url = uri("https://maven.pkg.github.com/scalar-labs/scalardb-sql")
-        credentials {
-            username = project.findProperty("gpr.user") ?: System.getenv("USERNAME")
-            password = project.findProperty("gpr.key") ?: System.getenv("TOKEN")
-        }
+  maven {
+    url = uri("https://maven.pkg.github.com/scalar-labs/scalardb-sql")
+    credentials {
+      username = project.findProperty("gpr.user") ?: System.getenv("USERNAME")
+      password = project.findProperty("gpr.key") ?: System.getenv("TOKEN")
     }
+  }
 }
 ```
 
-In this case, you need the `gpr.user` property for your GitHub username and the `gpr.key` property for your personal access token.
-So you need to have the properties in `~/.gradle/gradle.properties`, or specify the properties with the `-P` option when running the `./gradlew` command as follows:
+To configure the `gpr.user` property for your GitHub username and the `gpr.key` property for your personal access token, do one of the following:
 
-```shell
-$ ./gradlew build -Pgpr.user=<your GitHub username> -Pgpr.key=<your personal access token>
-```
+- **Store your GitHub credentials as properties in `~/.gradle/gradle.properties`**
+  - Open `~/.gradle/gradle.properties`, and store your GitHub credentials as properties by running the following command, replacing `<GITHUB_USERNAME>` with your username and `<GITHUB_PERSONAL_ACCESS_TOKEN>` with a personal access token:
+  ```shell
+  $ ./gradlew build -Pgpr.user=<GITHUB_USERNAME> -Pgpr.key=<GITHUB_PERSONAL_ACCESS_TOKEN>
+  ```
+
+- **Store your GitHub credentials as environment variables**
+  1. Open a terminal window, and store your GitHub username as an environment variable by running the following command, replacing `<GITHUB_USERNAME>` with your username:
+  ```shell
+  $ export USERNAME=<GITHUB_USERNAME>
+  ```
+  1. Store your GitHub personal access token as an environment variable by running the following command, replacing `<GITHUB_PERSONAL_ACCESS_TOKEN>` with a personal access token:
+  ```shell
+  $ export TOKEN=<GITHUB_PERSONAL_ACCESS_TOKEN>
+  ```
 
-Or you can also use environment variables, `USERNAME` for your GitHub username and `TOKEN` for your personal access token.
+## Add the build dependency for ScalarDB SQL by using Gradle
+{:.no_toc}
+
+After specifying your GitHub credentials, add the following ScalarDB SQL dependency to `build.gradle` in your application, replacing `<VERSION>` with the version of ScalarDB SQL that you want to use:
+
+```gradle
+dependencies {
+  // For Direct mode
+  implementation 'com.scalar-labs:scalardb-sql-direct-mode:<VERSION>'
 
-```shell
-$ export USERNAME=<your GitHub username>
-$ export TOKEN=<your personal access token>
+  // For Server mode
+  implementation 'com.scalar-labs:scalardb-sql-server-mode:<VERSION>'
+}
 ```
 
-To add the Maven repository using Maven, edit your `~/.m2/settings.xml` file as follows:
+</div>
+<div id="Maven" class="tabcontent" markdown="1">
+
+The following instructions describe how to add the build dependency for ScalarDB SQL to your application by using Maven. For details about using package repositories with Maven, see [Working with the Apache Maven registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry)
+
+## Configure your GitHub credentials for Maven
+{:.no_toc}
+
+Before adding the build dependency for ScalarDB SQL to your application by using Maven, you need to configure your GitHub credentials to access the package repository.
+
+To access the dependency on GitHub, add the following to `~/.m2/settings.xml` in your application, replacing `<GITHUB_USERNAME>` with your username and `<GITHUB_PERSONAL_ACCESS_TOKEN>` with a personal access token in the child `server` in the `servers` tag:
+
 ```xml
 <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -66,47 +120,35 @@ To add the Maven repository using Maven, edit your `~/.m2/settings.xml` file as
   <servers>
     <server>
       <id>github</id>
-      <username>USERNAME</username>
-      <password>TOKEN</password>
+      <username><GITHUB_USERNAME></username>
+      <password><GITHUB_PERSONAL_ACCESS_TOKEN></password>
     </server>
   </servers>
 </settings>
 ```
 
-In the `servers` tag, add a child `server` tag with an `id`, replacing *USERNAME* with your GitHub username, and *TOKEN* with your personal access token.
-
-Please see also the following documents for more details:
-- [Working with the Gradle registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-gradle-registry)
-- [Working with the Apache Maven registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry)
+## Add the build dependency for ScalarDB SQL by using Maven
+{:.no_toc}
 
-And then, you can install the library in your application using your build tool such as Gradle and Maven.
+After specifying your GitHub credentials, add the following ScalarDB SQL dependency to `pom.xml` in your application, replacing `<VERSION>` with the version of ScalarDB SQL that you want to use:
 
-To add a dependency on ScalarDB SQL using Gradle, use the following:
-```gradle
-dependencies {
-    // For Direct mode
-    implementation 'com.scalar-labs:scalardb-sql-direct-mode:3.10.1'
-
-    // For Server mode
-    implementation 'com.scalar-labs:scalardb-sql-server-mode:3.10.1'
-}
-```
-
-To add a dependency using Maven:
 ```xml
 <dependencies>
   <!-- For Direct mode -->
   <dependency>
     <groupId>com.scalar-labs</groupId>
     <artifactId>scalardb-sql-direct-mode</artifactId>
-    <version>3.10.1</version>
+    <version><VERSION></version>
   </dependency>
 
   <!-- For Server mode -->
   <dependency>
     <groupId>com.scalar-labs</groupId>
     <artifactId>scalardb-sql-server-mode</artifactId>
-    <version>3.10.1</version>
+    <version><VERSION></version>
   </dependency>
 </dependencies>
 ```
+
+</div>
+</div>
diff --git a/docs/3.10/scalardb-sql/javadoc/core/com/scalar/db/sql/PreparedStatement.html b/docs/3.10/scalardb-sql/javadoc/core/com/scalar/db/sql/PreparedStatement.html
@@ -685,14 +685,11 @@ <h4>execute</h4>
 <dt><span class="returnLabel">Returns:</span></dt>
 <dd>a <a href="../../../../com/scalar/db/sql/ResultSet.html" title="interface in com.scalar.db.sql"><code>ResultSet</code></a> object that contains the data produced by the query</dd>
 <dt><span class="throwsLabel">Throws:</span></dt>
-<dd><code><a href="../../../../com/scalar/db/sql/exception/TransactionRetryableException.html" title="class in com.scalar.db.sql.exception">TransactionRetryableException</a></code> - if the transaction operation execution fails due to
-     retryable faults (e.g., a transaction conflict). You can retry the transaction from the
-     beginning.</dd>
+<dd><code><a href="../../../../com/scalar/db/sql/exception/TransactionRetryableException.html" title="class in com.scalar.db.sql.exception">TransactionRetryableException</a></code> - if a retryable error happens (e.g., a transaction
+     conflict)</dd>
 <dd><code><a href="../../../../com/scalar/db/sql/exception/UnknownTransactionStatusException.html" title="class in com.scalar.db.sql.exception">UnknownTransactionStatusException</a></code> - if the transaction status (committed or aborted) is
      unknown when executing the COMMIT statement</dd>
-<dd><code><a href="../../../../com/scalar/db/sql/exception/SqlException.html" title="class in com.scalar.db.sql.exception">SqlException</a></code> - if the transaction operation execution fails due to transient or
-     nontransient faults. You can try retrying the transaction from the beginning, but the
-     transaction may still fail if the cause is nontranient</dd>
+<dd><code><a href="../../../../com/scalar/db/sql/exception/SqlException.html" title="class in com.scalar.db.sql.exception">SqlException</a></code> - if an unexpected error happens</dd>
 </dl>
 </li>
 </ul>