Clean code and refine javadocs for control plane manager

Change-Id: Ieaaebde69ce2ab54cb819cfad1baa34ee97a7d66

@@ -23,15 +23,32 @@ public class ControlMetric {
     private final ControlMetricType metricType;
     private final MetricValue metricValue;
 
+    /**
+     * Constructs a control metric using the given control metric type and
+     * metric value.
+     *
+     * @param metricType metric type reference
+     * @param metricValue metric value reference
+     */
     public ControlMetric(ControlMetricType metricType, MetricValue metricValue) {
         this.metricType = metricType;
         this.metricValue = metricValue;
     }
 
+    /**
+     * Returns metric type reference.
+     *
+     * @return metric type reference
+     */
     public ControlMetricType metricType() {
         return metricType;
     }
 
+    /**
+     * Returns metric value reference.
+     *
+     * @return metric value reference
+     */
     public MetricValue metricValue() {
         return metricValue;
     }

@@ -28,38 +28,44 @@ public interface ControlPlaneMonitorService {
     /**
      * Adds a new control metric value with a certain update interval.
      *
-     * @param controlMetric  control plane metric (e.g., control message rate, cpu, memory, etc.)
-     * @param updateInterval value update interval (time unit will be in minute)
-     * @param deviceId       {@link org.onosproject.net.DeviceId}
+     * @param controlMetric             control plane metric (e.g., control
+     *                                  message rate, cpu, memory, etc.)
+     * @param updateIntervalInMinutes   value update interval (in minute)
+     * @param deviceId                  device identifier
      */
-    void updateMetric(ControlMetric controlMetric, Integer updateInterval, Optional<DeviceId> deviceId);
+    void updateMetric(ControlMetric controlMetric, int updateIntervalInMinutes,
+                      Optional<DeviceId> deviceId);
 
     /**
      * Adds a new control metric value with a certain update interval.
      *
-     * @param controlMetric     control plane metric (e.g., disk and network metrics)
-     * @param updateInterval    value update interval (time unit will be in minute)
+     * @param controlMetric              control plane metric (e.g., disk and
+     *                                   network metrics)
+     * @param updateIntervalInMinutes    value update interval (in minute)
      * @param resourceName               resource name
      */
-    void updateMetric(ControlMetric controlMetric, Integer updateInterval, String resourceName);
+    void updateMetric(ControlMetric controlMetric, int updateIntervalInMinutes,
+                      String resourceName);
 
     /**
      * Obtains the control plane load of a specific device.
      * The metrics range from control messages and system metrics
      * (e.g., CPU and memory info)
      *
-     * @param nodeId   node id {@link org.onosproject.cluster.NodeId}
+     * @param nodeId                     node identifier
      * @param type                       control metric type
-     * @param deviceId device id {@link org.onosproject.net.DeviceId}
+     * @param deviceId                   device identifier
      * @return control plane load
      */
-    ControlLoad getLoad(NodeId nodeId, ControlMetricType type, Optional<DeviceId> deviceId);
+    ControlLoad getLoad(NodeId nodeId, ControlMetricType type,
+                        Optional<DeviceId> deviceId);
 
     /**
      * Obtains the control plane load of a specific device.
-     * The metrics range from I/O device metrics (e.g., disk and network interface)
+     * The metrics range from I/O device metrics
+     * (e.g., disk and network interface)
      *
-     * @param nodeId        node id {@link org.onosproject.cluster.NodeId}
+     * @param nodeId                     node identifier
      * @param type                       control metric type
      * @param resourceName               resource name
      * @return control plane load

@@ -27,7 +27,7 @@ public final class MetricValue {
     private final long count;
 
     /**
-     * Constructor.
+     * Constructs a metric value using the given rate, load and count.
      *
      * @param rate rate
      * @param load load

@@ -145,9 +145,9 @@ public interface MetricsDatabase {
         Builder addMetricType(String metricType);
 
         /**
-         * Builds a MetricDatabase instance.
+         * Builds a metric database instance.
          *
-         * @return MetricDatabase instance
+         * @return metric database instance
          */
         MetricsDatabase build();
     }

@@ -67,6 +67,12 @@ public final class ControlMetricsFactory {
     private Set<String> diskPartitions = Sets.newConcurrentHashSet();
     private Set<String> nwInterfaces = Sets.newConcurrentHashSet();
 
+    /**
+     * Constructs a control metrics factory using the given metrics and device services.
+     *
+     * @param metricsService metric service reference
+     * @param deviceService  device service reference
+     */
     private ControlMetricsFactory(MetricsService metricsService, DeviceService deviceService) {
         this.metricsService = metricsService;
         registerMetrics();
@@ -76,6 +82,13 @@ public final class ControlMetricsFactory {
         addAllControlMessageMetrics(deviceIds);
     }
 
+    /**
+     * Obtains the unique instance of ControlMetricsFactory.
+     *
+     * @param metricsService metric service
+     * @param deviceService  device service
+     * @return instance of ControlMetricsFactory
+     */
     public static ControlMetricsFactory getInstance(MetricsService metricsService,
                                                     DeviceService deviceService) {
         if (uniqueInstance == null) {
@@ -102,7 +115,7 @@ public final class ControlMetricsFactory {
     /**
      * Adds control metrics of a new device.
      *
-     * @param deviceId {@link org.onosproject.net.DeviceId}
+     * @param deviceId device identifier
      */
     public void addControlMessageMetricsByDeviceId(DeviceId deviceId) {
         MetricsAggregator inbound = new MetricsAggregator(metricsService,
@@ -171,7 +184,7 @@ public final class ControlMetricsFactory {
     /**
      * Removes control metrics of an existing device.
      *
-     * @param deviceId {@link org.onosproject.net.DeviceId}
+     * @param deviceId device identifier
      */
     public void removeControlMessageMetricsByDeviceId(DeviceId deviceId) {
         inboundPacket.remove(deviceId);
@@ -211,9 +224,9 @@ public final class ControlMetricsFactory {
     }
 
     /**
-     * Returns all device ids.
+     * Returns all device identifiers.
      *
-     * @return a collection of device id
+     * @return a collection of device identifiers
      */
     public Set<DeviceId> getDeviceIds() {
         return ImmutableSet.copyOf(this.deviceIds);
@@ -222,7 +235,7 @@ public final class ControlMetricsFactory {
     /**
      * Returns all disk partition names.
      *
-     * @return a collection of disk partition.
+     * @return a collection of disk partitions.
      */
     public Set<String> getDiskPartitions() {
         return ImmutableSet.copyOf(this.diskPartitions);
@@ -231,7 +244,7 @@ public final class ControlMetricsFactory {
     /**
      * Returns all network interface names.
      *
-     * @return a collection of network interface.
+     * @return a collection of network interfaces.
      */
     public Set<String> getNetworkInterfaces() {
         return ImmutableSet.copyOf(this.nwInterfaces);
@@ -240,7 +253,7 @@ public final class ControlMetricsFactory {
     /**
      * Adds control metrics for all devices.
      *
-     * @param deviceIds a set of deviceIds
+     * @param deviceIds a set of device identifiers
      */
     public void addAllControlMessageMetrics(Set<DeviceId> deviceIds) {
         deviceIds.forEach(v -> addControlMessageMetricsByDeviceId(v));
@@ -330,102 +343,239 @@ public final class ControlMetricsFactory {
         replyPacket.clear();
     }
 
+    /**
+     * Returns CPU load metric aggregator.
+     *
+     * @return metric aggregator
+     */
     public MetricsAggregator cpuLoadMetric() {
         return cpuLoad;
     }
 
+    /**
+     * Returns total CPU time metric aggregator.
+     *
+     * @return metric aggregator
+     */
     public MetricsAggregator totalCpuTimeMetric() {
         return totalCpuTime;
     }
 
+    /**
+     * Returns system CPU time metric aggregator.
+     *
+     * @return metric aggregator
+     */
     public MetricsAggregator sysCpuTimeMetric() {
         return sysCpuTime;
     }
 
+    /**
+     * Returns user CPU time metric aggregator.
+     *
+     * @return metric aggregator
+     */
     public MetricsAggregator userCpuTime() {
         return userCpuTime;
     }
 
+    /**
+     * Returns CPU idle time metric aggregator.
+     *
+     * @return metric aggregator
+     */
     public MetricsAggregator cpuIdleTime() {
         return cpuIdleTime;
     }
 
+    /**
+     * Returns free memory ratio metric aggregator.
+     *
+     * @return metric aggregator
+     */
     public MetricsAggregator memoryFreeRatio() {
         return memoryFreeRatio;
     }
 
+    /**
+     * Returns used memory ratio metric aggregator.
+     *
+     * @return metric aggregator
+     */
     public MetricsAggregator memoryUsedRatio() {
         return memoryUsedRatio;
     }
 
-    public MetricsAggregator diskReadBytes(String partitionName) {
-        return diskReadBytes.get(partitionName);
+    /**
+     * Returns disk read bytes metric aggregator.
+     *
+     * @param resourceName name of disk resource
+     * @return metric aggregator
+     */
+    public MetricsAggregator diskReadBytes(String resourceName) {
+        return diskReadBytes.get(resourceName);
     }
 
-    public MetricsAggregator diskWriteBytes(String partitionName) {
-        return diskWriteBytes.get(partitionName);
+    /**
+     * Returns disk write bytes metric aggregator.
+     *
+     * @param resourceName name of disk resource
+     * @return metric aggregator
+     */
+    public MetricsAggregator diskWriteBytes(String resourceName) {
+        return diskWriteBytes.get(resourceName);
     }
 
+    /**
+     * Returns incoming bytes metric aggregator.
+     *
+     * @param interfaceName name of network interface
+     * @return metric aggregator
+     */
     public MetricsAggregator nwIncomingBytes(String interfaceName) {
         return nwIncomingBytes.get(interfaceName);
     }
 
+    /**
+     * Returns outgoing bytes metric aggregator.
+     *
+     * @param interfaceName name of network interface
+     * @return metric aggregator
+     */
     public MetricsAggregator nwOutgoingBytes(String interfaceName) {
         return nwOutgoingBytes.get(interfaceName);
     }
 
+    /**
+     * Returns incoming packets metric aggregator.
+     *
+     * @param interfaceName name of network interface
+     * @return metric aggregator
+     */
     public MetricsAggregator nwIncomingPackets(String interfaceName) {
         return nwIncomingPackets.get(interfaceName);
     }
 
+    /**
+     * Returns outgoing packets metric aggregator.
+     *
+     * @param interfaceName name of network interface
+     * @return metric aggregator
+     */
     public MetricsAggregator nwOutgoingPackets(String interfaceName) {
         return nwOutgoingPackets.get(interfaceName);
     }
 
+    /**
+     * Returns inbound packet metric aggregator of all devices.
+     *
+     * @return metric aggregator
+     */
     public Map<DeviceId, MetricsAggregator> inboundPacket() {
         return ImmutableMap.copyOf(inboundPacket);
     }
 
+    /**
+     * Returns outgoing packet metric aggregator of all devices.
+     *
+     * @return metric aggregator
+     */
     public Map<DeviceId, MetricsAggregator> outboundPacket() {
         return ImmutableMap.copyOf(outboundPacket);
     }
 
+    /**
+     * Returns flow-mod packet metric aggregator of all devices.
+     *
+     * @return metric aggregator
+     */
     public Map<DeviceId, MetricsAggregator> flowmodPacket() {
         return ImmutableMap.copyOf(flowmodPacket);
     }
 
+    /**
+     * Returns flow-removed packet metric aggregator of all devices.
+     *
+     * @return metric aggregator
+     */
     public Map<DeviceId, MetricsAggregator> flowrmvPacket() {
         return ImmutableMap.copyOf(flowrmvPacket);
     }
 
+    /**
+     * Returns request packet metric aggregator of all devices.
+     *
+     * @return metric aggregator
+     */
     public Map<DeviceId, MetricsAggregator> requestPacket() {
         return ImmutableMap.copyOf(requestPacket);
     }
 
+    /**
+     * Returns reply packet metric aggregator of all devices.
+     *
+     * @return metric aggregator
+     */
     public Map<DeviceId, MetricsAggregator> replyPacket() {
         return ImmutableMap.copyOf(replyPacket);
     }
 
+    /**
+     * Returns inbound packet metric aggregator of a specified device.
+     *
+     * @param deviceId device identifier
+     * @return metric aggregator
+     */
     public MetricsAggregator inboundPacket(DeviceId deviceId) {
         return inboundPacket.get(deviceId);
     }
 
+    /**
+     * Returns outbound packet metric aggregator of a specified device.
+     *
+     * @param deviceId device identifier
+     * @return metric aggregator
+     */
     public MetricsAggregator outboundPacket(DeviceId deviceId) {
         return outboundPacket.get(deviceId);
     }
 
+    /**
+     * Returns flow-mod packet metric aggregator of a specified device.
+     *
+     * @param deviceId device identifier
+     * @return metric aggregator
+     */
     public MetricsAggregator flowmodPacket(DeviceId deviceId) {
         return flowmodPacket.get(deviceId);
     }
 
+    /**
+     * Returns flow-removed packet metric aggregator of a specified device.
+     *
+     * @param deviceId device identifier
+     * @return metric aggregator
+     */
     public MetricsAggregator flowrmvPacket(DeviceId deviceId) {
         return flowrmvPacket.get(deviceId);
     }
 
+    /**
+     * Returns request packet metric aggregator of a specified device.
+     *
+     * @param deviceId device identifier
+     * @return metric aggregator
+     */
     public MetricsAggregator requestPacket(DeviceId deviceId) {
         return requestPacket.get(deviceId);
     }
 
+    /**
+     * Returns reply packet metric aggregator of a specified device.
+     *
+     * @param deviceId device identifier
+     * @return metric aggregator
+     */
     public MetricsAggregator replyPacket(DeviceId deviceId) {
         return replyPacket.get(deviceId);
     }

@@ -28,7 +28,7 @@ public interface ControlMetricsObserver {
      * Feeds the extracted value from MetricAggregator to back-end storage.
      *
      * @param metricsAggregator metric aggregator
-     * @param deviceId          device id {@link org.onosproject.net.DeviceId}
+     * @param deviceId          device identification
      */
     void feedMetrics(MetricsAggregator metricsAggregator, Optional<DeviceId> deviceId);
 

@@ -36,6 +36,7 @@ import org.slf4j.LoggerFactory;
 
 import java.util.Map;
 import java.util.Optional;
+import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;
 
 import static org.onosproject.cpman.ControlMetricType.CPU_IDLE_TIME;
@@ -83,18 +84,18 @@ public class ControlPlaneMonitor implements ControlPlaneMonitorService {
     private static final String DISK = "Disk";
     private static final String NETWORK = "Network";
 
-    private static final ImmutableSet<ControlMetricType> CPU_METRICS =
+    private static final Set<ControlMetricType> CPU_METRICS =
             ImmutableSet.of(CPU_IDLE_TIME, CPU_LOAD, SYS_CPU_TIME,
                     USER_CPU_TIME, TOTAL_CPU_TIME);
-    private static final ImmutableSet<ControlMetricType> MEMORY_METRICS =
+    private static final Set<ControlMetricType> MEMORY_METRICS =
             ImmutableSet.of(MEMORY_FREE, MEMORY_FREE_RATIO, MEMORY_USED,
                     MEMORY_USED_RATIO);
-    private static final ImmutableSet<ControlMetricType> DISK_METRICS =
+    private static final Set<ControlMetricType> DISK_METRICS =
             ImmutableSet.of(DISK_READ_BYTES, DISK_WRITE_BYTES);
-    private static final ImmutableSet<ControlMetricType> NETWORK_METRICS =
+    private static final Set<ControlMetricType> NETWORK_METRICS =
             ImmutableSet.of(NW_INCOMING_BYTES, NW_OUTGOING_BYTES,
                     NW_INCOMING_PACKETS, NW_OUTGOING_PACKETS);
-    private static final ImmutableSet<ControlMetricType> CTRL_MSGS =
+    private static final Set<ControlMetricType> CTRL_MSGS =
             ImmutableSet.of(INBOUND_PACKET, OUTBOUND_PACKET, FLOW_MOD_PACKET,
                     FLOW_REMOVED_PACKET, REQUEST_PACKET, REPLY_PACKET);
     private Map<ControlMetricType, Double> cpuBuf;
@@ -134,7 +135,7 @@ public class ControlPlaneMonitor implements ControlPlaneMonitorService {
     }
 
     @Override
-    public void updateMetric(ControlMetric cm, Integer updateInterval,
+    public void updateMetric(ControlMetric cm, int updateIntervalInMinutes,
                              Optional<DeviceId> deviceId) {
         if (deviceId.isPresent()) {
 
@@ -180,7 +181,7 @@ public class ControlPlaneMonitor implements ControlPlaneMonitorService {
     }
 
     @Override
-    public void updateMetric(ControlMetric cm, Integer updateInterval,
+    public void updateMetric(ControlMetric cm, int updateIntervalInMinutes,
                              String resourceName) {
         // update disk metrics
         if (DISK_METRICS.contains(cm.metricType())) {
@@ -252,7 +253,7 @@ public class ControlPlaneMonitor implements ControlPlaneMonitorService {
     }
 
     private MetricsDatabase genMDbBuilder(String metricName,
-                                          ImmutableSet<ControlMetricType> metricTypes) {
+                                          Set<ControlMetricType> metricTypes) {
         MetricsDatabase.Builder builder = new DefaultMetricsDatabase.Builder();
         builder.withMetricName(metricName);
         metricTypes.forEach(type -> builder.addMetricType(type.toString()));

@@ -31,6 +31,13 @@ public class DefaultControlLoad implements ControlLoad {
     private final MetricsDatabase mdb;
     private final ControlMetricType type;
 
+    /**
+     * Constructs a control load using the given metrics database and
+     * control metric type.
+     *
+     * @param mdb  metrics database
+     * @param type control metric type
+     */
     public DefaultControlLoad(MetricsDatabase mdb, ControlMetricType type) {
         this.mdb = mdb;
         this.type = type;

@@ -53,6 +53,13 @@ public final class DefaultMetricsDatabase implements MetricsDatabase {
     private static final String INSUFFICIENT_DURATION = "Given duration less than one minute.";
     private static final String EXCEEDED_DURATION = "Given duration exceeds a day time.";
 
+    /**
+     * Constructs a metrics database using the given metric name and
+     * round robin database.
+     *
+     * @param metricName  metric name
+     * @param rrdDb       round robin database
+     */
     private DefaultMetricsDatabase(String metricName, RrdDb rrdDb) {
         this.metricName = metricName;
         this.rrdDb = rrdDb;

@@ -43,13 +43,13 @@ public class MetricsAggregator {
     private static final String COUNT_NAME = "count";
 
     /**
-     * Constructs a new MetricsAggregator for aggregating a metric.
+     * Constructs a new metrics aggregator for aggregating a metric.
      * Instantiates the metrics service
      * Initializes all the general metrics for that object
      *
-     * @param metricsService MetricsService reference
-     * @param type           Control metric type
-     * @param deviceId       DeviceId
+     * @param metricsService metric service reference
+     * @param type           control metric type
+     * @param deviceId       device identification
      */
     MetricsAggregator(MetricsService metricsService, ControlMetricType type,
                       Optional<DeviceId> deviceId) {
@@ -57,12 +57,12 @@ public class MetricsAggregator {
     }
 
     /**
-     * Constructs a new MetricAggregator for aggregating a metric.
+     * Constructs a new metrics aggregator for aggregating a metric.
      * Instantiates the metrics service
      * Initializes all the general metrics for that object
      *
-     * @param metricsService MetricsService reference
-     * @param type           Control metric type
+     * @param metricsService metric service reference
+     * @param type           control metric type
      * @param resourceName   resource name (e.g., ethernet interface name)
      */
     MetricsAggregator(MetricsService metricsService, ControlMetricType type,
@@ -72,12 +72,12 @@ public class MetricsAggregator {
     }
 
     /**
-     * Constructs a new MetricAggregator for aggregating a metric.
+     * Constructs a new metrics aggregator for aggregating a metric.
      * Instantiates the metrics service
      * Initializes all the general metrics for that object
      *
-     * @param metricsService MetricsService reference
-     * @param type           Control metric type
+     * @param metricsService metrics service reference
+     * @param type           control metric type
      */
     MetricsAggregator(MetricsService metricsService, ControlMetricType type) {
         init(metricsService, type, Optional.ofNullable(null), null);
@@ -86,9 +86,9 @@ public class MetricsAggregator {
     /**
      * Base method of the constructor of this class.
      *
-     * @param metricsService MetricsService reference
-     * @param type           Control metric type
-     * @param deviceId       DeviceId
+     * @param metricsService metrics service reference
+     * @param type           control metric type
+     * @param deviceId       device identification
      * @param resourceName   resource name
      */
     private void init(MetricsService metricsService, ControlMetricType type,
@@ -116,14 +116,19 @@ public class MetricsAggregator {
         this.countMeter = metricsService.createMeter(metricsComponent, metricsFeature, COUNT_NAME);
     }
 
+    /**
+     * Returns control metrics type.
+     *
+     * @return control metrics type
+     */
     public ControlMetricType getMetricsType() {
         return metricsType;
     }
 
     /**
-     * Increments the meter rate by {@code n}, and the meter counter by 1.
+     * Increments the meter rate by n, and the meter counter by 1.
      *
-     * @param n Increment the meter rate by {@code n}.
+     * @param n increment rate.
      */
     public void increment(long n) {
         rateMeter.mark(n);
@@ -131,7 +136,7 @@ public class MetricsAggregator {
     }
 
     /**
-     * Obtains the average load value.
+     * Returns the average load value.
      *
      * @return load value
      */
@@ -140,7 +145,7 @@ public class MetricsAggregator {
     }
 
     /**
-     * Obtains the average meter rate within recent 1 minute.
+     * Returns the average meter rate within recent 1 minute.
      *
      * @return rate value
      */
@@ -149,7 +154,7 @@ public class MetricsAggregator {
     }
 
     /**
-     * Obtains the average meter count within recent 1 minute.
+     * Returns the average meter count within recent 1 minute.
      *
      * @return count value
      */

@@ -36,6 +36,7 @@ import java.net.HttpURLConnection;
 import java.net.ServerSocket;
 import java.util.Optional;
 
+import static org.easymock.EasyMock.anyInt;
 import static org.easymock.EasyMock.anyObject;
 import static org.easymock.EasyMock.anyString;
 import static org.easymock.EasyMock.createMock;
@@ -68,7 +69,7 @@ public class ControlMetricsCollectorResourceTest extends JerseyTest {
 
     @Test
     public void testCpuMetricsPost() {
-        mockControlPlaneMonitorService.updateMetric(anyObject(), anyObject(),
+        mockControlPlaneMonitorService.updateMetric(anyObject(), anyInt(),
                 (Optional<DeviceId>) anyObject());
         expectLastCall().times(5);
         replay(mockControlPlaneMonitorService);
@@ -77,7 +78,7 @@ public class ControlMetricsCollectorResourceTest extends JerseyTest {
 
     @Test
     public void testMemoryMetricsPost() {
-        mockControlPlaneMonitorService.updateMetric(anyObject(), anyObject(),
+        mockControlPlaneMonitorService.updateMetric(anyObject(), anyInt(),
                 (Optional<DeviceId>) anyObject());
         expectLastCall().times(4);
         replay(mockControlPlaneMonitorService);
@@ -86,7 +87,7 @@ public class ControlMetricsCollectorResourceTest extends JerseyTest {
 
     @Test
     public void testDiskMetricsWithNullName() {
-        mockControlPlaneMonitorService.updateMetric(anyObject(), anyObject(), anyString());
+        mockControlPlaneMonitorService.updateMetric(anyObject(), anyInt(), anyString());
         expectLastCall().times(4);
         replay(mockControlPlaneMonitorService);
         basePostTest("disk-metrics-post.json", PREFIX + "/disk_metrics");
@@ -94,7 +95,7 @@ public class ControlMetricsCollectorResourceTest extends JerseyTest {
 
     @Test
     public void testNetworkMetricsWithNullName() {
-        mockControlPlaneMonitorService.updateMetric(anyObject(), anyObject(), anyString());
+        mockControlPlaneMonitorService.updateMetric(anyObject(), anyInt(), anyString());
         expectLastCall().times(8);
         replay(mockControlPlaneMonitorService);
         basePostTest("network-metrics-post.json", PREFIX + "/network_metrics");