From 61abe8ab63427842182609a42c1df0dbc5dda917 Mon Sep 17 00:00:00 2001
From: Henry Fang <quxiangfang@google.com>
Date: Mon, 16 Mar 2020 15:05:14 -0700
Subject: [PATCH] Add java doc to explain the return for insufficient resource.

bug: 151466005
Test: Manual
Change-Id: I21eede6838d70e5dbf0dde9c4ad28059364e107d
---
 media/java/android/media/MediaCas.java       | 19 ++++++++++++++-----
 media/java/android/media/tv/tuner/Tuner.java |  4 ++++
 2 files changed, 18 insertions(+), 5 deletions(-)

diff --git a/media/java/android/media/MediaCas.java b/media/java/android/media/MediaCas.java
index 3a771bba03b9d..ad9486cc6597f 100644
--- a/media/java/android/media/MediaCas.java
+++ b/media/java/android/media/MediaCas.java
@@ -870,16 +870,17 @@ public final class MediaCas implements AutoCloseable {
     private int getSessionResourceId() throws MediaCasException {
         validateInternalStates();
 
-        int[] sessionResourceId = new int[1];
-        sessionResourceId[0] = -1;
+        int[] sessionResourceHandle = new int[1];
+        sessionResourceHandle[0] = -1;
         if (mTunerResourceManager != null) {
             CasSessionRequest casSessionRequest = new CasSessionRequest(mClientId, mCasSystemId);
-            if (!mTunerResourceManager.requestCasSession(casSessionRequest, sessionResourceId)) {
-                throw new MediaCasException.ResourceBusyException(
+            if (!mTunerResourceManager
+                    .requestCasSession(casSessionRequest, sessionResourceHandle)) {
+                throw new MediaCasException.InsufficientResourceException(
                     "insufficient resource to Open Session");
             }
         }
-        return  sessionResourceId[0];
+        return  sessionResourceHandle[0];
     }
 
     private void addSessionToResourceMap(Session session, int sessionResourceId) {
@@ -905,6 +906,10 @@ public final class MediaCas implements AutoCloseable {
      * Open a session to descramble one or more streams scrambled by the
      * conditional access system.
      *
+     * <p>Tuner resource manager (TRM) uses the client priority value to decide whether it is able
+     * to get cas session resource if cas session resources is limited. If the client can't get the
+     * resource, this call returns {@link MediaCasException.InsufficientResourceException }.
+     *
      * @return session the newly opened session.
      *
      * @throws IllegalStateException if the MediaCas instance is not valid.
@@ -930,6 +935,10 @@ public final class MediaCas implements AutoCloseable {
      * Open a session with usage and scrambling information, so that descrambler can be configured
      * to descramble one or more streams scrambled by the conditional access system.
      *
+     * <p>Tuner resource manager (TRM) uses the client priority value to decide whether it is able
+     * to get cas session resource if cas session resources is limited. If the client can't get the
+     * resource, this call returns {@link MediaCasException.InsufficientResourceException}.
+     *
      * @param sessionUsage used for the created session.
      * @param scramblingMode used for the created session.
      *
diff --git a/media/java/android/media/tv/tuner/Tuner.java b/media/java/android/media/tv/tuner/Tuner.java
index 824255995de09..21e11b523d6a3 100644
--- a/media/java/android/media/tv/tuner/Tuner.java
+++ b/media/java/android/media/tv/tuner/Tuner.java
@@ -453,6 +453,10 @@ public class Tuner implements AutoCloseable  {
     /**
      * Tunes the frontend to using the settings given.
      *
+     * <p>Tuner resource manager (TRM) uses the client priority value to decide whether it is able
+     * to get frontend resource. If the client can't get the resource, this call returns {@link
+     * Result#RESULT_UNAVAILABLE}.
+     *
      * <p>
      * This locks the frontend to a frequency by providing signal
      * delivery information. If previous tuning isn't completed, this stop the previous tuning, and