Refactor and extend SnippetsBridge for multi-section support

chrome/android/java/src/org/chromium/chrome/browser/ntp/snippets/ContentSuggestionsSource.java

Index: chrome/android/java/src/org/chromium/chrome/browser/ntp/snippets/ContentSuggestionsSource.java
diff --git a/chrome/android/java/src/org/chromium/chrome/browser/ntp/snippets/ContentSuggestionsSource.java b/chrome/android/java/src/org/chromium/chrome/browser/ntp/snippets/ContentSuggestionsSource.java
new file mode 100644
index 0000000000000000000000000000000000000000..3ef24abb6a2fa8e212e5af47c7700b5ec4635770
--- /dev/null
+++ b/chrome/android/java/src/org/chromium/chrome/browser/ntp/snippets/ContentSuggestionsSource.java
@@ -0,0 +1,74 @@
+// 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.
+
+package org.chromium.chrome.browser.ntp.snippets;
+
+import android.graphics.Bitmap;
+
+import org.chromium.base.Callback;
+import org.chromium.chrome.browser.ntp.cards.SuggestionsCategoryInfo;
+import org.chromium.chrome.browser.ntp.snippets.CategoryStatus.CategoryStatusEnum;
+import org.chromium.chrome.browser.ntp.snippets.KnownCategories.KnownCategoriesEnum;
+
+import java.util.List;
+
+/**
+ * An interface for classes that provide content suggestions.
+ */
+public interface ContentSuggestionsSource {

[Michael van Ouwerkerk, 2016/08/09 13:52:20]

Could this be shortened to SuggestionsSource? Other classes like
SuggestionsCategoryInfo and SuggestionsSection also omit the Content prefix.

[Philipp Keck, 2016/08/09 16:15:07]

Done.

+    /**
+     * An observer for events in the content suggestions service.
+     */
+    interface ContentSuggestionsSourceObserver {

[Bernhard Bauer, 2016/08/09 13:10:41]

Do we need to repeat the class name in this interface? If we just call it
Observer, we can still refer to it as ContentSuggestionsSource.Observer to get
the same information, but we can also shorten it.

[Philipp Keck, 2016/08/09 14:02:53]

Done.

+        /** Called when a category has a new list of content suggestions. */
+        void onNewSuggestions(@KnownCategoriesEnum int category);

[Michael van Ouwerkerk, 2016/08/09 13:52:20]

Is it always a known category? Then use the annotation in the adapter, otherwise
remove it here.

[Bernhard Bauer, 2016/08/09 14:30:11]

This was a leftover from my CL. There could be server-defined categories (which
are not known at compile time), but I liked having an annotation. Really, we
could make an (otherwise empty) @Category annotation that would just serve as
documentation.

[Philipp Keck, 2016/08/09 16:15:07]

Done. Good catch.

[Philipp Keck, 2016/08/09 16:59:16]

You guys can add such a @Category annotation. The @KnownCategoriesEnum needs to
go from here, we want to support dynamic sections in M54 and the corresponding
server-provider will land soon.

[Bernhard Bauer, 2016/08/10 09:01:52]

Keep in mind that these annotations are only used in linting, i.e. nothing will
break at runtime if we have a value that is not a known category.

[Philipp Keck, 2016/08/10 09:05:09]

Ok. Didn't know that. Would it break though if we had unit tests that test want
to test for dynamic categories? Or does the linter ignore the test files?
Still, I think that "known category" would be the wrong documentation signal to
the reader, because it's actually "any category", whether it's known or not.

[Bernhard Bauer, 2016/08/10 09:39:11]

Well, you might get a lint warning, and that would be about it... :)
Oh yes, I just haven't gotten around to making that change :)

[Philipp Keck, 2016/08/10 09:56:40]

Ok. I will leave this as is, if that's okay.

+
+        /** Called when a category changed its status. */
+        void onCategoryStatusChanged(
+                @KnownCategoriesEnum int category, @CategoryStatusEnum int newStatus);

[Michael van Ouwerkerk, 2016/08/09 13:52:20]

Same thing for this category, is it a known one?

[Philipp Keck, 2016/08/09 16:15:07]

Done.

+    }
+
+    /**
+     * Gets the categories in the order in which they should be displayed.
+     * @return The categories.
+     */
+    int[] getCategories();
+
+    /**
+     * Gets the status of a category, possibly indicating the reason why it is disabled.
+     */
+    @CategoryStatusEnum
+    int getCategoryStatus(int category);
+
+    /**
+     * Gets the meta information of a category.
+     */
+    SuggestionsCategoryInfo getCategoryInfo(int category);
+
+    /**
+     * Gets the current content suggestions for a category, in the order in which they should be
+     * displayed.
+     */
+    List<SnippetArticleListItem> getSuggestionsForCategory(int category);
+
+    /**
+     * Fetches the thumbnail image for a content suggestion.
+     */
+    void fetchSuggestionImage(SnippetArticleListItem suggestion, Callback<Bitmap> callback);

[Michael van Ouwerkerk, 2016/08/09 13:52:20]

Is the callback guaranteed to never be called synchronously? Please document
that.

[Philipp Keck, 2016/08/09 16:15:07]

Done.

+
+    /**
+     * Tells the source to dismiss the content suggestion.
+     */
+    void dismissSuggestion(SnippetArticleListItem suggestion);
+
+    /**
+     * Checks whether a content suggestion has been visited.
+     */
+    void getSuggestionVisited(SnippetArticleListItem suggestion, Callback<Boolean> callback);

[Michael van Ouwerkerk, 2016/08/09 13:52:20]

Is the callback guaranteed to never be called synchronously? Please document
that.

[Philipp Keck, 2016/08/09 16:15:07]

Done.

+
+    /**
+     * Sets the recipient for update events from the source.
+     */
+    void setObserver(ContentSuggestionsSourceObserver observer);
+}