Add javadoc to PermissionManager

5 files changed, 150 insertions, 9 deletions

diff --git a/sdl_android/src/main/java/com/smartdevicelink/api/PermissionManager/OnPermissionChangeListener.java b/sdl_android/src/main/java/com/smartdevicelink/api/PermissionManager/OnPermissionChangeListener.java
index 4748680f1..bebe0c92c 100644
--- a/sdl_android/src/main/java/com/smartdevicelink/api/PermissionManager/OnPermissionChangeListener.java
+++ b/sdl_android/src/main/java/com/smartdevicelink/api/PermissionManager/OnPermissionChangeListener.java
@@ -6,6 +6,15 @@ import com.smartdevicelink.protocol.enums.FunctionID;
 
 import java.util.Map;
 
+/**
+ * OnPermissionChangeListener is a listener which includes a callback method that can be called when there are permission changes
+ */
 public interface OnPermissionChangeListener {
+    /**
+     * Call back method that PermissionManager will call to inform the developer about permission changes
+     * @param allowedPermissions an overall view about the status of the permissions
+     * @param permissionGroupStatus a detailed view about which permissions are allowed and which ones are not
+     * @see com.smartdevicelink.api.PermissionManager.PermissionManager.PermissionGroupStatus
+     */
     void onPermissionsChange(@NonNull Map<FunctionID, PermissionStatus> allowedPermissions, @NonNull @PermissionManager.PermissionGroupStatus int permissionGroupStatus);
 }
diff --git a/sdl_android/src/main/java/com/smartdevicelink/api/PermissionManager/PermissionElement.java b/sdl_android/src/main/java/com/smartdevicelink/api/PermissionManager/PermissionElement.java
index faf9986b1..0b6b1b78e 100644
--- a/sdl_android/src/main/java/com/smartdevicelink/api/PermissionManager/PermissionElement.java
+++ b/sdl_android/src/main/java/com/smartdevicelink/api/PermissionManager/PermissionElement.java
@@ -6,27 +6,52 @@ import com.smartdevicelink.protocol.enums.FunctionID;
 
 import java.util.List;
 
