Merge "API review: Builder for TableResponse" into udc-dev

core/api/current.txt

@@ -26782,9 +26782,7 @@ package android.media.tv {
   }
 
   public final class TableResponse extends android.media.tv.BroadcastInfoResponse implements android.os.Parcelable {
-    ctor public TableResponse(int, int, int, @Nullable android.net.Uri, int, int);
+    ctor @Deprecated public TableResponse(int, int, int, @Nullable android.net.Uri, int, int);
-    ctor public TableResponse(int, int, int, @NonNull byte[], int, int);
-    ctor public TableResponse(int, int, int, @NonNull android.os.SharedMemory, int, int);
     method public int getSize();
     method @Nullable public byte[] getTableByteArray();
     method @Nullable public android.os.SharedMemory getTableSharedMemory();
@@ -26793,6 +26791,14 @@ package android.media.tv {
     field @NonNull public static final android.os.Parcelable.Creator<android.media.tv.TableResponse> CREATOR;
   }
 
+  public static final class TableResponse.Builder {
+    ctor public TableResponse.Builder(int, int, int, int, int);
+    method @NonNull public android.media.tv.TableResponse build();
+    method @NonNull public android.media.tv.TableResponse.Builder setTableByteArray(@NonNull byte[]);
+    method @NonNull public android.media.tv.TableResponse.Builder setTableSharedMemory(@NonNull android.os.SharedMemory);
+    method @NonNull public android.media.tv.TableResponse.Builder setTableUri(@NonNull android.net.Uri);
+  }
+
   public final class TimelineRequest extends android.media.tv.BroadcastInfoRequest implements android.os.Parcelable {
     ctor public TimelineRequest(int, int, int);
     ctor public TimelineRequest(int, int, int, @NonNull String);

media/java/android/media/tv/TableResponse.java

@@ -64,7 +64,10 @@ public final class TableResponse extends BroadcastInfoResponse implements Parcel
      * @param tableUri The URI of the table in the database.
      * @param version The version number of requested table.
      * @param size The Size number of table in bytes.
+     *
+     * @deprecated use {@link Builder} instead.
      */
+    @Deprecated
     public TableResponse(int requestId, int sequence, @ResponseResult int responseResult,
             @Nullable Uri tableUri, int version, int size) {
         super(RESPONSE_TYPE, requestId, sequence, responseResult);
@@ -76,30 +79,7 @@ public final class TableResponse extends BroadcastInfoResponse implements Parcel
     }
 
     /**
-     * Constructs a TableResponse with a table URI.
+     * Constructs a TableResponse.
-     *
-     * @param requestId The ID is used to associate the response with the request.
-     * @param sequence The sequence number which indicates the order of related responses.
-     * @param responseResult The result for the response. It's one of {@link #RESPONSE_RESULT_OK},
-     *                       {@link #RESPONSE_RESULT_CANCEL}, {@link #RESPONSE_RESULT_ERROR}.
-     * @param tableByteArray The byte array which stores the table in bytes. The structure and
-     *                       syntax of the table depends on the table name in
-     *                       {@link TableRequest#getTableName()} and the corresponding standard.
-     * @param version The version number of requested table.
-     * @param size The Size number of table in bytes.
-     */
-    public TableResponse(int requestId, int sequence, @ResponseResult int responseResult,
-            @NonNull byte[] tableByteArray, int version, int size) {
-        super(RESPONSE_TYPE, requestId, sequence, responseResult);
-        mVersion = version;
-        mSize = size;
-        mTableUri = null;
-        mTableByteArray = tableByteArray;
-        mTableSharedMemory = null;
-    }
-
-    /**
-     * Constructs a TableResponse with a table URI.
      *
      * @param requestId The ID is used to associate the response with the request.
      * @param sequence The sequence number which indicates the order of related responses.
@@ -112,17 +92,128 @@ public final class TableResponse extends BroadcastInfoResponse implements Parcel
      *                          {@link TableRequest#getTableName()} and the corresponding standard.
      * @param version The version number of requested table.
      * @param size The Size number of table in bytes.
+     * @param tableUri The URI of the table in the database.
+     * @param tableByteArray The byte array which stores the table in bytes. The structure and
+     *                       syntax of the table depends on the table name in
+     * @param tableSharedMemory The shared memory which stores the table. The table size can be
+     *                          large so using a shared memory optimizes the data
+     *                          communication between the table data source and the receiver. The
+     *                          structure syntax of the table depends on the table name in
+     *                          {@link TableRequest#getTableName()} and the corresponding standard.
      */
-    public TableResponse(int requestId, int sequence, @ResponseResult int responseResult,
+    private TableResponse(int requestId, int sequence, @ResponseResult int responseResult,
-            @NonNull SharedMemory tableSharedMemory, int version, int size) {
+            int version, int size, Uri tableUri, byte[] tableByteArray,
+            SharedMemory tableSharedMemory) {
         super(RESPONSE_TYPE, requestId, sequence, responseResult);
         mVersion = version;
         mSize = size;
-        mTableUri = null;
+        mTableUri = tableUri;
-        mTableByteArray = null;
+        mTableByteArray = tableByteArray;
         mTableSharedMemory = tableSharedMemory;
     }
 
+    /**
+     * Builder for {@link TableResponse}.
+     */
+    public static final class Builder {
+        private final int mRequestId;
+        private final int mSequence;
+        @ResponseResult
+        private final int mResponseResult;
+        private final int mVersion;
+        private final int mSize;
+        private Uri mTableUri;
+        private byte[] mTableByteArray;
+        private SharedMemory mTableSharedMemory;
+
+        /**
+         * Constructs a Builder object of {@link TableResponse}.
+         *
+         * @param requestId The ID is used to associate the response with the request.
+         * @param sequence The sequence number which indicates the order of related responses.
+         * @param responseResult The result for the response. It's one of
+         *                       {@link #RESPONSE_RESULT_OK}, {@link #RESPONSE_RESULT_CANCEL},
+         *                       {@link #RESPONSE_RESULT_ERROR}.
+         * @param version The version number of requested table.
+         * @param size The Size number of table in bytes.
+         */
+        public Builder(int requestId, int sequence, @ResponseResult int responseResult, int version,
+                int size) {
+            mRequestId = requestId;
+            mSequence = sequence;
+            mResponseResult = responseResult;
+            mVersion = version;
+            mSize = size;
+        }
+
+        /**
+         * Sets table URI.
+         *
+         * <p>For a single builder instance, at most one of table URI, table byte array, and table
+         * shared memory can be set. If more than one are set, only the last call takes precedence
+         * and others are reset to {@code null}.
+         *
+         * @param uri The URI of the table.
+         */
+        @NonNull
+        public Builder setTableUri(@NonNull Uri uri) {
+            mTableUri = uri;
+            mTableByteArray = null;
+            mTableSharedMemory = null;
+            return this;
+        }
+
+        /**
+         * Sets table byte array.
+         *
+         * <p>For a single builder instance, at most one of table URI, table byte array, and table
+         * shared memory can be set. If more than one are set, only the last call takes precedence
+         * and others are reset to {@code null}.
+         *
+         * @param bytes The byte array which stores the table in bytes. The structure and
+         *              syntax of the table depends on the table name in
+         *              {@link TableRequest#getTableName()} and the corresponding standard.
+         */
+        @NonNull
+        public Builder setTableByteArray(@NonNull byte[] bytes) {
+            mTableByteArray = bytes;
+            mTableUri = null;
+            mTableSharedMemory = null;
+            return this;
+        }
+
+
+        /**
+         * Sets table shared memory.
+         *
+         * <p>For a single builder instance, at most one of table URI, table byte array, and table
+         * shared memory can be set. If more than one are set, only the last call takes precedence
+         * and others are reset to {@code null}.
+         *
+         * @param sharedMemory The shared memory which stores the table. The table size can be
+         *                     large so using a shared memory optimizes the data
+         *                     communication between the table data source and the receiver. The
+         *                     structure syntax of the table depends on the table name in
+         *                     {@link TableRequest#getTableName()} and the corresponding standard.
+         */
+        @NonNull
+        public Builder setTableSharedMemory(@NonNull SharedMemory sharedMemory) {
+            mTableSharedMemory = sharedMemory;
+            mTableUri = null;
+            mTableByteArray = null;
+            return this;
+        }
+
+        /**
+         * Builds a {@link TableResponse} object.
+         */
+        @NonNull
+        public TableResponse build() {
+            return new TableResponse(mRequestId, mSequence, mResponseResult, mVersion, mSize,
+                    mTableUri, mTableByteArray, mTableSharedMemory);
+        }
+    }
+
     TableResponse(Parcel source) {
         super(RESPONSE_TYPE, source);
         String uriString = source.readString();