docs: Managed Folders samples (#2562)

* docs: Managed Folders samples

* linter

update without managed folder name populated

lint

format bucketname

enable uniform bucket level access

moving config update

enabling uniform bucket level access

figure out why tests are failing

use format instead of

linter

fixing tests

finally fix test and add in other tests

linter

adding copyrights to tests

removing unnecessary changed to downloadbytesrangetest

* shutdown storage control instances

* Update samples/snippets/src/main/java/com/example/storage/managedfolders/CreateManagedFolder.java

Co-authored-by: BenWhitehead <BenWhitehead@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: BenWhitehead <BenWhitehead@users.noreply.github.com>

* pr comments

* linter

---------

Co-authored-by: BenWhitehead <BenWhitehead@users.noreply.github.com>

samples/snippets/src/main/java/com/example/storage/managedfolders/CreateManagedFolder.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.storage.managedfolders;
+
+// [START storage_control_managed_folder_create]
+
+import com.google.storage.control.v2.BucketName;
+import com.google.storage.control.v2.CreateManagedFolderRequest;
+import com.google.storage.control.v2.ManagedFolder;
+import com.google.storage.control.v2.StorageControlClient;
+
+public class CreateManagedFolder {
+  public static void managedFolderCreate(String bucketName, String managedFolderId)
+      throws Exception {
+
+    // Instantiates a client in a try-with-resource to automatically cleanup underlying resources
+    try (StorageControlClient storageControlClient = StorageControlClient.create()) {
+      CreateManagedFolderRequest request =
+          CreateManagedFolderRequest.newBuilder()
+              // Set project to "_" to signify global bucket
+              .setParent(BucketName.format("_", bucketName))
+          .setManagedFolder(ManagedFolder.newBuilder().build())
+          .setManagedFolderId(managedFolderId).build();
+      String response = storageControlClient.createManagedFolder(request).getName();
+      System.out.printf("Performed createManagedFolder request for %s%n", response);
+    }
+  }
+}
+// [END storage_control_managed_folder_create]

samples/snippets/src/main/java/com/example/storage/managedfolders/DeleteManagedFolder.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.storage.managedfolders;
+
+// [START storage_control_managed_folder_delete]
+import com.google.storage.control.v2.BucketName;
+import com.google.storage.control.v2.DeleteManagedFolderRequest;
+import com.google.storage.control.v2.ManagedFolderName;
+import com.google.storage.control.v2.StorageControlClient;
+
+class DeleteManagedFolder {
+  public static void managedFolderDelete(String bucketName, String managedFolderId)
+      throws Exception {
+    // Instantiates a client in a try-with-resource to automatically cleanup underlying resources
+    try (StorageControlClient storageControlClient = StorageControlClient.create()) {
+      // Set project to "_" to signify global bucket
+      BucketName resourceBucketName = BucketName.of("_", bucketName);
+      DeleteManagedFolderRequest deleteManagedFolderRequest =
+          DeleteManagedFolderRequest.newBuilder()
+          .setName(
+              ManagedFolderName.format(
+                  resourceBucketName.getProject(),
+                  resourceBucketName.getBucket(),
+                  managedFolderId)
+          )
+          .build();
+      storageControlClient.deleteManagedFolder(deleteManagedFolderRequest);
+      System.out.printf("Deleted Managed Folder %s%n", managedFolderId);
+    }
+  }
+
+}
+
+// [END storage_control_managed_folder_delete]

samples/snippets/src/main/java/com/example/storage/managedfolders/GetManagedFolder.java

@@ -0,0 +1,49 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.storage.managedfolders;
+
+// [START storage_control_managed_folder_get]
+
+import com.google.storage.control.v2.BucketName;
+import com.google.storage.control.v2.GetManagedFolderRequest;
+import com.google.storage.control.v2.ManagedFolder;
+import com.google.storage.control.v2.ManagedFolderName;
+import com.google.storage.control.v2.StorageControlClient;
+
+class GetManagedFolder {
+
+  public static void managedFolderGet(String bucketName, String managedFolderId) throws Exception {
+    // Instantiates a client in a try-with-resource to automatically cleanup underlying resources
+    try (StorageControlClient storageControlClient = StorageControlClient.create()) {
+      // Set project to "_" to signify global bucket
+      BucketName resourceBucketName = BucketName.of("_", bucketName);
+      GetManagedFolderRequest getManagedFolderRequest =
+          GetManagedFolderRequest.newBuilder()
+              .setName(
+                  ManagedFolderName.format(
+                      resourceBucketName.getProject(),
+                      resourceBucketName.getBucket(),
+                      managedFolderId))
+              .build();
+      ManagedFolder managedFolder = storageControlClient.getManagedFolder(getManagedFolderRequest);
+      System.out.printf("Got Managed Folder %s%n", managedFolder.getName());
+    }
+  }
+
+}
+
+// [END storage_control_managed_folder_get]

samples/snippets/src/main/java/com/example/storage/managedfolders/ListManagedFolders.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.storage.managedfolders;
+
+// [START storage_control_managed_folder_list]
+
+import com.google.storage.control.v2.BucketName;
+import com.google.storage.control.v2.ListManagedFoldersRequest;
+import com.google.storage.control.v2.ManagedFolder;
+import com.google.storage.control.v2.StorageControlClient;
+
+class ListManagedFolders {
+
+  public static void managedFolderList(String bucketName) throws Exception {
+    // Instantiates a client in a try-with-resource to automatically cleanup underlying resources
+    try (StorageControlClient storageControlClient = StorageControlClient.create()) {
+      ListManagedFoldersRequest listManagedFoldersRequest =
+          ListManagedFoldersRequest.newBuilder()
+              // Set project to "_" to signify global bucket
+              .setParent(BucketName.format("_", bucketName))
+              .build();
+      Iterable<ManagedFolder> managedFolders =
+          storageControlClient.listManagedFolders(listManagedFoldersRequest).iterateAll();
+      for (ManagedFolder folder : managedFolders) {
+        System.out.printf("%s bucket has managed folder %s%n", bucketName, folder.getName());
+      }
+    }
+  }
+}
+
+// [END storage_control_managed_folder_list]

samples/snippets/src/test/java/com/example/storage/managedfolders/CreateManagedFolderTest.java

@@ -0,0 +1,81 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.storage.managedfolders;
+
+import static com.google.common.truth.Truth.assertThat;
+
+import com.google.cloud.storage.Bucket;
+import com.google.cloud.storage.BucketInfo;
+import com.google.cloud.storage.BucketInfo.IamConfiguration;
+import com.google.cloud.storage.Storage;
+import com.google.cloud.storage.StorageOptions;
+import com.google.cloud.storage.testing.RemoteStorageHelper;
+import com.google.cloud.testing.junit4.StdOutCaptureRule;
+import com.google.storage.control.v2.DeleteManagedFolderRequest;
+import com.google.storage.control.v2.ManagedFolderName;
+import com.google.storage.control.v2.StorageControlClient;
+import java.io.IOException;
+import java.util.UUID;
+import org.junit.After;
+import org.junit.Before;
+import org.junit.Rule;
+import org.junit.Test;
+
+public class CreateManagedFolderTest {
+
+  @Rule
+  public StdOutCaptureRule stdOut = new StdOutCaptureRule();
+
+  protected String bucketName;
+  protected Storage storage;
+  protected Bucket bucket;
+  protected String managedFolderId;
+  protected StorageControlClient storageControl;
+
+  @Before
+  public void setUp() throws IOException {
+    bucketName = RemoteStorageHelper.generateBucketName();
+    storageControl = StorageControlClient.create();
+    storage = StorageOptions.getDefaultInstance().getService();
+    managedFolderId = "new-managed-folder-" + UUID.randomUUID();
+    BucketInfo bucketInfo = BucketInfo.newBuilder(bucketName)
+        .setIamConfiguration(
+        IamConfiguration
+            .newBuilder()
+            .setIsUniformBucketLevelAccessEnabled(true)
+        .build()).build();
+    bucket = storage.create(bucketInfo);
+  }
+
+  @After
+  public void tearDown() {
+    storageControl.deleteManagedFolder(
+        DeleteManagedFolderRequest.newBuilder().setName(
+            ManagedFolderName.format("_", bucketName, managedFolderId)
+        ).build());
+    storage.delete(bucketName);
+    storageControl.shutdown();
+  }
+
+  @Test
+  public void testCreateManagedFolder() throws Exception {
+    CreateManagedFolder.managedFolderCreate(bucketName, managedFolderId);
+    String got = stdOut.getCapturedOutputAsUtf8String();
+    assertThat(got).contains(String.format(managedFolderId));
+  }
+}
+

samples/snippets/src/test/java/com/example/storage/managedfolders/DeleteManagedFolderTest.java

@@ -0,0 +1,83 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.storage.managedfolders;
+
+import static com.google.common.truth.Truth.assertThat;
+
+import com.google.cloud.storage.Bucket;
+import com.google.cloud.storage.BucketInfo;
+import com.google.cloud.storage.BucketInfo.IamConfiguration;
+import com.google.cloud.storage.Storage;
+import com.google.cloud.storage.StorageOptions;
+import com.google.cloud.storage.testing.RemoteStorageHelper;
+import com.google.cloud.testing.junit4.StdOutCaptureRule;
+import com.google.storage.control.v2.BucketName;
+import com.google.storage.control.v2.CreateManagedFolderRequest;
+import com.google.storage.control.v2.ManagedFolder;
+import com.google.storage.control.v2.StorageControlClient;
+import java.io.IOException;
+import java.util.UUID;
+import org.junit.After;
+import org.junit.Before;
+import org.junit.Rule;
+import org.junit.Test;
+
+public class DeleteManagedFolderTest {
+
+  @Rule
+  public StdOutCaptureRule stdOut = new StdOutCaptureRule();
+
+  protected String bucketName;
+  protected Storage storage;
+  protected Bucket bucket;
+  protected String managedFolderId;
+  protected StorageControlClient storageControl;
+
+  @Before
+  public void setUp() throws IOException {
+    bucketName = RemoteStorageHelper.generateBucketName();
+    storageControl = StorageControlClient.create();
+    storage = StorageOptions.getDefaultInstance().getService();
+    managedFolderId = "new-managed-folder-" + UUID.randomUUID();
+    BucketInfo bucketInfo = BucketInfo.newBuilder(bucketName)
+        .setIamConfiguration(
+            IamConfiguration
+                .newBuilder()
+                .setIsUniformBucketLevelAccessEnabled(true)
+                .build()).build();
+    bucket = storage.create(bucketInfo);
+    storageControl.createManagedFolder(
+        CreateManagedFolderRequest.newBuilder()
+            // Set project to "_" to signify global bucket
+            .setParent(BucketName.format("_", bucketName))
+            .setManagedFolder(ManagedFolder.newBuilder().build())
+            .setManagedFolderId(managedFolderId).build());
+  }
+
+  @After
+  public void tearDown() {
+    storage.delete(bucketName);
+    storageControl.shutdown();
+  }
+
+  @Test
+  public void testDeleteManagedFolder() throws Exception {
+    DeleteManagedFolder.managedFolderDelete(bucketName, managedFolderId);
+    String got = stdOut.getCapturedOutputAsUtf8String();
+    assertThat(got).contains(String.format(managedFolderId));
+  }
+}