+/**
+ * PermissionElement holds the RPC name that the developer wants to add a listener for.
+ * It also holds any permission parameters for that RPC that the developer wants to track as well.
+ */
 public class PermissionElement {
     private FunctionID rpcName;
     private List<String> parameters;
 
+    /**
+     * Create a new instance of PermissionElement
+     * @param rpcName
+     * @param parameters
+     */
     public PermissionElement(@NonNull FunctionID rpcName, List<String> parameters){
         this.rpcName = rpcName;
         this.parameters = parameters;
     }
 
+    /**
+     * Get the RPC name
+     * @return FunctionID value represents the RPC name
+     */
     public FunctionID getRpcName() {
         return rpcName;
     }
 
+    /**
+     * Set the RPC name
+     * @param rpcName
+     */
     public void setRpcName(@NonNull FunctionID rpcName) {
         this.rpcName = rpcName;
     }
 
+    /**
+     * Get the permission parameters for the RPC
+     * @return List<String> represents the permission parameters for the RPC
+     */
     public List<String> getParameters() {
         return parameters;
     }
 
+    /**
+     * Set the permission parameters for the RPC
+     * @param parameters
+     */
     public void setParameters(List<String> parameters) {
         this.parameters = parameters;
     }
diff --git a/sdl_android/src/main/java/com/smartdevicelink/api/PermissionManager/PermissionFilter.java b/sdl_android/src/main/java/com/smartdevicelink/api/PermissionManager/PermissionFilter.java
index d93394022..34bd76d36 100644
--- a/sdl_android/src/main/java/com/smartdevicelink/api/PermissionManager/PermissionFilter.java
+++ b/sdl_android/src/main/java/com/smartdevicelink/api/PermissionManager/PermissionFilter.java
@@ -5,12 +5,23 @@ import android.support.annotation.NonNull;
 import java.util.List;
 import java.util.UUID;
 
+/**
+ * PermissionFilter holds all the required information for a specific OnPermissionChangeListener
+ */
 class PermissionFilter {
     private UUID identifier;
     private List<PermissionElement> permissionElements;
     private int groupType;
     private OnPermissionChangeListener listener;
 
+    /**
+     * Creates a new instance of PermissionFilter
+     * @param identifier
+     * @param permissionElements
+     * @param groupType
+     * @param listener
+     * @see com.smartdevicelink.api.PermissionManager.PermissionManager.PermissionGroupType
+     */
     PermissionFilter(UUID identifier, @NonNull List<PermissionElement> permissionElements, @NonNull @PermissionManager.PermissionGroupType int groupType, @NonNull OnPermissionChangeListener listener) {
         this.identifier = identifier;
         if (this.identifier == null) {
@@ -21,18 +32,35 @@ class PermissionFilter {
         this.listener = listener;
     }
 
+    /**
+     * Get the unique id for the listener
+     * @return UUID object represents the id for the listener
+     */
     protected UUID getIdentifier() {
         return identifier;
     }
 
+    /**
+     * Get the permission elements that the developer wants to add a listener for
+     * @return List<PermissionElement> represents the RPCs and their parameters that the developer wants to add a listener for
+     */
     protected List<PermissionElement> getPermissionElements() {
         return permissionElements;
     }
 
-    protected int getGroupType() {
+    /**
+     * Get how we want the listener to be called: when any change happens? or when all permissions become allowed?
+     * @return PermissionGroupType int value represents whether the developer needs the listener to be called when there is any permissions change or only when all permission become allowed
+     * @see com.smartdevicelink.api.PermissionManager.PermissionManager.PermissionGroupType
+     */
+    protected @PermissionManager.PermissionGroupType int getGroupType() {
         return groupType;
     }
 
+    /**
+     * Get the listener object
+     * @return OnPermissionChangeListener object represents the listener for that filter
+     */
     protected OnPermissionChangeListener getListener() {
         return listener;
     }
diff --git a/sdl_android/src/main/java/com/smartdevicelink/api/PermissionManager/PermissionManager.java b/sdl_android/src/main/java/com/smartdevicelink/api/PermissionManager/PermissionManager.java
index cd0350cbd..ecc3e5746 100644
--- a/sdl_android/src/main/java/com/smartdevicelink/api/PermissionManager/PermissionManager.java
+++ b/sdl_android/src/main/java/com/smartdevicelink/api/PermissionManager/PermissionManager.java
@@ -51,7 +51,10 @@ import java.util.UUID;
     public static final int PERMISSION_GROUP_TYPE_ALL_ALLOWED = 0;  // Be notified when all of the permission in the group are allowed, or, when they all stop being allowed in some sense, that is, when they were all allowed, and now they are not.
     public static final int PERMISSION_GROUP_TYPE_ANY = 1;          // Be notified when any change in availability occurs among the group
 
-
+    /**
+     * Creates a new instance of the PermissionManager
+     * @param internalInterface
+     */
     public PermissionManager(@NonNull ISdl internalInterface){
         super(internalInterface);
         transitionToState(ManagerState.SETTING_UP);
@@ -63,7 +66,9 @@ import java.util.UUID;
         setupInternalListeners();
     }
 
-    // Setup the PermissionManager's internal listeners
+    /**
+     * Setup the PermissionManager's internal listeners
+     */
     private void setupInternalListeners() {
         // Set PermissionManager's OnHMIStatusListener to keep currentHMILevel updated
         onHMIStatusListener = new OnRPCNotificationListener() {
@@ -133,12 +138,21 @@ import java.util.UUID;
         internalInterface.addOnRPCNotificationListener(FunctionID.ON_PERMISSIONS_CHANGE, onPermissionsChangeListener);
     }
 
-    // Determine if an individual RPC is allowed for the current HMI level
+    /**
+     * Determine if an individual RPC is allowed for the current HMI level
+     * @param rpcName
+     * @return boolean represents whether the RPC is allowed or not
+     */
     public boolean isRPCAllowed(@NonNull FunctionID rpcName){
         return isRPCAllowed(rpcName, currentHMILevel);
     }
 
-
+    /**
+     * Determine if an individual RPC is allowed for any HMI level
+     * @param rpcName
+     * @param hmiLevel
+     * @return boolean represents whether the RPC is allowed or not
+     */
     private boolean isRPCAllowed(@NonNull FunctionID rpcName, HMILevel hmiLevel){
         PermissionItem permissionItem = permissions.get(rpcName);
         if (hmiLevel == null || permissionItem == null || permissionItem.getHMIPermissions() == null || permissionItem.getHMIPermissions().getAllowed() == null){
@@ -150,6 +164,12 @@ import java.util.UUID;
         }
     }
 
+    /**
+     * Determine if an individual permission parameter is allowed for the current HMI level
+     * @param rpcName
+     * @param parameter
+     * @return boolean represents whether the permission parameter is allowed or not
+     */
     public boolean isPermissionParameterAllowed(@NonNull FunctionID rpcName, @NonNull String parameter){
         PermissionItem permissionItem = permissions.get(rpcName);
         if (!isRPCAllowed(rpcName) || permissionItem.getParameterPermissions() == null || permissionItem.getParameterPermissions().getAllowed() == null){
@@ -161,6 +181,9 @@ import java.util.UUID;
         }
     }
 
+    /**
+     * Clean up everything after the manager is no longer needed
+     */
     public void dispose(){
         super.dispose();
 
@@ -178,7 +201,12 @@ import java.util.UUID;
         transitionToState(ManagerState.SHUTDOWN);
     }
 
-    // Determine if a group of permissions is allowed for the current HMI level
+    /**
+     * Determine if a group of permissions is allowed for the current HMI level
+     * @param permissionElements
+     * @return PermissionGroupStatus int value that gives an overall view whether the permissions are allowed or not
+     * @see PermissionGroupStatus
+     */
     public @PermissionGroupStatus int getGroupStatusOfPermissions(@NonNull List<PermissionElement> permissionElements){
         if (currentHMILevel == null){
             return PERMISSION_GROUP_STATUS_UNKNOWN;
@@ -223,8 +251,12 @@ import java.util.UUID;
         }
     }
 
-    // Retrieve a map with keys that are the passed in RPC names specifying if that RPC
-    // and its parameter permissions are currently allowed for the current HMI level
+    /**
+     * Determine if a group of permissions is allowed for the current HMI level
+     * This method is similar to getGroupStatusOfPermissions() but returns more detailed result about each individual permission
+     * @param permissionElements
+     * @return a map with keys that are the passed in RPC names specifying if that RPC and its parameter permissions are currently allowed for the current HMI level
+     */
     public Map <FunctionID, PermissionStatus> getStatusOfPermissions(@NonNull List<PermissionElement> permissionElements){
         Map<FunctionID, PermissionStatus> statusOfPermissions = new HashMap<>();
         for (PermissionElement permissionElement : permissionElements) {
@@ -244,19 +276,33 @@ import java.util.UUID;
         return statusOfPermissions;
     }
 
+    /**
+     * Call the listener for a specific filter
+     * @param filter
+     */
     private void callFilterListener(@NonNull PermissionFilter filter){
         int permissionGroupStatus = getGroupStatusOfPermissions(filter.getPermissionElements());
         Map <FunctionID, PermissionStatus> allowedPermissions = getStatusOfPermissions(filter.getPermissionElements());
         filter.getListener().onPermissionsChange(allowedPermissions, permissionGroupStatus);
     }
 
+    /**
+     * Add a listener to be called when there is permissions change
+     * @param permissionElements
+     * @param groupType PermissionGroupType int value represents whether we need the listener to be called when there is any permissions change or only when all permission become allowed
+     * @param listener
+     * @return unique uuid number for the listener. It can be used to remove the listener later.
+     */
     public UUID addListener(@NonNull List<PermissionElement> permissionElements, @NonNull @PermissionGroupType int groupType, @NonNull OnPermissionChangeListener listener){
         PermissionFilter filter = new PermissionFilter(null, permissionElements, groupType, listener);
         filters.add(filter);
         return filter.getIdentifier();
     }
 
-    // Removes specific listener
+    /**
+     * Removes specific listener
+     * @param listenerId
+     */
     public void removeListener(@NonNull UUID listenerId){
         for (PermissionFilter filter : filters) {
             if (filter.getIdentifier().equals(listenerId)) {
diff --git a/sdl_android/src/main/java/com/smartdevicelink/api/PermissionManager/PermissionStatus.java b/sdl_android/src/main/java/com/smartdevicelink/api/PermissionManager/PermissionStatus.java
index 28980bf16..95f90f56a 100644
--- a/sdl_android/src/main/java/com/smartdevicelink/api/PermissionManager/PermissionStatus.java
+++ b/sdl_android/src/main/java/com/smartdevicelink/api/PermissionManager/PermissionStatus.java
@@ -6,37 +6,70 @@ import com.smartdevicelink.protocol.enums.FunctionID;
 
 import java.util.Map;
 
+/**
+ * PermissionStatus gives a detailed view about whether an RPC and its permission parameters are allowed or not
+ */
 public class PermissionStatus {
     private FunctionID rpcName;
     private boolean isRPCAllowed;
     private Map<String, Boolean> allowedParameters;
 
+    /**
+     * Creates a new PermissionStatus instance
+     * @param rpcName
+     * @param isRPCAllowed
+     * @param allowedParameters
+     */
     public PermissionStatus(@NonNull FunctionID rpcName, @NonNull boolean isRPCAllowed, Map<String, Boolean> allowedParameters) {
         this.rpcName = rpcName;
         this.isRPCAllowed = isRPCAllowed;
         this.allowedParameters = allowedParameters;
     }
 
+    /**
+     * Get the name of the RPC
+     * @return FunctionID value represents the name of the RPC
+     */
     public FunctionID getRpcName() {
         return rpcName;
     }
 
+    /**
+     * Set the name of the RPC
+     * @param rpcName
+     */
     protected void setRpcName(@NonNull FunctionID rpcName) {
         this.rpcName = rpcName;
     }
 
+    /**
+     * Get whether the RCP is allowed or not
+     * @return boolean represents whether the RCP is allowed or not
+     */
     public boolean getIsRPCAllowed() {
         return isRPCAllowed;
     }
 
+    /**
+     * Set whether the RPC is allowed or not
+     * @param isRPCAllowed
+     */
     protected void setIsRPCAllowed(@NonNull boolean isRPCAllowed) {
         this.isRPCAllowed = isRPCAllowed;
     }
 
+    /**
+     * Get the status of the permission parameter for the RPC
+     * @return Map<String, Boolean> object with keys that represent the permission parameter names and values that represent whether the parameters are allowed or not
+     */
     public Map<String, Boolean> getAllowedParameters() {
         return allowedParameters;
     }
 
+    /**
+     * Set the status of the permission parameter for the RPC
+     * @param allowedParameters
+     */
     protected void setAllowedParameters(Map<String, Boolean> allowedParameters) {
         this.allowedParameters = allowedParameters;
     }