docs: add Hierarchical Namespace Bucket and Folders samples (#2583)

New samples
* `storage_create_bucket_hierarchical_namespace`
* `storage_control_create_folder`
* `storage_control_delete_folder`
* `storage_control_get_folder`
* `storage_control_list_folders`
* `storage_control_rename_folder`

Fixes #2569

samples/snippets/src/main/java/com/example/storage/control/v2/CreateFolder.java

@@ -0,0 +1,50 @@
+/*
+ * 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.control.v2;
+
+// [START storage_control_create_folder]
+import com.google.storage.control.v2.BucketName;
+import com.google.storage.control.v2.CreateFolderRequest;
+import com.google.storage.control.v2.Folder;
+import com.google.storage.control.v2.StorageControlClient;
+import java.io.IOException;
+
+public final class CreateFolder {
+
+  public static void createFolder(String bucketName, String folderName) throws IOException {
+    // The name of the bucket
+    // String bucketName = "your-unique-bucket-name";
+
+    // The name of the folder within the bucket
+    // String folderName = "your-unique-folder-name";
+
+    try (StorageControlClient storageControl = StorageControlClient.create()) {
+
+      CreateFolderRequest request =
+          CreateFolderRequest.newBuilder()
+              // Set project to "_" to signify globally scoped bucket
+              .setParent(BucketName.format("_", bucketName))
+              .setFolderId(folderName)
+              .build();
+
+      Folder newFolder = storageControl.createFolder(request);
+
+      System.out.printf("Created folder: %s%n", newFolder.getName());
+    }
+  }
+}
+// [END storage_control_create_folder]

samples/snippets/src/main/java/com/example/storage/control/v2/CreateHierarchicalNamespaceBucket.java

@@ -0,0 +1,54 @@
+/*
+ * 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.control.v2;
+
+// [START storage_create_bucket_hierarchical_namespace]
+import com.google.cloud.storage.Bucket;
+import com.google.cloud.storage.BucketInfo;
+import com.google.cloud.storage.BucketInfo.HierarchicalNamespace;
+import com.google.cloud.storage.BucketInfo.IamConfiguration;
+import com.google.cloud.storage.Storage;
+import com.google.cloud.storage.StorageOptions;
+
+public final class CreateHierarchicalNamespaceBucket {
+
+  public static void createHierarchicalNamespaceBucket(String projectId, String bucketName)
+      throws Exception {
+    // The ID of your GCP project
+    // String projectId = "your-project-id";
+
+    // The ID to give your GCS bucket
+    // String bucketName = "your-unique-bucket-name";
+    StorageOptions storageOptions = StorageOptions.newBuilder().setProjectId(projectId).build();
+    try (Storage storage = storageOptions.getService()) {
+
+      BucketInfo bucketInfo =
+          BucketInfo.newBuilder(bucketName)
+              .setIamConfiguration(
+                  // Hierarchical namespace buckets must use uniform bucket-level access.
+                  IamConfiguration.newBuilder().setIsUniformBucketLevelAccessEnabled(true).build())
+              .setHierarchicalNamespace(HierarchicalNamespace.newBuilder().setEnabled(true).build())
+              .build();
+
+      Bucket bucket = storage.create(bucketInfo);
+
+      System.out.printf(
+          "Created bucket %s with Hierarchical Namespace enabled.%n", bucket.getName());
+    }
+  }
+}
+// [END storage_create_bucket_hierarchical_namespace]

samples/snippets/src/main/java/com/example/storage/control/v2/DeleteFolder.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.control.v2;
+
+// [START storage_control_delete_folder]
+
+import com.google.storage.control.v2.DeleteFolderRequest;
+import com.google.storage.control.v2.FolderName;
+import com.google.storage.control.v2.StorageControlClient;
+import java.io.IOException;
+
+public final class DeleteFolder {
+
+  public static void deleteFolder(String bucketName, String folderName) throws IOException {
+    // The name of the bucket
+    // String bucketName = "your-unique-bucket-name";
+
+    // The name of the folder within the bucket
+    // String folderName = "your-unique-folder-name";
+
+    try (StorageControlClient storageControl = StorageControlClient.create()) {
+
+      // Set project to "_" to signify globally scoped bucket
+      String folderResourceName = FolderName.format("_", bucketName, folderName);
+      DeleteFolderRequest request =
+          DeleteFolderRequest.newBuilder().setName(folderResourceName).build();
+
+      storageControl.deleteFolder(request);
+
+      System.out.printf("Deleted folder: %s%n", folderResourceName);
+    }
+  }
+}
+// [END storage_control_delete_folder]

samples/snippets/src/main/java/com/example/storage/control/v2/GetFolder.java

@@ -0,0 +1,50 @@
+/*
+ * 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.control.v2;
+
+// [START storage_control_get_folder]
+
+import com.google.storage.control.v2.Folder;
+import com.google.storage.control.v2.FolderName;
+import com.google.storage.control.v2.GetFolderRequest;
+import com.google.storage.control.v2.StorageControlClient;
+import java.io.IOException;
+
+public final class GetFolder {
+
+  public static void getFolder(String bucketName, String folderName) throws IOException {
+    // The name of the bucket
+    // String bucketName = "your-unique-bucket-name";
+
+    // The name of the folder within the bucket
+    // String folderName = "your-unique-folder-name";
+
+    try (StorageControlClient storageControl = StorageControlClient.create()) {
+
+      GetFolderRequest request =
+          GetFolderRequest.newBuilder()
+              // Set project to "_" to signify globally scoped bucket
+              .setName(FolderName.format("_", bucketName, folderName))
+              .build();
+
+      Folder newFolder = storageControl.getFolder(request);
+
+      System.out.printf("Got folder: %s%n", newFolder.getName());
+    }
+  }
+}
+// [END storage_control_get_folder]

samples/snippets/src/main/java/com/example/storage/control/v2/ListFolders.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.control.v2;
+
+// [START storage_control_list_folders]
+
+import com.google.storage.control.v2.BucketName;
+import com.google.storage.control.v2.Folder;
+import com.google.storage.control.v2.ListFoldersRequest;
+import com.google.storage.control.v2.StorageControlClient;
+import java.io.IOException;
+
+public final class ListFolders {
+
+  public static void listFolders(String bucketName) throws IOException {
+    // The name of the bucket
+    // String bucketName = "your-unique-bucket-name";
+
+    try (StorageControlClient storageControl = StorageControlClient.create()) {
+
+      ListFoldersRequest request =
+          ListFoldersRequest.newBuilder()
+              // Set project to "_" to signify globally scoped bucket
+              .setParent(BucketName.format("_", bucketName))
+              .build();
+
+      Iterable<Folder> folders = storageControl.listFolders(request).iterateAll();
+      for (Folder folder : folders) {
+        System.out.printf("Found folder: %s%n", folder.getName());
+      }
+    }
+  }
+}
+// [END storage_control_list_folders]

samples/snippets/src/main/java/com/example/storage/control/v2/RenameFolder.java

@@ -0,0 +1,66 @@
+/*
+ * 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.control.v2;
+
+// [START storage_control_rename_folder]
+
+import com.google.api.gax.longrunning.OperationFuture;
+import com.google.storage.control.v2.Folder;
+import com.google.storage.control.v2.FolderName;
+import com.google.storage.control.v2.RenameFolderMetadata;
+import com.google.storage.control.v2.RenameFolderRequest;
+import com.google.storage.control.v2.StorageControlClient;
+import java.io.IOException;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
+
+public final class RenameFolder {
+
+  public static void renameFolder(
+      String bucketName, String sourceFolderName, String destinationFolderName)
+      throws IOException, ExecutionException, InterruptedException, TimeoutException {
+    // The name of the bucket
+    // String bucketName = "your-unique-bucket-name";
+
+    // The name of the folder within the bucket
+    // String sourceFolderName = "your-unique-source-folder-name";
+
+    // The new name of the folder within the bucket
+    // String destinationFolderName = "your-unique-destination-folder-name";
+
+    try (StorageControlClient storageControl = StorageControlClient.create()) {
+
+      // Set project to "_" to signify globally scoped bucket
+      String sourceFolderResourceName = FolderName.format("_", bucketName, sourceFolderName);
+      RenameFolderRequest request =
+          RenameFolderRequest.newBuilder()
+              .setName(sourceFolderResourceName)
+              .setDestinationFolderId(destinationFolderName)
+              .build();
+
+      OperationFuture<Folder, RenameFolderMetadata> renameOperation =
+          storageControl.renameFolderAsync(request);
+
+      Folder destinationFolder = renameOperation.get(30, TimeUnit.SECONDS);
+
+      System.out.printf(
+          "Renamed folder from %s to %s%n", sourceFolderResourceName, destinationFolder.getName());
+    }
+  }
+}
+// [END storage_control_rename_folder]