feat(spanner): make ResultSourceInterface public

google/cloud/spanner/connection.cc

@@ -23,8 +23,7 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 
 namespace {
 
-class StatusOnlyResultSetSource
-    : public spanner_internal::ResultSourceInterface {
+class StatusOnlyResultSetSource : public ResultSourceInterface {
  public:
   explicit StatusOnlyResultSetSource(Status status)
       : status_(std::move(status)) {}

google/cloud/spanner/internal/connection_impl.cc

@@ -258,7 +258,7 @@ Status ConnectionImpl::Rollback(RollbackParams params) {
                });
 }
 
-class StatusOnlyResultSetSource : public ResultSourceInterface {
+class StatusOnlyResultSetSource : public spanner::ResultSourceInterface {
  public:
   explicit StatusOnlyResultSetSource(google::cloud::Status status)
       : status_(std::move(status)) {}
@@ -283,11 +283,11 @@ ResultType MakeStatusOnlyResult(Status status) {
       std::make_unique<StatusOnlyResultSetSource>(std::move(status)));
 }
 
-class DmlResultSetSource : public ResultSourceInterface {
+class DmlResultSetSource : public spanner::ResultSourceInterface {
  public:
-  static StatusOr<std::unique_ptr<ResultSourceInterface>> Create(
+  static StatusOr<std::unique_ptr<spanner::ResultSourceInterface>> Create(
       google::spanner::v1::ResultSet result_set) {
-    return std::unique_ptr<ResultSourceInterface>(
+    return std::unique_ptr<spanner::ResultSourceInterface>(
         new DmlResultSetSource(std::move(result_set)));
   }
 
@@ -320,7 +320,7 @@ class StreamingPartitionedDmlResult {
  public:
   StreamingPartitionedDmlResult() = default;
   explicit StreamingPartitionedDmlResult(
-      std::unique_ptr<ResultSourceInterface> source)
+      std::unique_ptr<spanner::ResultSourceInterface> source)
       : source_(std::move(source)) {}
 
   // This class is movable but not copyable.
@@ -345,7 +345,7 @@ class StreamingPartitionedDmlResult {
   }
 
  private:
-  std::unique_ptr<ResultSourceInterface> source_;
+  std::unique_ptr<spanner::ResultSourceInterface> source_;
 };
 
 /**
@@ -583,7 +583,7 @@ StatusOr<ResultType> ConnectionImpl::ExecuteSqlImpl(
     StatusOr<google::spanner::v1::TransactionSelector>& s,
     TransactionContext const& ctx, SqlParams params,
     google::spanner::v1::ExecuteSqlRequest::QueryMode query_mode,
-    std::function<StatusOr<std::unique_ptr<ResultSourceInterface>>(
+    std::function<StatusOr<std::unique_ptr<spanner::ResultSourceInterface>>(
         google::spanner::v1::ExecuteSqlRequest& request)> const&
         retry_resume_fn) {
   if (!s.ok()) {
@@ -677,7 +677,7 @@ ResultType ConnectionImpl::CommonQueryImpl(
       [stub, retry_policy_prototype, backoff_policy_prototype,
        route_to_leader = ctx.route_to_leader, tracing_enabled,
        tracing_options](google::spanner::v1::ExecuteSqlRequest& request) mutable
-      -> StatusOr<std::unique_ptr<ResultSourceInterface>> {
+      -> StatusOr<std::unique_ptr<spanner::ResultSourceInterface>> {
     auto factory = [stub, request, route_to_leader, tracing_enabled,
                     tracing_options](std::string const& resume_token) mutable {
       if (!resume_token.empty()) request.set_resume_token(resume_token);

google/cloud/spanner/internal/connection_impl.h

@@ -139,7 +139,7 @@ class ConnectionImpl : public spanner::Connection {
       StatusOr<google::spanner::v1::TransactionSelector>& s,
       TransactionContext const& ctx, SqlParams params,
       google::spanner::v1::ExecuteSqlRequest::QueryMode query_mode,
-      std::function<StatusOr<std::unique_ptr<ResultSourceInterface>>(
+      std::function<StatusOr<std::unique_ptr<spanner::ResultSourceInterface>>(
           google::spanner::v1::ExecuteSqlRequest& request)> const&
           retry_resume_fn);
 

google/cloud/spanner/internal/partial_result_set_resume_test.cc

@@ -68,8 +68,9 @@ std::unique_ptr<PartialResultSetReader> MakeTestResume(
           .clone());
 }
 
-StatusOr<std::unique_ptr<ResultSourceInterface>> CreatePartialResultSetSource(
-    std::unique_ptr<PartialResultSetReader> reader, Options opts = {}) {
+StatusOr<std::unique_ptr<spanner::ResultSourceInterface>>
+CreatePartialResultSetSource(std::unique_ptr<PartialResultSetReader> reader,
+                             Options opts = {}) {
   internal::OptionsSpan span(
       internal::MergeOptions(std::move(opts), internal::CurrentOptions()));
   return PartialResultSetSource::Create(std::move(reader));

google/cloud/spanner/internal/partial_result_set_source.cc

@@ -55,8 +55,8 @@ void ExtractSubrangeAndAppend(Values& src, int start, Values& dst) {
 
 }  // namespace
 
-StatusOr<std::unique_ptr<ResultSourceInterface>> PartialResultSetSource::Create(
-    std::unique_ptr<PartialResultSetReader> reader) {
+StatusOr<std::unique_ptr<spanner::ResultSourceInterface>>
+PartialResultSetSource::Create(std::unique_ptr<PartialResultSetReader> reader) {
   std::unique_ptr<PartialResultSetSource> source(
       new PartialResultSetSource(std::move(reader)));
 

google/cloud/spanner/internal/partial_result_set_source.h

@@ -42,10 +42,10 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
  * reader and the spanner `ResultSet`, and is used to iterate over the rows
  * returned from a read operation.
  */
-class PartialResultSetSource : public ResultSourceInterface {
+class PartialResultSetSource : public spanner::ResultSourceInterface {
  public:
   /// Factory method to create a PartialResultSetSource.
-  static StatusOr<std::unique_ptr<ResultSourceInterface>> Create(
+  static StatusOr<std::unique_ptr<spanner::ResultSourceInterface>> Create(
       std::unique_ptr<PartialResultSetReader> reader);
 
   ~PartialResultSetSource() override;

google/cloud/spanner/internal/partial_result_set_source_test.cc

@@ -52,8 +52,9 @@ struct StringOption {
 // Create the `PartialResultSetSource` within an `OptionsSpan` that has its
 // `StringOption` set to the current test name, so that we might check that
 // all `PartialResultSetReader` calls happen within a matching span.
-StatusOr<std::unique_ptr<ResultSourceInterface>> CreatePartialResultSetSource(
-    std::unique_ptr<PartialResultSetReader> reader, Options opts = {}) {
+StatusOr<std::unique_ptr<spanner::ResultSourceInterface>>
+CreatePartialResultSetSource(std::unique_ptr<PartialResultSetReader> reader,
+                             Options opts = {}) {
   internal::OptionsSpan span(internal::MergeOptions(
       std::move(opts.set<StringOption>(CurrentTestName())),
       internal::CurrentOptions()));

google/cloud/spanner/mocks/mock_spanner_connection.h

@@ -71,7 +71,7 @@ class MockConnection : public spanner::Connection {
  *
  * @see @ref spanner-mocking for an example using this class.
  */
-class MockResultSetSource : public spanner_internal::ResultSourceInterface {
+class MockResultSetSource : public spanner::ResultSourceInterface {
  public:
   MOCK_METHOD(StatusOr<spanner::Row>, NextRow, (), (override));
   MOCK_METHOD(absl::optional<google::spanner::v1::ResultSetMetadata>, Metadata,

google/cloud/spanner/results.cc

@@ -26,7 +26,7 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 namespace {
 
 absl::optional<Timestamp> GetReadTimestamp(
-    std::unique_ptr<spanner_internal::ResultSourceInterface> const& source) {
+    std::unique_ptr<ResultSourceInterface> const& source) {
   auto metadata = source->Metadata();
   absl::optional<Timestamp> timestamp;
   if (metadata.has_value() && metadata->has_transaction() &&
@@ -38,13 +38,13 @@ absl::optional<Timestamp> GetReadTimestamp(
 }
 
 std::int64_t GetRowsModified(
-    std::unique_ptr<spanner_internal::ResultSourceInterface> const& source) {
+    std::unique_ptr<ResultSourceInterface> const& source) {
   auto stats = source->Stats();
   return stats ? stats->row_count_exact() : 0;
 }
 
 absl::optional<std::unordered_map<std::string, std::string>> GetExecutionStats(
-    std::unique_ptr<spanner_internal::ResultSourceInterface> const& source) {
+    std::unique_ptr<ResultSourceInterface> const& source) {
   auto stats = source->Stats();
   if (stats && stats->has_query_stats()) {
     std::unordered_map<std::string, std::string> execution_stats;

google/cloud/spanner/results.h

@@ -27,24 +27,49 @@
 
 namespace google {
 namespace cloud {
-namespace spanner_internal {
+namespace spanner {
 GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 
+/**
+ * Defines the interface for `RowStream` implementations.
+ *
+ * The `RowStream` class represents a stream of `Rows` returned from
+ * `spanner::Client::Read()` or `spanner::Client::ExecuteQuery()`. There are
+ * different implementations depending the the RPC. Applications can also
+ * mock this class when testing their code and mocking the `spanner::Client`
+ * behavior.
+ */
 class ResultSourceInterface {
  public:
   virtual ~ResultSourceInterface() = default;
-  // Returns OK Status with an empty Row to indicate end-of-stream.
+
+  /**
+   * Returns the next row in the stream.
+   *
+   * @return if the stream is interrupted due to a failure the
+   *   `StatusOr<spanner::Row>` contains the error. If the
+   */
   virtual StatusOr<spanner::Row> NextRow() = 0;
+
+  /**
+   * Returns metadata about the result set, such as the field types and the
+   * transaction id created by the request.
+   *
+   * @see https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.v1#resultsetmetadata
+   *     for more information.
+   */
   virtual absl::optional<google::spanner::v1::ResultSetMetadata> Metadata() = 0;
+
+  /**
+   * Returns statiscs about the result set, such as the number of rows returned,
+   * or the query plan used to compute the results.
+   *
+   * @see https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.v1#resultsetstats
+   *     for more information.
+   */
   virtual absl::optional<google::spanner::v1::ResultSetStats> Stats() const = 0;
 };
 
-GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
-}  // namespace spanner_internal
-
-namespace spanner {
-GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
-
 /**
  * Contains a hierarchical representation of the operations the database server
  * performs in order to execute a particular SQL statement.
@@ -74,8 +99,7 @@ using ExecutionPlan = ::google::spanner::v1::QueryPlan;
 class RowStream {
  public:
   RowStream() = default;
-  explicit RowStream(
-      std::unique_ptr<spanner_internal::ResultSourceInterface> source)
+  explicit RowStream(std::unique_ptr<ResultSourceInterface> source)
       : source_(std::move(source)) {}
 
   // This class is movable but not copyable.
@@ -102,7 +126,7 @@ class RowStream {
   absl::optional<Timestamp> ReadTimestamp() const;
 
  private:
-  std::unique_ptr<spanner_internal::ResultSourceInterface> source_;
+  std::unique_ptr<ResultSourceInterface> source_;
 };
 
 /**
@@ -120,8 +144,7 @@ class RowStream {
 class DmlResult {
  public:
   DmlResult() = default;
-  explicit DmlResult(
-      std::unique_ptr<spanner_internal::ResultSourceInterface> source)
+  explicit DmlResult(std::unique_ptr<ResultSourceInterface> source)
       : source_(std::move(source)) {}
 
   // This class is movable but not copyable.
@@ -137,7 +160,7 @@ class DmlResult {
   std::int64_t RowsModified() const;
 
  private:
-  std::unique_ptr<spanner_internal::ResultSourceInterface> source_;
+  std::unique_ptr<ResultSourceInterface> source_;
 };
 
 /**
@@ -161,8 +184,7 @@ class DmlResult {
 class ProfileQueryResult {
  public:
   ProfileQueryResult() = default;
-  explicit ProfileQueryResult(
-      std::unique_ptr<spanner_internal::ResultSourceInterface> source)
+  explicit ProfileQueryResult(std::unique_ptr<ResultSourceInterface> source)
       : source_(std::move(source)) {}
 
   // This class is movable but not copyable.
@@ -201,7 +223,7 @@ class ProfileQueryResult {
   absl::optional<spanner::ExecutionPlan> ExecutionPlan() const;
 
  private:
-  std::unique_ptr<spanner_internal::ResultSourceInterface> source_;
+  std::unique_ptr<ResultSourceInterface> source_;
 };
 
 /**
@@ -220,8 +242,7 @@ class ProfileQueryResult {
 class ProfileDmlResult {
  public:
   ProfileDmlResult() = default;
-  explicit ProfileDmlResult(
-      std::unique_ptr<spanner_internal::ResultSourceInterface> source)
+  explicit ProfileDmlResult(std::unique_ptr<ResultSourceInterface> source)
       : source_(std::move(source)) {}
 
   // This class is movable but not copyable.
@@ -251,11 +272,21 @@ class ProfileDmlResult {
   absl::optional<spanner::ExecutionPlan> ExecutionPlan() const;
 
  private:
-  std::unique_ptr<spanner_internal::ResultSourceInterface> source_;
+  std::unique_ptr<ResultSourceInterface> source_;
 };
 
 GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
 }  // namespace spanner
+
+namespace spanner_internal {
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
+
+/// @deprecated Prefer using `spanner::ResultSourceInterface` directly.
+using ResultSourceInterface = spanner::ResultSourceInterface;
+
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
+}  // namespace spanner_internal
+
 }  // namespace cloud
 }  // namespace google