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

Author: BenWhitehead

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]