[SM-1268] Review Java docs (#871)

## 🎟️ Tracking https://bitwarden.atlassian.net/browse/SM-1268 ## 📔 Objective Review Java language docs. ## ⏰ Reminders before review - Contributor guidelines followed - All formatters and local linters executed and passed - Written new unit and / or integration tests where applicable - Protected functional changes with optionality (feature flags) - Used internationalization (i18n) for all UI strings - CI builds passed - Communicated to DevOps any deployment requirements - Updated any necessary documentation (Confluence, contributing docs) or informed the documentation team ## 🦮 Reviewer guidelines  - 👍 (`:+1:`) or similar for great changes - 📝 (`:memo:`) or ℹ️ (`:information_source:`) for notes or general info - ❓ (`:question:`) for questions - 🤔 (`:thinking:`) or 💭 (`:thought_balloon:`) for more open inquiry that's not quite a confirmed issue and could potentially benefit from discussion - 🎨 (`:art:`) for suggestions / improvements - ❌ (`:x:`) or ⚠️ (`:warning:`) for more significant problems or concerns needing attention - 🌱 (`:seedling:`) or ♻️ (`:recycle:`) for future improvements or indications of technical debt - ⛏ (`:pick:`) for minor or nitpick changes --------- Co-authored-by: Thomas Avery <[email protected]>
bitwarden · Jul 9, 2024 · 91cf1a5 · 91cf1a5
1 parent 6decd1f
commit 91cf1a5
Show file tree

Hide file tree

Showing 7 changed files with 171 additions and 55 deletions.
diff --git a/languages/java/Example.java b/languages/java/Example.java
diff --git a/languages/java/INSTALL.md b/languages/java/INSTALL.md
@@ -0,0 +1,52 @@
+# Java build
+
+## Introduction
+
+Gradle is used to build Java Bitwarden client library.
+
+The output of the build is placed in `build/libs` directory and should contain `BitwardenSDK.jar` file.
+
+## Prerequisites
+
+- JDK 17 installed.
+- Bitwarden SDK native library build. See [SDK README.md](../../README.md) for instructions.
+
+## Build Commands
+
+```shell
+./gradlew build
+```
+
+## Example
+
+### macOS
+
+#### Install Prerequisites
+
+Use brew to install JDK 17.
+
+```shell
+brew install --cask temurin@17
+brew install jenv
+export PATH="$HOME/.jenv/bin:$PATH"
+eval "$(jenv init -)"
+jenv add /Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home
+jenv shell 17
+```
+
+#### Build Commands
+
+```shell
+./gradlew build
+```
+
+## Example SDK Usage Project
+
+```shell
+export ACCESS_TOKEN="<access_token>"
+export ORGANIZATION_ID="<organization_id>"
+export API_URL="https://api.bitwarden.com"
+export IDENTITY_URL="https://identity.bitwarden.com"
+
+./gradlew :example:run
+```
diff --git a/languages/java/README.md b/languages/java/README.md
@@ -12,6 +12,8 @@ Review the help documentation on [Access Tokens]
 ### Create new Bitwarden client
 
 ```java
+import com.bitwarden.sdk.*;
+
 BitwardenSettings bitwardenSettings = new BitwardenSettings();
 bitwardenSettings.setApiUrl("https://api.bitwarden.com");
 bitwardenSettings.setIdentityUrl("https://identity.bitwarden.com");
@@ -24,6 +26,13 @@ bitwardenClient.accessTokenLogin("<access-token>");
 ```java
 UUID organizationId = UUID.fromString("<organization-id>");
 var projectResponse = bitwardenClient.projects().create(organizationId, "TestProject");
+UUID projectId = projectResponse.getID();
+```
+
+### Get project
+
+```java
+var projectResponse = bitwardenClient.projects().get(projectId);
 ```
 
 ### List all projects
@@ -35,9 +44,7 @@ var projectsResponse = bitwardenClient.projects().list(organizationId);
 ### Update project
 
 ```java
-UUID projectId = projectResponse.getID();
-projectResponse = bitwardenClient.projects().get(projectId);
-projectResponse = bitwardenClient.projects.update(projectId, organizationId, "TestProjectUpdated");
+var projectResponse = bitwardenClient.projects().update(projectId, organizationId, "TestProjectUpdated");
 ```
 
 ### Add new secret
@@ -50,24 +57,30 @@ var secretResponse = bitwardenClient.secrets().create(key, value, note, organiza
 UUID secretId = secretResponse.getID();
 ```
 
+### Get secret
+
+```java
+var secretResponse = bitwardenClient.secrets().get(secretId);
+```
+
 ### Update secret
 
 ```java
-bitwardenClient.secrets().update(secretId, key2, value2, note2, organizationId, new UUID[]{projectId});
+var secretResponse = bitwardenClient.secrets().update(secretId, key2, value2, note2, organizationId, new UUID[]{projectId});
 ```
 
 ### List secrets
 
 ```java
-var secretIdentifiersResponse secretIdentifiersResponse = bitwardenClient.secrets().list(organizationId);
+var secretIdentifiersResponse = bitwardenClient.secrets().list(organizationId);
 ```
 
-# Delete secret or project
+### Delete secret or project
 
 ```java
 bitwardenClient.secrets().delete(new UUID[]{secretId});
 bitwardenClient.projects().delete(new UUID[]{projectId});
 ```
 
 [Access Tokens]: https://bitwarden.com/help/access-tokens/
-[Bitwarden Secrets Manager]: https://bitwarden.com/products/secrets-manager/
+[Bitwarden Secrets Manager]: https://bitwarden.com/products/secrets-manager/
diff --git a/languages/java/build.gradle b/languages/java/build.gradle
@@ -81,18 +81,25 @@ java {
     withSourcesJar()
 }
 
-//  Gradle build requires GitHub workflow to copy native library to resources
-//  Uncomment copyNativeLib and jar tasks to use the local build (modify architecture if needed)
-//tasks.register('copyNativeLib', Copy) {
-//    delete 'src/main/resources/darwin-aarch64'
-//    from '../../target/debug'
-//    include '*libbitwarden_c*.dylib'
-//    include '*libbitwarden_c*.so'
-//    include '*bitwarden_c*.dll'
-//    into 'src/main/resources/darwin-aarch64'
-//}
-//
-//jar {
-//    dependsOn tasks.named("copyNativeLib").get()
-//    from 'src/main/resources'
-//}
+jar {
+    // Copy native library to jar resources for local gradle build
+    if (System.getenv("GITHUB_TOKEN") == null) {
+        from('../../target/debug') {
+            include '*libbitwarden_c*.dylib'
+            into "darwin-x86-64"
+        }
+        from('../../target/debug') {
+            include '*libbitwarden_c*.dylib'
+            into "darwin-aarch64"
+        }
+        from('../../target/debug') {
+            include '*libbitwarden_c*.so'
+            into "linux-x86-64"
+        }
+        from('../../target/debug') {
+            include '*bitwarden_c*.dll'
+            into "win32-x86-64"
+        }
+    }
+}
+
diff --git a/languages/java/example/Example.java b/languages/java/example/Example.java
@@ -0,0 +1,52 @@
+import java.lang.System;
+import java.util.UUID;
+
+import com.bitwarden.sdk.*;
+import com.bitwarden.sdk.schema.*;
+
+class Example {
+    public static void main(String[] args) {
+        if (!System.getenv().containsKey("ACCESS_TOKEN") || !System.getenv().containsKey("ORGANIZATION_ID")) {
+            System.err.println("Missing environment variable ACCESS_TOKEN or ORGANIZATION_ID");
+            System.exit(1);
+        }
+
+        String accessToken = System.getenv("ACCESS_TOKEN");
+        UUID organizationId = UUID.fromString(System.getenv("ORGANIZATION_ID"));
+        String apiUrl = System.getenv("API_URL");
+        String identityUrl = System.getenv("IDENTITY_URL");
+
+        // Configuring the URLS is optional, remove them to use the default values
+        BitwardenSettings bitwardenSettings = new BitwardenSettings();
+        bitwardenSettings.setApiUrl(apiUrl);
+        bitwardenSettings.setIdentityUrl(identityUrl);
+
+        try (BitwardenClient client = new BitwardenClient(bitwardenSettings)) {
+            client.accessTokenLogin(accessToken);
+
+            ProjectResponse project = client.projects().create(organizationId, "Test Project");
+            System.out.println("Project id: " + project.getID());
+
+            project = client.projects().get(project.getID());
+
+            ProjectsResponse projects = client.projects().list(organizationId);
+            System.out.println("Projects count: " + projects.getData().length);
+
+            client.projects().update(project.getID(), organizationId, "Updated Test Project");
+
+            SecretResponse secret = client.secrets().create("Secret Key", "Secret Value", "Secret Note",
+                organizationId, new UUID[]{project.getID()});
+            System.out.println("Secret id: " + secret.getID());
+
+            secret = client.secrets().get(secret.getID());
+
+            SecretIdentifiersResponse secrets = client.secrets().list(organizationId);
+            System.out.println("Secrets count: " + secrets.getData().length);
+
+            client.secrets().update(secret.getID(), "Updated Key", "Updated Value", "Updated Noye", organizationId, new UUID[]{project.getID()});
+
+            client.secrets().delete(new UUID[]{secret.getID()});
+            client.projects().delete(new UUID[]{project.getID()});
+        }
+    }
+}
diff --git a/languages/java/example/build.gradle b/languages/java/example/build.gradle
@@ -0,0 +1,23 @@
+plugins {
+    id 'application'
+}
+
+repositories {
+    mavenLocal()
+    mavenCentral()
+}
+
+dependencies {
+    implementation rootProject
+}
+
+application {
+    mainClass = 'Example'
+}
+
+sourceSets {
+    main {
+        java.srcDirs += '.'
+    }
+}
+
diff --git a/languages/java/settings.gradle b/languages/java/settings.gradle
@@ -3,3 +3,5 @@
  */
 
 rootProject.name = 'BitwardenSDK'
+
+include "example"
Original file line number	Diff line number	Diff line change
Expand Up		@@ -3,3 +3,5 @@
		*/

		rootProject.name = 'BitwardenSDK'

		include "example"