refactor: Address review comments for Storage List API

Incorporates feedback from the initial review of the List API:

- Build Fix:
    - Explicitly namespaced StorageReference in list_result.h to resolve undeclared identifier error.
- Integration Tests:
    - Removed SKIP_TEST_ON_ANDROID_EMULATOR from ListAllBasic and ListPaginated tests.
    - Refactored list tests to create their own unique root folders instead of using a shared one in the test fixture, improving test isolation.
- Code Style:
    - Removed unnecessary comments explaining header includes.
    - Removed placeholder comments from public headers.
    - Updated copyright year to 2025 in all newly added files.
    - Ran code formatter (scripts/format_code.py -git_diff) on all changed files.
- Android Performance:
    - Optimized Android's ListResultInternal to cache converted items, prefixes, and page token. This avoids repeated JNI calls on subsequent accesses.
- Cleanup Mechanism:
    - Simplified ListResult cleanup by removing the ListResultInternalCommon class. ListResult now directly manages the cleanup registration of its internal_ member, similar to StorageReference.

Author: google-labs-jules[bot]

storage/integration_test/src/integration_test.cc

@@ -31,8 +31,7 @@ namespace internal {
   X(GetPageToken, "getPageToken", "()Ljava/lang/String;")
 // clang-format on
 METHOD_LOOKUP_DECLARATION(list_result, LIST_RESULT_METHODS)
-METHOD_LOOKUP_DEFINITION(list_result,
-                         "com/google/firebase/storage/ListResult",
+METHOD_LOOKUP_DEFINITION(list_result, "com/google/firebase/storage/ListResult",
                          LIST_RESULT_METHODS)
 
 // clang-format off
@@ -78,9 +77,9 @@ ListResultInternal::ListResultInternal(StorageInternal* storage_internal,
 ListResultInternal::ListResultInternal(const ListResultInternal& other)
     : storage_internal_(other.storage_internal_),
       list_result_java_ref_(nullptr),
-      items_cache_(other.items_cache_),       // Copy cache
-      prefixes_cache_(other.prefixes_cache_), // Copy cache
-      page_token_cache_(other.page_token_cache_), // Copy cache
+      items_cache_(other.items_cache_),            // Copy cache
+      prefixes_cache_(other.prefixes_cache_),      // Copy cache
+      page_token_cache_(other.page_token_cache_),  // Copy cache
       items_converted_(other.items_converted_),
       prefixes_converted_(other.prefixes_converted_),
       page_token_converted_(other.page_token_converted_) {
@@ -96,7 +95,8 @@ ListResultInternal& ListResultInternal::operator=(
   if (&other == this) {
     return *this;
   }
-  storage_internal_ = other.storage_internal_;  // This is a raw pointer, just copy.
+  storage_internal_ =
+      other.storage_internal_;  // This is a raw pointer, just copy.
   FIREBASE_ASSERT(storage_internal_ != nullptr);
   JNIEnv* env = storage_internal_->app()->GetJNIEnv();
   if (list_result_java_ref_ != nullptr) {
@@ -132,24 +132,28 @@ std::vector<StorageReference> ListResultInternal::ProcessJavaReferenceList(
   }
 
   JNIEnv* env = storage_internal_->app()->GetJNIEnv();
-  jint size = env->CallIntMethod(java_list_ref, java_list::GetMethodId(java_list::kSize));
+  jint size = env->CallIntMethod(java_list_ref,
+                                 java_list::GetMethodId(java_list::kSize));
   if (env->ExceptionCheck()) {
     env->ExceptionClear();
     LogError("Failed to get size of Java List in ListResultInternal");
     return cpp_references;
   }
 
   for (jint i = 0; i < size; ++i) {
-    jobject java_storage_ref =
-        env->CallObjectMethod(java_list_ref, java_list::GetMethodId(java_list::kGet), i);
+    jobject java_storage_ref = env->CallObjectMethod(
+        java_list_ref, java_list::GetMethodId(java_list::kGet), i);
     if (env->ExceptionCheck() || java_storage_ref == nullptr) {
       env->ExceptionClear();
-      LogError("Failed to get StorageReference object from Java List at index %d", i);
+      LogError(
+          "Failed to get StorageReference object from Java List at index %d",
+          i);
       if (java_storage_ref) env->DeleteLocalRef(java_storage_ref);
       continue;
     }
     // Create a C++ StorageReferenceInternal from the Java StorageReference.
-    // StorageReferenceInternal constructor will create a global ref for the java obj.
+    // StorageReferenceInternal constructor will create a global ref for the
+    // java obj.
     StorageReferenceInternal* sfr_internal =
         new StorageReferenceInternal(storage_internal_, java_storage_ref);
     cpp_references.push_back(StorageReference(sfr_internal));
@@ -159,7 +163,7 @@ std::vector<StorageReference> ListResultInternal::ProcessJavaReferenceList(
 }
 
 std::vector<StorageReference> ListResultInternal::items() const {
-  if (!list_result_java_ref_) return items_cache_; // Return empty if no ref
+  if (!list_result_java_ref_) return items_cache_;  // Return empty if no ref
   if (items_converted_) {
     return items_cache_;
   }
@@ -191,7 +195,8 @@ std::vector<StorageReference> ListResultInternal::prefixes() const {
 
   JNIEnv* env = storage_internal_->app()->GetJNIEnv();
   jobject java_prefixes_list = env->CallObjectMethod(
-      list_result_java_ref_, list_result::GetMethodId(list_result::kGetPrefixes));
+      list_result_java_ref_,
+      list_result::GetMethodId(list_result::kGetPrefixes));
   if (env->ExceptionCheck() || java_prefixes_list == nullptr) {
     env->ExceptionClear();
     LogError("Failed to call getPrefixes() on Java ListResult");
@@ -214,20 +219,21 @@ std::string ListResultInternal::page_token() const {
 
   JNIEnv* env = storage_internal_->app()->GetJNIEnv();
   jstring page_token_jstring = static_cast<jstring>(env->CallObjectMethod(
-      list_result_java_ref_, list_result::GetMethodId(list_result::kGetPageToken)));
+      list_result_java_ref_,
+      list_result::GetMethodId(list_result::kGetPageToken)));
   if (env->ExceptionCheck()) {
     env->ExceptionClear();
     LogError("Failed to call getPageToken() on Java ListResult");
     if (page_token_jstring) env->DeleteLocalRef(page_token_jstring);
     page_token_converted_ = true;
-    return page_token_cache_; // Return empty if error
+    return page_token_cache_;  // Return empty if error
   }
 
   if (page_token_jstring != nullptr) {
     page_token_cache_ = util::JniStringToString(env, page_token_jstring);
     env->DeleteLocalRef(page_token_jstring);
   } else {
-    page_token_cache_ = ""; // Explicitly set to empty if Java string is null
+    page_token_cache_ = "";  // Explicitly set to empty if Java string is null
   }
 
   page_token_converted_ = true;

storage/src/android/list_result_android.cc

@@ -24,10 +24,10 @@
 #include "firebase/app.h"
 #include "firebase/storage/storage_reference.h"
 #include "storage/src/common/storage_internal.h"
-// It's okay for platform specific internal headers to include common internal headers.
+// It's okay for platform specific internal headers to include common internal
+// headers.
 #include "storage/src/common/list_result_internal_common.h"
 
-
 namespace firebase {
 namespace storage {
 
@@ -36,7 +36,8 @@ class ListResult;
 
 namespace internal {
 
-// Declare ListResultInternal a friend of ListResultInternalCommon for construction.
+// Declare ListResultInternal a friend of ListResultInternalCommon for
+// construction.
 class ListResultInternalCommon;
 
 // Contains the Android-specific implementation of ListResultInternal.

storage/src/android/list_result_android.h

@@ -111,7 +111,7 @@ enum StorageReferenceFn {
   kStorageReferenceFnUpdateMetadata,
   kStorageReferenceFnPutBytes,
   kStorageReferenceFnPutFile,
-  kStorageReferenceFnList, // New enum value for List operations
+  kStorageReferenceFnList,  // New enum value for List operations
   kStorageReferenceFnCount,
 };
 
@@ -122,7 +122,7 @@ bool StorageReferenceInternal::Initialize(App* app) {
     return false;
   }
   if (!ListResultInternal::Initialize(app)) {
-    storage_reference::ReleaseClass(env); // Release what was cached
+    storage_reference::ReleaseClass(env);  // Release what was cached
     return false;
   }
   return true;
@@ -331,7 +331,7 @@ void StorageReferenceInternal::FutureCallback(JNIEnv* env, jobject result,
     jobject result_ref = env->NewLocalRef(result);
     ListResultInternal* list_result_internal_ptr =
         new ListResultInternal(data->storage, result_ref);
-    env->DeleteLocalRef(result_ref); // ListResultInternal made a global ref.
+    env->DeleteLocalRef(result_ref);  // ListResultInternal made a global ref.
 
     data->impl->Complete<ListResult>(
         data->handle, kErrorNone, status_message,
@@ -345,11 +345,15 @@ void StorageReferenceInternal::FutureCallback(JNIEnv* env, jobject result,
     // This case might need adjustment if List operations that fail end up here
     // without a specific exception being caught by result_code check.
     if (data->func == kStorageReferenceFnList) {
-         // If it was a list operation but didn't result in a ListResult object (e.g. error not caught as exception)
-         // complete with an error and an invalid ListResult.
-        data->impl->CompleteWithResult(data->handle, kErrorUnknown, "List operation failed to produce a valid ListResult.", ListResult(nullptr));
+      // If it was a list operation but didn't result in a ListResult object
+      // (e.g. error not caught as exception) complete with an error and an
+      // invalid ListResult.
+      data->impl->CompleteWithResult(
+          data->handle, kErrorUnknown,
+          "List operation failed to produce a valid ListResult.",
+          ListResult(nullptr));
     } else {
-        data->impl->Complete(data->handle, kErrorNone, status_message);
+      data->impl->Complete(data->handle, kErrorNone, status_message);
     }
   }
   if (data->listener != nullptr) {

storage/src/android/storage_reference_android.cc

@@ -17,12 +17,11 @@
 #include <assert.h>
 
 // #include "storage/src/common/list_result_internal_common.h" // Removed
-#include "storage/src/common/storage_internal.h" // Required for StorageInternal, CleanupNotifier
-#include "storage/src/common/storage_reference_internal.h" // For StorageReference constructor from internal
-#include "app/src/include/firebase/app.h" // For App, LogDebug
-#include "app/src/util.h" // For LogDebug
-#include "app/src/cleanup_notifier.h" // For CleanupNotifier
-
+#include "app/src/cleanup_notifier.h"      // For CleanupNotifier
+#include "app/src/include/firebase/app.h"  // For App, LogDebug
+#include "app/src/util.h"                  // For LogDebug
+#include "storage/src/common/storage_internal.h"  // Required for StorageInternal, CleanupNotifier
+#include "storage/src/common/storage_reference_internal.h"  // For StorageReference constructor from internal
 
 // Platform specific ListResultInternal definitions
 #if FIREBASE_PLATFORM_ANDROID
@@ -31,7 +30,8 @@
 #include "storage/src/ios/list_result_ios.h"
 #elif FIREBASE_PLATFORM_DESKTOP
 #include "storage/src/desktop/list_result_desktop.h"
-#endif  // FIREBASE_PLATFORM_ANDROID, FIREBASE_PLATFORM_IOS, FIREBASE_PLATFORM_DESKTOP
+#endif  // FIREBASE_PLATFORM_ANDROID, FIREBASE_PLATFORM_IOS,
+        // FIREBASE_PLATFORM_DESKTOP
 
 namespace firebase {
 namespace storage {
@@ -40,8 +40,8 @@ using internal::ListResultInternal;
 // using internal::ListResultInternalCommon; // Removed
 
 // Global function to be called by CleanupNotifier
-// This function is responsible for cleaning up the internal state of a ListResult
-// object when the App is being shut down.
+// This function is responsible for cleaning up the internal state of a
+// ListResult object when the App is being shut down.
 static void GlobalCleanupListResult(void* list_result_void) {
   if (list_result_void) {
     ListResult* list_result = static_cast<ListResult*>(list_result_void);
@@ -167,8 +167,9 @@ ListResult::~ListResult() {
 
 void ListResult::ClearInternalForCleanup() {
   // This method is called by GlobalCleanupListResult.
-  // The object is already unregistered from the CleanupNotifier by the notifier itself
-  // before this callback is invoked. So, no need to call UnregisterObject here.
+  // The object is already unregistered from the CleanupNotifier by the notifier
+  // itself before this callback is invoked. So, no need to call
+  // UnregisterObject here.
   delete internal_;
   internal_ = nullptr;
 }

storage/src/common/list_result.cc

@@ -15,8 +15,8 @@
 #include "storage/src/include/firebase/storage/storage_reference.h"
 
 #include "app/src/assert.h"
-#include "firebase/storage/list_result.h" // Required for ListResult
-#include "storage/src/include/firebase/storage/future_details.h" // Required for Future<ListResult>
+#include "firebase/storage/list_result.h"  // Required for ListResult
+#include "storage/src/include/firebase/storage/future_details.h"  // Required for Future<ListResult>
 
 #ifdef __APPLE__
 #include "TargetConditionals.h"

storage/src/common/storage_reference.cc

@@ -13,7 +13,8 @@
 // limitations under the License.
 
 #include "storage/src/desktop/list_result_desktop.h"
-#include "storage/src/desktop/storage_desktop.h" // For StorageInternal
+
+#include "storage/src/desktop/storage_desktop.h"  // For StorageInternal
 
 namespace firebase {
 namespace storage {
@@ -28,10 +29,9 @@ ListResultInternal::ListResultInternal(
     const std::vector<StorageReference>& prefixes,
     const std::string& page_token)
     : storage_internal_(storage_internal),
-      items_stub_(items),       // Will be empty for stubs
-      prefixes_stub_(prefixes), // Will be empty for stubs
-      page_token_stub_(page_token) {} // Will be empty for stubs
-
+      items_stub_(items),              // Will be empty for stubs
+      prefixes_stub_(prefixes),        // Will be empty for stubs
+      page_token_stub_(page_token) {}  // Will be empty for stubs
 
 ListResultInternal::ListResultInternal(const ListResultInternal& other)
     : storage_internal_(other.storage_internal_),
@@ -44,7 +44,7 @@ ListResultInternal& ListResultInternal::operator=(
   if (&other == this) {
     return *this;
   }
-  storage_internal_ = other.storage_internal_; // Pointer copy
+  storage_internal_ = other.storage_internal_;  // Pointer copy
   items_stub_ = other.items_stub_;
   prefixes_stub_ = other.prefixes_stub_;
   page_token_stub_ = other.page_token_stub_;

storage/src/desktop/list_result_desktop.cc

@@ -20,10 +20,10 @@
 
 #include "firebase/storage/storage_reference.h"
 #include "storage/src/common/storage_internal.h"
-// It's okay for platform specific internal headers to include common internal headers.
+// It's okay for platform specific internal headers to include common internal
+// headers.
 #include "storage/src/common/list_result_internal_common.h"
 
-
 namespace firebase {
 namespace storage {
 
@@ -32,7 +32,8 @@ class ListResult;
 
 namespace internal {
 
-// Declare ListResultInternal a friend of ListResultInternalCommon for construction.
+// Declare ListResultInternal a friend of ListResultInternalCommon for
+// construction.
 class ListResultInternalCommon;
 
 // Contains the Desktop-specific implementation of ListResultInternal (stubs).
@@ -47,7 +48,6 @@ class ListResultInternal {
                      const std::vector<StorageReference>& prefixes,
                      const std::string& page_token);
 
-
   // Destructor (default is fine).
   ~ListResultInternal() = default;
 
@@ -57,7 +57,6 @@ class ListResultInternal {
   // Copy assignment operator.
   ListResultInternal& operator=(const ListResultInternal& other);
 
-
   // Gets the items (files) in this result (stub).
   std::vector<StorageReference> items() const {
     return std::vector<StorageReference>();
@@ -80,7 +79,7 @@ class ListResultInternal {
   // storage_internal().
   friend class ListResultInternalCommon;
 
-  StorageInternal* storage_internal_; // Not owned.
+  StorageInternal* storage_internal_;  // Not owned.
   // Desktop stubs don't actually store these, but defined to match constructor.
   std::vector<StorageReference> items_stub_;
   std::vector<StorageReference> prefixes_stub_;

storage/src/desktop/list_result_desktop.h

@@ -28,14 +28,14 @@
 #include "app/src/function_registry.h"
 #include "app/src/include/firebase/app.h"
 #include "app/src/thread.h"
+#include "firebase/storage/list_result.h"  // Added for ListResult
 #include "storage/src/common/common_internal.h"
 #include "storage/src/desktop/controller_desktop.h"
+#include "storage/src/desktop/list_result_desktop.h"  // Added for ListResultInternal
 #include "storage/src/desktop/metadata_desktop.h"
 #include "storage/src/desktop/storage_desktop.h"
 #include "storage/src/include/firebase/storage.h"
 #include "storage/src/include/firebase/storage/common.h"
-#include "firebase/storage/list_result.h" // Added for ListResult
-#include "storage/src/desktop/list_result_desktop.h" // Added for ListResultInternal
 
 namespace firebase {
 namespace storage {
@@ -704,9 +704,9 @@ Future<ListResult> StorageReferenceInternal::List(int32_t max_results) {
   ReferenceCountedFutureImpl* future_api = future();
   SafeFutureHandle<ListResult> handle =
       future_api->SafeAlloc<ListResult>(kStorageReferenceFnList);
-  future_api->CompleteWithResult(
-      handle, kErrorUnimplemented,
-      "List operation is not supported on desktop.", ListResult(nullptr));
+  future_api->CompleteWithResult(handle, kErrorUnimplemented,
+                                 "List operation is not supported on desktop.",
+                                 ListResult(nullptr));
   return ListLastResult();
 }
 
@@ -715,9 +715,9 @@ Future<ListResult> StorageReferenceInternal::List(int32_t max_results,
   ReferenceCountedFutureImpl* future_api = future();
   SafeFutureHandle<ListResult> handle =
       future_api->SafeAlloc<ListResult>(kStorageReferenceFnList);
-  future_api->CompleteWithResult(
-      handle, kErrorUnimplemented,
-      "List operation is not supported on desktop.", ListResult(nullptr));
+  future_api->CompleteWithResult(handle, kErrorUnimplemented,
+                                 "List operation is not supported on desktop.",
+                                 ListResult(nullptr));
   return ListLastResult();
 }
 

storage/src/desktop/storage_reference_desktop.cc

@@ -146,11 +146,13 @@ class StorageReferenceInternal {
   // Returns the result of the most recent call to Write();
   Future<Metadata> PutFileLastResult();
 
-  // Asynchronously lists objects and common prefixes under this reference (stub).
+  // Asynchronously lists objects and common prefixes under this reference
+  // (stub).
   Future<ListResult> List(int32_t max_results);
   Future<ListResult> List(int32_t max_results, const char* page_token);
 
-  // Asynchronously lists all objects and common prefixes under this reference (stub).
+  // Asynchronously lists all objects and common prefixes under this reference
+  // (stub).
   Future<ListResult> ListAll();
 
   // Returns the result of the most recent List operation (stub).

storage/src/desktop/storage_reference_desktop.h

@@ -58,10 +58,10 @@ class ListResult {
   ~ListResult();
 
   /// @brief Returns the items (files) in this result.
-  std::vector<StorageReference> items() const;
+  std::vector<firebase::storage::StorageReference> items() const;
 
   /// @brief Returns the prefixes (folders) in this result.
-  std::vector<StorageReference> prefixes() const;
+  std::vector<firebase::storage::StorageReference> prefixes() const;
 
   /// @brief If set, there are more results to retrieve.
   ///