Merge pull request #773 from harshanL/master

Fixed java-doc comments issues and added comments to the configs.

components/device-mgt/org.wso2.carbon.device.mgt.common/src/main/java/org/wso2/carbon/device/mgt/common/authorization/DeviceAccessAuthorizationService.java

@@ -55,8 +55,7 @@ public interface DeviceAccessAuthorizationService {
      * DeviceIdentifier list.
      *
      * @param deviceIdentifiers - List of DeviceIdentifiers to be checked for authorization.
-     * @return DeviceAuthorizationResult - Authorization result including the list of authorized devices & unauthorized
+     * @return DeviceAuthorizationResult - Authorization result including the list of authorized devices & unauthorized devices.
-     * devices.
      * @throws DeviceAccessAuthorizationException if something goes wrong when checking the authorization.
      */
     DeviceAuthorizationResult isUserAuthorized(List<DeviceIdentifier> deviceIdentifiers) throws
@@ -68,8 +67,7 @@ public interface DeviceAccessAuthorizationService {
      *
      * @param deviceIdentifiers - List of DeviceIdentifiers to be checked for authorization.
      * @param groupPermissions  - Group Permissions
-     * @return DeviceAuthorizationResult - Authorization result including the list of authorized devices & unauthorized
+     * @return DeviceAuthorizationResult - Authorization result including the list of authorized devices & unauthorized devices.
-     * devices.
      * @throws DeviceAccessAuthorizationException if something goes wrong when checking the authorization.
      */
     DeviceAuthorizationResult isUserAuthorized(List<DeviceIdentifier> deviceIdentifiers, String[] groupPermissions)
@@ -95,8 +93,7 @@ public interface DeviceAccessAuthorizationService {
      * @param deviceIdentifiers - List of DeviceIdentifiers to be checked for authorization.
      * @param username          - User name
      * @param groupPermissions  - Group Permissions
-     * @return DeviceAuthorizationResult - Authorization result including the list of authorized devices & unauthorized
+     * @return DeviceAuthorizationResult - Authorization result including the list of authorized devices & unauthorized devices.
-     * devices.
      * @throws DeviceAccessAuthorizationException if something goes wrong when checking the authorization.
      */
     DeviceAuthorizationResult isUserAuthorized(List<DeviceIdentifier> deviceIdentifiers, String username,
@@ -129,8 +126,7 @@ public interface DeviceAccessAuthorizationService {
      *
      * @param deviceIdentifiers - List of DeviceIdentifiers to be checked for authorization.
      * @param username          - Username of the user to be checked for authorization.
-     * @return DeviceAuthorizationResult - Authorization result including the list of authorized devices & unauthorized
+     * @return DeviceAuthorizationResult - Authorization result including the list of authorized devices & unauthorized devices.
-     * devices.
      * @throws DeviceAccessAuthorizationException if something goes wrong when checking the authorization.
      */
     DeviceAuthorizationResult isUserAuthorized(List<DeviceIdentifier> deviceIdentifiers, String username) throws

components/device-mgt/org.wso2.carbon.device.mgt.common/src/main/java/org/wso2/carbon/device/mgt/common/operation/mgt/OperationManager.java

@@ -17,11 +17,14 @@
  */
 package org.wso2.carbon.device.mgt.common.operation.mgt;
 
-import org.wso2.carbon.device.mgt.common.*;
+import org.wso2.carbon.device.mgt.common.DeviceIdentifier;
+import org.wso2.carbon.device.mgt.common.DeviceManagementException;
+import org.wso2.carbon.device.mgt.common.InvalidDeviceException;
+import org.wso2.carbon.device.mgt.common.PaginationRequest;
+import org.wso2.carbon.device.mgt.common.PaginationResult;
 import org.wso2.carbon.device.mgt.common.push.notification.NotificationStrategy;
 
 import java.util.List;
-import java.util.Map;
 
 /**
  * This represents the Device Operation management functionality which should be implemented by
@@ -34,6 +37,7 @@ public interface OperationManager {
      *
      * @param operation Operation to be added
      * @param devices   List of DeviceIdentifiers to execute the operation
+     * @return Activity object corresponds to the added operation.
      * @throws OperationManagementException If some unusual behaviour is observed while adding the operation
      *         InvalidDeviceException       If addOperation request contains Invalid DeviceIdentifiers.
      */
@@ -43,7 +47,8 @@ public interface OperationManager {
     /**
      * Method to retrieve the list of all operations to a device.
      *
-     * @param deviceId
+     * @param deviceId - Device Identifier of the device
+     * @return A List of operations applied to the given device-id.
      * @throws OperationManagementException If some unusual behaviour is observed while fetching the
      *                                      operation list.
      */
@@ -64,6 +69,7 @@ public interface OperationManager {
      * Method to retrieve the list of available operations to a device.
      *
      * @param deviceId DeviceIdentifier of the device
+     * @return A List of pending operations.
      * @throws OperationManagementException If some unusual behaviour is observed while fetching the
      *                                      operation list.
      */

components/device-mgt/org.wso2.carbon.device.mgt.common/src/main/java/org/wso2/carbon/device/mgt/common/permission/mgt/PermissionManagerService.java

@@ -27,19 +27,20 @@ import java.util.Properties;
 public interface PermissionManagerService {
 
     /**
+     * Adds a permission.
      *
      * @param permission - Permission to be added
-     * @throws PermissionManagementException If some unusual behaviour is observed while adding the
+     * @return A boolean indicating the status of the operation.
-     * permission.
+     * @throws PermissionManagementException If some unusual behaviour is observed while adding the permission.
      */
     boolean addPermission(Permission permission) throws PermissionManagementException;
 
     /**
+     * Fetches a given permission.
      *
      * @param properties - Properties of the permission to be fetched.
      * @return The matched Permission object.
-     * @throws PermissionManagementException If some unusual behaviour is observed while fetching the
+     * @throws PermissionManagementException If some unusual behaviour is observed while fetching the permission.
-     * permission.
      */
     Permission getPermission(Properties properties) throws PermissionManagementException;
 

components/device-mgt/org.wso2.carbon.device.mgt.core/src/main/java/org/wso2/carbon/device/mgt/core/cache/DeviceCacheManager.java

@@ -29,9 +29,45 @@ import java.util.List;
  */
 public interface DeviceCacheManager {
 
+    /**
+     * Adds a given device object to the device-cache.
+     * @param deviceIdentifier - DeviceIdentifier of the device to be added.
+     * @param device - Device object to be added.
+     * @param tenantId - Owning tenant of the device.
+     *
+     */
     void addDeviceToCache(DeviceIdentifier deviceIdentifier, Device device, int tenantId);
-    void removeDeviceFromCache(DeviceIdentifier identifier, int tenantId);
+
-    void removeDevicesFromCache(List<DeviceIdentifier> deviceList, int tenantId);
+    /**
+     * Removes a device object from device-cache.
+     * @param deviceIdentifier - DeviceIdentifier of the device to be removed.
+     * @param tenantId - Owning tenant of the device.
+     *
+     */
+    void removeDeviceFromCache(DeviceIdentifier deviceIdentifier, int tenantId);
+
+    /**
+     * Removes a list of devices from device-cache.
+     * @param deviceList - List of Cache-Keys of the device objects to be removed.
+     *
+     */
+    void removeDevicesFromCache(List<DeviceCacheKey> deviceList);
+
+    /**
+     * Updates a given device object in the device-cache.
+     * @param deviceIdentifier - DeviceIdentifier of the device to be updated.
+     * @param device - Device object to be updated.
+     * @param tenantId - Owning tenant of the device.
+     *
+     */
     void updateDeviceInCache(DeviceIdentifier deviceIdentifier, Device device, int tenantId);
+
+    /**
+     * Fetches a device object from device-cache.
+     * @param deviceIdentifier - DeviceIdentifier of the device to be fetched.
+     * @param tenantId - Owning tenant of the device.
+     * @return Device object
+     *
+     */
     Device getDeviceFromCache(DeviceIdentifier deviceIdentifier, int tenantId);
 }

components/device-mgt/org.wso2.carbon.device.mgt.core/src/main/java/org/wso2/carbon/device/mgt/core/cache/impl/DeviceCacheManagerImpl.java

@@ -73,10 +73,9 @@ public class DeviceCacheManagerImpl implements DeviceCacheManager {
     }
 
     @Override
-    public void removeDevicesFromCache(List<DeviceIdentifier> deviceList, int tenantId) {
+    public void removeDevicesFromCache(List<DeviceCacheKey> deviceList) {
         Cache<DeviceCacheKey, Device> lCache = DeviceManagerUtil.getDeviceCache();
-        for (DeviceIdentifier deviceIdentifier : deviceList) {
+        for (DeviceCacheKey cacheKey : deviceList) {
-            DeviceCacheKey cacheKey = getCacheKey(deviceIdentifier, tenantId);
             if (lCache.containsKey(cacheKey)) {
                 lCache.remove(cacheKey);
             }

features/device-mgt/org.wso2.carbon.device.mgt.server.feature/src/main/resources/conf/cdm-config.xml

@@ -66,10 +66,14 @@
         <ActivityListPageSize>20</ActivityListPageSize>
         <OperationListPageSize>20</OperationListPageSize>
     </PaginationConfiguration>
-    <!--This specifies whether to enable the DeviceStatus Task in this node.-->
+    <!--This specifies whether to enable the DeviceStatus Task in this node. In clustered setup only master node
+     should  have to run this task.-->
     <DeviceStatusTaskConfig>
         <Enable>true</Enable>
     </DeviceStatusTaskConfig>
+    <!--This controls the in-memory device cache which is local to this node. Setting it enable will activate the
+    device caching for upto configured expiry-time in seconds. In clustered setup all worker nodes can enable the
+    device-cache to improve performance. -->
     <DeviceCacheConfiguration>
         <Enable>true</Enable>
         <ExpiryTime>600</ExpiryTime>