Add ContentSuggestionsService

components/ntp_snippets/content_suggestions_provider.h

+// Copyright 2016 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef COMPONENTS_NTP_SNIPPETS_CONTENT_SUGGESTIONS_PROVIDER_H_
+#define COMPONENTS_NTP_SNIPPETS_CONTENT_SUGGESTIONS_PROVIDER_H_
+
+#include <string>
+#include <vector>
+
+#include "base/callback_forward.h"
+#include "components/ntp_snippets/content_suggestion.h"
+#include "components/ntp_snippets/content_suggestions_category.h"
+#include "components/ntp_snippets/content_suggestions_category_status.h"
+
+namespace gfx {
+class Image;
+}
+
+namespace ntp_snippets {
+
+// Provides content suggestions from one particular source.
+// A provider can provide suggestions for multiple ContentSuggestionCategories,
+// but for every category that it provides, it will be the only provider in the
+// system which provides suggestions for that category.
+// A provider can be a keyed service, in which case it should notify the
+// ContentSuggestionsService through the observer before it shuts down.
+class ContentSuggestionsProvider {
+ public:
+  using ImageFetchedCallback =
+      base::Callback<void(const std::string& suggestion_id, const gfx::Image&)>;
+
+  // The observer of a provider is notified when new data is available.
+  class Observer {
+   public:
+    // Called when the available content changed.
+    // If a provider provides suggestions of multiple categories, it must call
+    // this callback for every category individually. The |suggestions|
+    // parameter should always contain the full list of currently available
+    // suggestions of that category, i.e., passing an empty list will remove
+    // all suggestions of the given category for the provider. Note that to
+    // clear them from the UI immediately, the provider needs to change the
+    // status of the respective category.
+    // The list must not contain ContentSuggestions assigned to a category other
+    // than the passed |changed_category|.
+    virtual void OnNewSuggestions(
+        ContentSuggestionsCategory changed_category,
+        std::vector<ContentSuggestion> suggestions) = 0;

[tschumann, 2016/07/06 06:36:12]

const vector<>& ?

[Marc Treib, 2016/07/06 08:20:44]

This is on purpose, to avoid a copy - it'll be moved in. No risk of copying
accidentally since ContentSuggestion isn't copyable.
Doesn't really matter too much though.

[tschumann, 2016/07/06 14:49:44]

given it's an interface, I have a slight tendency towards const & as it imposes
less restrictions on the implementations. But not feeling terribly strongly.

[Philipp Keck, 2016/07/06 15:53:20]

const-ref wouldn't work because ContentSuggestion is not copyable. The service
is the only implementation of this interface and it is a reasonable assumption
that it will stay the only implementation (we also only allow one observer, not
multiple ones).

+
+    // Called when the status of a category changed.
+    // Whenever the status changes to an unavailable status, all suggestions in
+    // that category must immediately be removed from all caches and from the
+    // UI.
+    virtual void OnCategoryStatusChanged(
+        ContentSuggestionsCategory changed_category,
+        ContentSuggestionsCategoryStatus new_status) = 0;
+
+    // Called when the provider needs to shut down and will not deliver any
+    // suggestions anymore. This unregisters the provider, removes the observer
+    // and deactivates all provided categories.
+    virtual void OnProviderShutdown(ContentSuggestionsProvider* provider) = 0;
+  };
+
+  // Sets an observer which is notified about changes to the available
+  // suggestions, or removes it by passing a nullptr.
+  virtual void SetObserver(Observer* observer) = 0;
+
+  // Determines the status of the given |category|, see
+  // ContentSuggestionsCategoryStatus.
+  virtual ContentSuggestionsCategoryStatus GetCategoryStatus(
+      ContentSuggestionsCategory category) = 0;
+
+  // Discards the suggestion with the given ID. A provider needs to ensure that
+  // a once-discarded suggestion is never delivered again (through the
+  // Observer). The provider must not call Observer::OnSuggestionsChanged if the
+  // removal of the discarded suggestion is the only change.
+  // Note that the |suggestion_id| to the provider here is the same as the
+  // |original_id| that was passed to the |ContentSuggestion| constructor.
+  virtual void DiscardSuggestion(const std::string& suggestion_id) = 0;
+
+  // Fetches the image for the suggestion with the given ID and returns it
+  // through the callback. This fetch may occur locally or from the internet.
+  // Note that the |suggestion_id| to the provider here is the same as the
+  // |original_id| that was passed to the |ContentSuggestion| constructor.
+  virtual void FetchSuggestionImage(const std::string& suggestion_id,
+                                    const ImageFetchedCallback& callback) = 0;
+
+  // Used only for debugging purposes. Clears all caches so that the next
+  // fetch starts from scratch.
+  virtual void ClearCachedSuggestionsForDebugging() = 0;
+
+  // Used only for debugging purposes. Clears the cache of discarded
+  // suggestions, if present, so that no suggestions are suppressed. This does
+  // not necessarily make previously discarded suggestions reappear, as they may
+  // have been permanently deleted, depending on the provider implementation.
+  virtual void ClearDiscardedSuggestionsForDebugging() = 0;
+
+  // Creates a unique ID. The given |within_category_id| must be unique among
+  // all suggestion IDs from this provider for the given |category|. This method
+  // combines it with the |category| to form an ID that is unique
+  // application-wide, because this provider is the only one that provides
+  // suggestions for that category.
+  static std::string MakeUniqueID(ContentSuggestionsCategory category,

[tschumann, 2016/07/06 06:36:12]

should this be protected?

[Philipp Keck, 2016/07/06 08:34:23]

No, NTPSnippet also calls it. If the NTPSnippet class can't call it directly, it
needs an ID parameter on its NTPSnippet::ToContentSuggestion(std::string id)
that would be filled in by the calling NTPSnippetsService, which in turn gets it
from the ContentSuggestionsProvider::MakeUniqueID here. So ToContentSuggestion()
would need a parameter, though ToXxx methods usually don't have parameters
(except to further specify the format of the output).

[tschumann, 2016/07/06 14:49:44]

As discussed offline, give that the provider is calling
NTPSnippet::ToContentSuggestion(), we can either move that conversion into the
provider or just pass in the ID.

[Philipp Keck, 2016/07/06 15:53:20]

This method is now protected. It will be used by providers internally (and they
can decide to pass it along to any helper methods they might need). The current
use in NTPSnippet::ToContentSuggestion and in fact the entire
ToContentSuggestion method have been removed. The new use will be in the
conversion method in the NTPSnippetsService (aka ArticleSuggestionsProvider),
which currently calls ToContentSuggestion. The changes to NTPSnippetsService are
not part of this CL, so it will reappear later.

+                                  const std::string& within_category_id);
+
+  const std::vector<ContentSuggestionsCategory> provided_categories() const {
+    return provided_categories_;
+  }
+
+ protected:
+  ContentSuggestionsProvider(
+      const std::vector<ContentSuggestionsCategory>& provided_categories);
+  virtual ~ContentSuggestionsProvider();
+
+ private:
+  const std::vector<ContentSuggestionsCategory> provided_categories_;
+};
+
+}  // namespace ntp_snippets
+
+#endif  // COMPONENTS_NTP_SNIPPETS_CONTENT_SUGGESTIONS_PROVIDER_H_