Fixes to DrmConvertedStatus, DrmInfoStatus, and DrmSupportInfo classes

o added missing javadoc comment for some public fields
o added checks for arguments
o DrmSupportInfo should have not been exposed as public.
  A default package access modifier appears to be more proper but we may
  not be able to change the modifier.

Change-Id: I5b284c17219c5121f241ee2934fb3e859ce7c827

3 files changed, 136 insertions, 47 deletions

diff --git a/drm/java/android/drm/DrmConvertedStatus.java b/drm/java/android/drm/DrmConvertedStatus.java
index cecb135..f6e570a 100755
--- a/drm/java/android/drm/DrmConvertedStatus.java
+++ b/drm/java/android/drm/DrmConvertedStatus.java
@@ -18,36 +18,67 @@ package android.drm;
 
 /**
  * An entity class that wraps converted data, conversion status, and the
- * offset for appending the header and body signature to the converted data. An instance of this
- * class is returned by the {@link DrmManagerClient#convertData convertData()} and
- * {@link DrmManagerClient#closeConvertSession closeConvertSession()} methods. The offset is provided only when a
- * conversion session is closed by calling {@link DrmManagerClient#closeConvertSession closeConvertSession()}.
+ * offset for appending the header and body signature to the converted data.
+ * An instance of this class may be created two ways by the drm framework:
+ * a) a call to {@link DrmManagerClient#convertData DrmManagerClient.convertData()} and
+ * b) a call to {@link DrmManagerClient#closeConvertSession DrmManagerClient.closeConvertSession()}.
+ * An valid offset value is provided only from a success call to
+ * {@link DrmManagerClient#closeConvertSession DrmManagerClient.closeConvertSession()}.
  *
  */
 public class DrmConvertedStatus {
-    // Should be in sync with DrmConvertedStatus.cpp
+    // The following status code constants must be in sync with
+    // DrmConvertedStatus.cpp. Please also update isValidStatusCode()
+    // when more status code constants are added.
+    /**
+     * Indicate the conversion status is successful.
+     */
     public static final int STATUS_OK = 1;
+    /**
+     * Indicate a failed conversion status due to input data.
+     */
     public static final int STATUS_INPUTDATA_ERROR = 2;
+    /**
+     * Indicate a general failed conversion status.
+     */
     public static final int STATUS_ERROR = 3;
 
-    /** Status code for the conversion.*/
+    /**
+     * Status code for the conversion. Must be one of the defined status
+     * constants above.
+     */
     public final int statusCode;
-    /** Converted data.*/
+    /**
+     * Converted data. It is optional and thus can be null.
+     */
     public final byte[] convertedData;
-    /** Offset value for the body and header signature.*/
+    /**
+     * Offset value for the body and header signature.
+     */
     public final int offset;
 
     /**
      * Creates a <code>DrmConvertedStatus</code> object with the specified parameters.
      *
-     * @param _statusCode Conversion status.
-     * @param _convertedData Converted data.
-     * @param _offset Offset value for appending the header and body signature.
+     * @param statusCode Conversion status. Must be one of the status code constants
+     * defined above.
+     * @param convertedData Converted data. It can be null.
+     * @param offset Offset value for appending the header and body signature.
      */
-    public DrmConvertedStatus(int _statusCode, byte[] _convertedData, int _offset) {
-        statusCode = _statusCode;
-        convertedData = _convertedData;
-        offset = _offset;
+    public DrmConvertedStatus(int statusCode, byte[] convertedData, int offset) {
+        if (!isValidStatusCode(statusCode)) {
+            throw new IllegalArgumentException("Unsupported status code: " + statusCode);
+        }
+
+        this.statusCode = statusCode;
+        this.convertedData = convertedData;
+        this.offset = offset;
+    }
+
+    private boolean isValidStatusCode(int statusCode) {
+        return statusCode == STATUS_OK ||
+               statusCode == STATUS_INPUTDATA_ERROR ||
+               statusCode == STATUS_ERROR;
     }
 }
 
diff --git a/drm/java/android/drm/DrmInfoStatus.java b/drm/java/android/drm/DrmInfoStatus.java
index 2fe0a78..9a3a7df 100755
--- a/drm/java/android/drm/DrmInfoStatus.java
+++ b/drm/java/android/drm/DrmInfoStatus.java
@@ -17,53 +17,81 @@
 package android.drm;
 
 /**
- * An entity class that wraps the result of communication between a device and an online DRM
- * server. Specifically, when the {@link DrmManagerClient#processDrmInfo processDrmInfo()} method
- * is called, an instance of <code>DrmInfoStatus</code> is returned.
+ * An entity class that wraps the result of communication between a device
+ * and an online DRM server. Specifically, when the
+ * {@link DrmManagerClient#processDrmInfo DrmManagerClient.processDrmInfo()}
+ * method is called, an instance of <code>DrmInfoStatus</code> is returned.
  *<p>
- * This class contains the {@link ProcessedData} object, which can be used to instantiate a
- * {@link DrmRights} object during license acquisition.
+ * This class contains the {@link ProcessedData} object, which can be used
+ * to instantiate a {@link DrmRights} object during license acquisition.
  *
  */
 public class DrmInfoStatus {
-    // Should be in sync with DrmInfoStatus.cpp
+    // The following status code constants must be in sync with DrmInfoStatus.cpp
+    // Please update isValidStatusCode() if more status codes are added.
+    /**
+     * Indicate successful communication.
+     */
     public static final int STATUS_OK = 1;
+
+    /**
+     * Indicate failed communication.
+     */
     public static final int STATUS_ERROR = 2;
 
     /**
-     * The status of the communication.
+     * The status of the communication. Must be one of the defined status
+     * constants above.
      */
     public final int statusCode;
     /**
-     * The type of DRM information processed.
+     * The type of DRM information processed. Must be one of the valid type
+     * constants defined in {@link DrmInfoRequest}.
      */
     public final int infoType;
     /**
-     * The MIME type of the content.
+     * The MIME type of the content. Must not be null or an empty string.
      */
     public final String mimeType;
     /**
-     * The processed data.
+     * The processed data. It is optional and thus could be null. When it
+     * is null, it indicates that a particular call to
+     * {@link DrmManagerClient#processDrmInfo DrmManagerClient.processDrmInfo()}
+     * does not return any additional useful information except for the status code.
      */
     public final ProcessedData data;
 
     /**
      * Creates a <code>DrmInfoStatus</code> object with the specified parameters.
      *
-     * @param _statusCode The status of the communication.
-     * @param _infoType The type of the DRM information processed.
-     * @param _data The processed data.
-     * @param _mimeType The MIME type.
+     * @param statusCode The status of the communication. Must be one of the defined
+     * status constants above.
+     * @param infoType The type of the DRM information processed. Must be a valid
+     * type for {@link DrmInfoRequest}.
+     * @param data The processed data.
+     * @param mimeType The MIME type.
      */
-    public DrmInfoStatus(int _statusCode, int _infoType, ProcessedData _data, String _mimeType) {
-        if (!DrmInfoRequest.isValidType(_infoType)) {
-            throw new IllegalArgumentException("infoType: " + _infoType);
+    public DrmInfoStatus(int statusCode, int infoType, ProcessedData data, String mimeType) {
+        if (!DrmInfoRequest.isValidType(infoType)) {
+            throw new IllegalArgumentException("infoType: " + infoType);
         }
 
-        statusCode = _statusCode;
-        infoType = _infoType;
-        data = _data;
-        mimeType = _mimeType;
+        if (!isValidStatusCode(statusCode)) {
+            throw new IllegalArgumentException("Unsupported status code: " + statusCode);
+        }
+
+        if (mimeType == null || mimeType == "") {
+            throw new IllegalArgumentException("mimeType is null or an empty string");
+        }
+
+        this.statusCode = statusCode;
+        this.infoType = infoType;
+        this.data = data;
+        this.mimeType = mimeType;
+    }
+
+    private boolean isValidStatusCode(int statusCode) {
+        return statusCode == STATUS_OK || statusCode == STATUS_ERROR;
     }
 }
 
diff --git a/drm/java/android/drm/DrmSupportInfo.java b/drm/java/android/drm/DrmSupportInfo.java
index 6484fa7..3694ff4 100755
--- a/drm/java/android/drm/DrmSupportInfo.java
+++ b/drm/java/android/drm/DrmSupportInfo.java
@@ -36,8 +36,16 @@ public class DrmSupportInfo {
      * Adds the specified MIME type to the list of MIME types this DRM plug-in supports.
      *
      * @param mimeType MIME type that can be handles by this DRM plug-in.
+     * Must not be null or an empty string.
      */
     public void addMimeType(String mimeType) {
+        if (mimeType == null) {
+            throw new IllegalArgumentException("mimeType is null");
+        }
+        if (mimeType == "") {
+            throw new IllegalArgumentException("mimeType is an empty string");
+        }
+
         mMimeTypeList.add(mimeType);
     }
 
@@ -45,8 +53,14 @@ public class DrmSupportInfo {
      * Adds the specified file suffix to the list of file suffixes this DRM plug-in supports.
      *
      * @param fileSuffix File suffix that can be handled by this DRM plug-in.
+     * it could be null but not an empty string. When it is null, it indicates
+     * that some DRM content comes with no file suffix.
      */
     public void addFileSuffix(String fileSuffix) {
+        if (fileSuffix == "") {
+            throw new IllegalArgumentException("fileSuffix is an empty string");
+        }
+
         mFileSuffixList.add(fileSuffix);
     }
 
@@ -73,12 +87,18 @@ public class DrmSupportInfo {
     /**
      * Sets a description for the DRM plug-in (agent).
      *
-     * @param description Unique description of plug-in.
+     * @param description Unique description of plug-in. Must not be null
+     * or an empty string.
      */
     public void setDescription(String description) {
-        if (null != description) {
-            mDescription = description;
+        if (description == null) {
+            throw new IllegalArgumentException("description is null");
+        }
+        if (description == "") {
+            throw new IllegalArgumentException("description is an empty string");
         }
+
+        mDescription = description;
     }
 
     /**
@@ -93,7 +113,10 @@ public class DrmSupportInfo {
     }
 
     /**
-     * Retrieves the DRM plug-in (agent) description.
+     * Retrieves the DRM plug-in (agent) description. Even if null or an empty
+     * string is not allowed in {@link #setDescription(String)}, if
+     * {@link #setDescription(String)} is not called, description returned
+     * from this method is an empty string.
      *
      * @return The plug-in description.
      */
@@ -111,20 +134,21 @@ public class DrmSupportInfo {
     }
 
     /**
-     * Overridden <code>equals</code> implementation.
+     * Overridden <code>equals</code> implementation. Two DrmSupportInfo objects
+     * are considered being equal if they support exactly the same set of mime
+     * types, file suffixes, and has exactly the same description.
      *
      * @param object The object to be compared.
      * @return True if equal; false if not equal.
      */
     public boolean equals(Object object) {
-        boolean result = false;
-
         if (object instanceof DrmSupportInfo) {
-            result = mFileSuffixList.equals(((DrmSupportInfo) object).mFileSuffixList) &&
-                    mMimeTypeList.equals(((DrmSupportInfo) object).mMimeTypeList) &&
-                    mDescription.equals(((DrmSupportInfo) object).mDescription);
+            DrmSupportInfo info = (DrmSupportInfo) object;
+            return mFileSuffixList.equals(info.mFileSuffixList) &&
+                   mMimeTypeList.equals(info.mMimeTypeList) &&
+                   mDescription.equals(info.mDescription);
         }
-        return result;
+        return false;
     }
 
     /**
@@ -132,11 +156,17 @@ public class DrmSupportInfo {
      *
      * @param mimeType MIME type.
      * @return True if Mime type is supported; false if MIME type is not supported.
+     * Null or empty string is not a supported mimeType.
      */
     /* package */ boolean isSupportedMimeType(String mimeType) {
         if (null != mimeType && !mimeType.equals("")) {
             for (int i = 0; i < mMimeTypeList.size(); i++) {
                 String completeMimeType = mMimeTypeList.get(i);
+
+                // The reason that equals() is not used is that sometimes,
+                // content distributor might just append something to
+                // the basic MIME type. startsWith() is used to avoid
+                // frequent update of DRM agent.
                 if (completeMimeType.startsWith(mimeType)) {
                     return true;
                 }