[TTS] Add a Java Context linked to existing native

chrome/android/java/src/org/chromium/chrome/browser/contextualsearch/ContextualSearchContext.java

+// Copyright 2017 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.contextualsearch;
+
+import org.chromium.base.annotations.CalledByNative;
+
+/**
+ * Provides a context in which to search, and links to the native ContextualSearchContext.
+ * Includes the selection, selection offsets, surrounding page content, etc.
+ */
+public class ContextualSearchContext {
+    private long mNativePointer;
+
+    private final String mSelection;

[Theresa, 2017/03/08 01:54:38]

nit: final variables go first.

[Donn Denman, 2017/03/09 17:35:04]

Done.

+
+    // Whether the context should include brief page content or a larger amount as would be
+    // appropriate when resolving the search term.
+    private boolean mUseBriefPageContent;
+
+    /**
+     * Constructs a context that cannot resolve a search term and has a small amount of
+     * page content.
+     */
+    ContextualSearchContext(String selection) {
+        mNativePointer = nativeInit();
+        mUseBriefPageContent = true;
+        mSelection = selection;
+        nativeSetUseBriefPageContent(getNativePointer(), true);
+    }
+
+    /**
+     * Constructs a context that can resolve a search term and has a large amount of
+     * page content.
+     */
+    ContextualSearchContext(String selection, String homeCountry, boolean maySendBasePageUrl) {

[Theresa, 2017/03/08 01:54:38]

nit: JavaDocs for parameters

[Donn Denman, 2017/03/09 17:35:04]

Done.

+        mNativePointer = nativeInit();
+        mUseBriefPageContent = false;
+        mSelection = selection;
+        nativeSetUseBriefPageContent(getNativePointer(), false);
+        nativeSetProperties(getNativePointer(), selection, homeCountry, maySendBasePageUrl);
+    }
+
+    /**
+     * This method should be called to clean up storage when an instance of this class is
+     * no longer in use.
+     */
+    void destroy() {
+        assert mNativePointer != 0;
+        nativeDestroy(mNativePointer);
+        mNativePointer = 0;
+    }
+
+    String getSelection() {
+        return mSelection;
+    }
+
+    // ============================================================================================
+    // Native callback support.
+    // ============================================================================================
+
+    @CalledByNative
+    private void clearNativePointer() {

[Theresa, 2017/03/08 01:54:38]

When is this called vs destroy()?

[Donn Denman, 2017/03/09 17:35:04]

Added JavaDoc.

Destroy is called from the java, but clearNativePointer is called by the native
destructor so this class will let go of the pointer to the native instance.

[Theresa, 2017/03/09 18:29:44]

What I was trying to ask is when is the object destroyed by Java and when is it
destroyed by native? Typically we only have one or the other and both methods
release the pointer to the native instance.

[Donn Denman, 2017/03/09 22:00:25]

BTW, here's that sample code I was telling you about:
Documentation and quick reference are found in sample_for_tests.h &
SampleForTests.java.

I see.  Since we want to destroy in Java I can get rid of this
clearNativePointer and just have destroy clear it.  Thanks!

+        assert mNativePointer != 0;
+        mNativePointer = 0;
+    }
+
+    @CalledByNative
+    private long getNativePointer() {
+        assert mNativePointer != 0;
+        return mNativePointer;
+    }
+
+    // ============================================================================================
+    // Native methods.
+    // ============================================================================================
+    private native long nativeInit();
+    private native void nativeDestroy(long nativeContextualSearchContext);
+    private native void nativeSetUseBriefPageContent(
+            long nativeContextualSearchContext, boolean useBriefPageContent);
+    private native void nativeSetProperties(long nativeContextualSearchContext, String selection,
+            String homeCountry, boolean maySendBasePageUrl);
+}