Cleaning up Javadocs in core-ui classes.

Promoted Glyphs inner class to GlyphConstants.

Change-Id: Ib12a4556a75d98edb3544b9ae45605fab554fdcf

+/*
+ * Copyright 2016-present Open Networking Laboratory
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.onosproject.ui;
+
+/**
+ * Defines constants for standard glyph identifiers.
+ * <p>
+ * See also:
+ * <ul>
+ *     <li>
+ *         https://wiki.onosproject.org/display/ONOS/UI+Service+-+GlyphService
+ *     </li>
+ * </ul>
+ */
+public final class GlyphConstants {
+    public static final String BIRD = "bird";
+
+    public static final String UNKNOWN = "m_unknown";
+    public static final String QUERY = "query";
+    public static final String NODE = "node";
+
+    public static final String SWITCH = "m_switch";
+    public static final String ROUTER = "router";
+    public static final String ROADM = "m_roadm";
+    public static final String OTN = "otn";
+    public static final String ROADM_OTN = "roadm_otn";
+    public static final String FIBER_SWITCH = "fiber_switch";
+    public static final String MICROWAVE = "microwave";
+
+    public static final String ENDSTATION = "m_endstation";
+    public static final String BGP_SPEAKER = "bgpSpeaker";
+
+    public static final String CHAIN = "chain";
+    public static final String CROWN = "crown";
+    public static final String LOCK = "lock";
+    public static final String TOPO = "topo";
+    public static final String REFRESH = "refresh";
+    public static final String GARBAGE = "garbage";
+
+    public static final String FLOW_TABLE = "flowTable";
+    public static final String PORT_TABLE = "portTable";
+    public static final String GROUP_TABLE = "groupTable";
+    public static final String METER_TABLE = "meterTable";
+
+    public static final String SUMMARY = "m_summary";
+    public static final String DETAILS = "m_details";
+    public static final String PORTS = "m_ports";
+    public static final String MAP = "m_map";
+    public static final String CYCLE_LABELS = "m_cycleLabels";
+    public static final String OBLIQUE = "m_oblique";
+    public static final String FILTERS = "m_filters";
+    public static final String RESET_ZOOM = "m_resetZoom";
+    public static final String RELATED_INTENTS = "m_relatedIntents";
+    public static final String NEXT = "m_next";
+    public static final String PREV = "m_prev";
+    public static final String INTENT_TRAFFIC = "m_intentTraffic";
+    public static final String ALL_TRAFFIC = "m_allTraffic";
+    public static final String FLOWS = "m_flows";
+    public static final String EQ_MASTER = "m_eqMaster";
+
+    public static final String UI_ATTACHED = "m_uiAttached";
+    public static final String CHECK_MARK = "checkMark";
+    public static final String X_MARK = "m_xMark";
+    public static final String TRIANGLE_UP = "triangleUp";
+    public static final String TRIANGLE_DOWN = "triangleDown";
+    public static final String PLUS = "plus";
+    public static final String MINUS = "minus";
+    public static final String PLAY = "play";
+    public static final String STOP = "stop";
+
+    public static final String CLOUD = "m_cloud";
+
+    // non-instantiable
+    private GlyphConstants() {
+    }
+}

@@ -31,15 +31,14 @@ public final class JsonUtils {
     }
 
     /**
-     * Wraps a message payload into an event structure for the given event
-     * type and sequence ID. Generally, the sequence ID should be a copy of
-     * the ID from the client request event.
+     * Composes a message structure for the given message type and payload.
      *
      * @param type    event type
      * @param sid     sequence ID
      * @param payload event payload
      * @return the object node representation
      */
+    @Deprecated
     public static ObjectNode envelope(String type, long sid, ObjectNode payload) {
         ObjectNode event = MAPPER.createObjectNode();
         event.put("event", type);
@@ -82,6 +81,7 @@ public final class JsonUtils {
      * @param event message event
      * @return extracted sequence identifier
      */
+    @Deprecated
     public static long sid(ObjectNode event) {
         return number(event, "sid");
     }

@@ -32,6 +32,12 @@ public abstract class RequestHandler {
     private UiMessageHandler parent;
 
 
+    /**
+     * Constructs a request handler instance that will handle events
+     * of the specified type.
+     *
+     * @param eventType type of event that will be handled
+     */
     public RequestHandler(String eventType) {
         this.eventType = eventType;
     }
@@ -64,7 +70,7 @@ public abstract class RequestHandler {
     // === Convenience methods...
 
     /**
-     * Returns implementation of the specified service class.
+     * Returns an implementation of the specified service class.
      *
      * @param serviceClass service class
      * @param <T>          type of service
@@ -76,19 +82,20 @@ public abstract class RequestHandler {
     }
 
     /**
-     * Sends a message back to the client.
+     * Sends a message back to the client with the given event type and payload.
      *
      * @param eventType message event type
      * @param sid       message sequence identifier
      * @param payload   message payload
      */
     // TODO: remove sid from signature
+    @Deprecated
     protected void sendMessage(String eventType, long sid, ObjectNode payload) {
         parent.connection().sendMessage(eventType, sid, payload);
     }
 
     /**
-     * Sends a message back to the client.
+     * Sends a message back to the client with the given event type and payload.
      *
      * @param eventType message event type
      * @param payload   message payload
@@ -100,8 +107,8 @@ public abstract class RequestHandler {
 
     /**
      * Sends a message back to the client.
-     * Here, the message is preformatted; the assumption is it has its
-     * eventType, sid and payload attributes already filled in.
+     * Here, the message is preformatted; the assumption is that it has its
+     * eventType and payload attributes already filled in.
      *
      * @param message the message to send
      */
@@ -161,5 +168,4 @@ public abstract class RequestHandler {
     protected boolean bool(ObjectNode node, String key) {
         return JsonUtils.bool(node, key);
     }
-
 }

@@ -27,7 +27,10 @@ import static com.google.common.base.Preconditions.checkArgument;
 import static com.google.common.base.Preconditions.checkNotNull;
 
 /**
- * User interface extension.
+ * Immutable representation of a user interface extension.
+ * <p>
+ * Note that the {@link Builder} class is used to create a user
+ * interface extension instance, and that these instances are immutable.
  */
 public final class UiExtension {
 
@@ -41,7 +44,7 @@ public final class UiExtension {
 
     private final ClassLoader classLoader;
     private final String resourcePath;
-    private final List<UiView> views;
+    private final List<UiView> viewList;
     private final UiMessageHandlerFactory messageHandlerFactory;
     private final UiTopoOverlayFactory topoOverlayFactory;
     private final UiTopoMapFactory topoMapFactory;
@@ -53,12 +56,12 @@ public final class UiExtension {
                         UiMessageHandlerFactory mhFactory,
                         UiTopoOverlayFactory toFactory,
                         UiTopoMapFactory tmFactory) {
-        this.classLoader = cl;
-        this.resourcePath = path;
-        this.views = views;
-        this.messageHandlerFactory = mhFactory;
-        this.topoOverlayFactory = toFactory;
-        this.topoMapFactory = tmFactory;
+        classLoader = cl;
+        resourcePath = path;
+        viewList = views;
+        messageHandlerFactory = mhFactory;
+        topoOverlayFactory = toFactory;
+        topoMapFactory = tmFactory;
     }
 
 
@@ -86,7 +89,7 @@ public final class UiExtension {
      * @return contributed view descriptors
      */
     public List<UiView> views() {
-        return isValid ? views : ImmutableList.of();
+        return isValid ? viewList : ImmutableList.of();
     }
 
     /**
@@ -146,7 +149,7 @@ public final class UiExtension {
         private ClassLoader classLoader;
 
         private String resourcePath = EMPTY;
-        private List<UiView> views = new ArrayList<>();
+        private List<UiView> viewList = new ArrayList<>();
         private UiMessageHandlerFactory messageHandlerFactory = null;
         private UiTopoOverlayFactory topoOverlayFactory = null;
         private UiTopoMapFactory topoMapFactory = null;
@@ -155,7 +158,7 @@ public final class UiExtension {
          * Create a builder with the given class loader.
          * Resource path defaults to "".
          * Views defaults to an empty list.
-         * Both Message and TopoOverlay factories default to null.
+         * MessageHandler, TopoOverlay, and TopoMap factories default to null.
          *
          * @param cl    the class loader
          * @param views list of views contributed by this extension
@@ -163,19 +166,19 @@ public final class UiExtension {
         public Builder(ClassLoader cl, List<UiView> views) {
             checkNotNull(cl, "Must provide a class loader");
             checkArgument(views.size() > 0, "Must provide at least one view");
-            this.classLoader = cl;
-            this.views = views;
+            classLoader = cl;
+            viewList = views;
         }
 
         /**
-         * Set the resource path. That is, path to where the CSS and JS
-         * files are located. This value should
+         * Set the resource path. That is, the path to where the CSS and JS
+         * files are located.
          *
          * @param path resource path
          * @return self, for chaining
          */
         public Builder resourcePath(String path) {
-            this.resourcePath = path == null ? EMPTY : path + SLASH;
+            resourcePath = path == null ? EMPTY : path + SLASH;
             return this;
         }
 
@@ -186,7 +189,7 @@ public final class UiExtension {
          * @return self, for chaining
          */
         public Builder messageHandlerFactory(UiMessageHandlerFactory mhFactory) {
-            this.messageHandlerFactory = mhFactory;
+            messageHandlerFactory = mhFactory;
             return this;
         }
 
@@ -197,7 +200,7 @@ public final class UiExtension {
          * @return self, for chaining
          */
         public Builder topoOverlayFactory(UiTopoOverlayFactory toFactory) {
-            this.topoOverlayFactory = toFactory;
+            topoOverlayFactory = toFactory;
             return this;
         }
 
@@ -208,21 +211,19 @@ public final class UiExtension {
          * @return self, for chaining
          */
         public Builder topoMapFactory(UiTopoMapFactory tmFactory) {
-            this.topoMapFactory = tmFactory;
+            topoMapFactory = tmFactory;
             return this;
         }
 
         /**
-         * Builds the UI extension.
+         * Builds the user interface extension.
          *
          * @return UI extension instance
          */
         public UiExtension build() {
-            return new UiExtension(classLoader, resourcePath, views,
+            return new UiExtension(classLoader, resourcePath, viewList,
                                     messageHandlerFactory, topoOverlayFactory,
                                     topoMapFactory);
         }
-
     }
-
 }

@@ -25,19 +25,19 @@ public interface UiExtensionService {
     /**
      * Registers the specified user interface extension.
      *
-     * @param extension GUI extension to register
+     * @param extension UI extension to register
      */
     void register(UiExtension extension);
 
     /**
      * Unregisters the specified user interface extension.
      *
-     * @param extension GUI extension to unregister
+     * @param extension UI extension to unregister
      */
     void unregister(UiExtension extension);
 
     /**
-     * Returns the list of user interface extensions.
+     * Returns the list of registered user interface extensions.
      *
      * @return list of extensions
      */
@@ -47,7 +47,7 @@ public interface UiExtensionService {
      * Returns the user interface extension that contributed the specified view.
      *
      * @param viewId view identifier
-     * @return user interface extension
+     * @return contributing user interface extension
      */
     UiExtension getViewExtension(String viewId);
 }

@@ -154,16 +154,16 @@ public abstract class UiMessageHandler {
     }
 
     /**
-     * Returns the user interface connection with which this handler was primed.
+     * Returns the service directory with which this handler was primed.
      *
-     * @return user interface connection
+     * @return service directory
      */
     public ServiceDirectory directory() {
         return directory;
     }
 
     /**
-     * Returns implementation of the specified service class.
+     * Returns an implementation of the specified service class.
      *
      * @param serviceClass service class
      * @param <T>          type of service

@@ -23,6 +23,8 @@ import java.util.Set;
 
 /**
  * Service for managing {@link UiTopoLayout} instances.
+ * Those instances are used in conjunction with modeling the region-based
+ * topology views.
  */
 public interface UiTopoLayoutService {
 
@@ -45,7 +47,7 @@ public interface UiTopoLayoutService {
      * Adds a layout to the system or updates an existing one.
      *
      * @param layout the layout to add or update
-     * @return an indication of success
+     * @return true if added; false if updated
      */
     boolean addLayout(UiTopoLayout layout);
 
@@ -87,7 +89,7 @@ public interface UiTopoLayoutService {
      * Removes a layout from the system.
      *
      * @param layout the layout to remove
-     * @return an indication of success
+     * @return true if removed; false if no longer registered
      */
     boolean removeLayout(UiTopoLayout layout);
 

@@ -17,12 +17,13 @@
 package org.onosproject.ui;
 
 /**
- * Represents user interface topology view overlay.
+ * Represents a geographically-based map to be used in the user interface
+ * topology view. Instances of this class are immutable.
  */
 public class UiTopoMap {
 
     private final String id;
-    private final String description;
+    private final String desc;
     private final String filePath;
     private final double scale;
 
@@ -31,13 +32,13 @@ public class UiTopoMap {
      * Creates a new topology map.
      *
      * @param id map identifier
-     * @param description map description
-     * @param filePath map filePath,
-     * @param scale map scale,
+     * @param desc map description
+     * @param filePath map filePath
+     * @param scale map scale
      */
-    public UiTopoMap(String id, String description, String filePath, double scale) {
+    public UiTopoMap(String id, String desc, String filePath, double scale) {
         this.id = id;
-        this.description = description;
+        this.desc = desc;
         this.filePath = filePath;
         this.scale = scale;
     }
@@ -47,8 +48,8 @@ public class UiTopoMap {
      *
      * @return the identifier
      */
-    public String getId() {
-        return this.id;
+    public String id() {
+        return id;
     }
 
     /**
@@ -56,8 +57,8 @@ public class UiTopoMap {
      *
      * @return the description
      */
-    public String getDescription() {
-        return this.description;
+    public String description() {
+        return desc;
     }
 
     /**
@@ -65,8 +66,8 @@ public class UiTopoMap {
      *
      * @return the filePath
      */
-    public String getFilePath() {
-        return this.filePath;
+    public String filePath() {
+        return filePath;
     }
 
     /**
@@ -74,8 +75,7 @@ public class UiTopoMap {
      *
      * @return the scale
      */
-    public double getScale() {
-        return this.scale;
+    public double scale() {
+        return scale;
     }
-
 }

@@ -19,15 +19,15 @@ package org.onosproject.ui;
 import java.util.List;
 
 /**
- * Abstraction of an entity capable of producing one or more topology
- * map topologies.
+ * Abstraction of an entity capable of producing one or more geographic-based
+ * maps for the topology view.
  */
 public interface UiTopoMapFactory {
 
     /**
-     * Produces a list of new maps.
+     * Produces a list of maps to be added to the topology view.
      *
-     * @return list of new maps
+     * @return list of maps
      */
-    List<UiTopoMap> newMaps();
+    List<UiTopoMap> geoMaps();
 }
\ No newline at end of file

@@ -27,6 +27,10 @@ import java.util.Map;
 
 /**
  * Represents user interface topology view overlay.
+ * <p>
+ * This base class does little more than provide a logger and an identifier.
+ * Subclasses will probably want to override some or all of the base methods
+ * to do useful things during the life-cycle of the overlay.
  */
 public class UiTopoOverlay {
 
@@ -40,7 +44,8 @@ public class UiTopoOverlay {
     private boolean isActive = false;
 
     /**
-     * Creates a new user interface topology view overlay descriptor.
+     * Creates a new user interface topology view overlay descriptor, with
+     * the given identifier.
      *
      * @param id overlay identifier
      */
@@ -139,7 +144,7 @@ public class UiTopoOverlay {
      * @param event the link event
      * @return map of additional key/value pairs to be added to the JSON event
      * @deprecated this is a temporary addition for Goldeneye (1.6) release,
-     * and expected to be replaced in the Hummingbird (1.7) release
+     * and expected to be replaced in the Ibis (1.8) release
      */
     @Deprecated
     public Map<String, String> additionalLinkData(LinkEvent event) {

@@ -20,12 +20,12 @@ import com.google.common.base.MoreObjects;
 import java.util.Objects;
 
 /**
- * Represents user interface view addition.
+ * Represents a user interface view addition.
  */
 public class UiView {
 
     /**
-     * Designates navigation menu category.
+     * Designates the navigation menu category.
      */
     public enum Category {
         /**
@@ -57,7 +57,7 @@ public class UiView {
         }
 
         /**
-         * Returns display label for the category.
+         * Returns the display label for the category.
          *
          * @return display label
          */
@@ -87,6 +87,9 @@ public class UiView {
      * Creates a new user interface view descriptor. The navigation item
      * will appear in the navigation menu under the specified category,
      * with the specified icon adornment.
+     * <p>
+     * Note: see the {@code glyphMapping} structure in {@code icon.js} for
+     * valid icon identifiers.
      *
      * @param category view category
      * @param id       view identifier
@@ -112,7 +115,7 @@ public class UiView {
     /**
      * Returns the view identifier.
      *
-     * @return view id
+     * @return view ID
      */
     public String id() {
         return id;
@@ -128,7 +131,7 @@ public class UiView {
     }
 
     /**
-     * Returns the icon ID.
+     * Returns the icon identifier.
      *
      * @return icon ID
      */
@@ -149,7 +152,7 @@ public class UiView {
         if (obj == null || getClass() != obj.getClass()) {
             return false;
         }
-        final UiView other = (UiView) obj;
+        UiView other = (UiView) obj;
         return Objects.equals(this.id, other.id);
     }
 

@@ -18,77 +18,10 @@ package org.onosproject.ui.topo;
 
 /**
  * Defines string constants used in the Topology View of the ONOS GUI.
- * <p>
- * See also:
- * <ul>
- *     <li> https://wiki.onosproject.org/display/ONOS/UI+Service+-+GlyphService </li>
- * </ul>
  */
 public final class TopoConstants {
 
     /**
-     * Defines constants for standard glyph identifiers.
-     */
-    public static final class Glyphs {
-        public static final String BIRD = "bird";
-
-        public static final String UNKNOWN = "m_unknown";
-        public static final String QUERY = "query";
-        public static final String NODE = "node";
-
-        public static final String SWITCH = "m_switch";
-        public static final String ROUTER = "router";
-        public static final String ROADM = "m_roadm";
-        public static final String OTN = "otn";
-        public static final String ROADM_OTN = "roadm_otn";
-        public static final String FIBER_SWITCH = "fiber_switch";
-        public static final String MICROWAVE = "microwave";
-
-        public static final String ENDSTATION = "m_endstation";
-        public static final String BGP_SPEAKER = "bgpSpeaker";
-
-        public static final String CHAIN = "chain";
-        public static final String CROWN = "crown";
-        public static final String LOCK = "lock";
-        public static final String TOPO = "topo";
-        public static final String REFRESH = "refresh";
-        public static final String GARBAGE = "garbage";
-
-        public static final String FLOW_TABLE = "flowTable";
-        public static final String PORT_TABLE = "portTable";
-        public static final String GROUP_TABLE = "groupTable";
-        public static final String METER_TABLE = "meterTable";
-
-        public static final String SUMMARY = "m_summary";
-        public static final String DETAILS = "m_details";
-        public static final String PORTS = "m_ports";
-        public static final String MAP = "m_map";
-        public static final String CYCLE_LABELS = "m_cycleLabels";
-        public static final String OBLIQUE = "m_oblique";
-        public static final String FILTERS = "m_filters";
-        public static final String RESET_ZOOM = "m_resetZoom";
-        public static final String RELATED_INTENTS = "m_relatedIntents";
-        public static final String NEXT = "m_next";
-        public static final String PREV = "m_prev";
-        public static final String INTENT_TRAFFIC = "m_intentTraffic";
-        public static final String ALL_TRAFFIC = "m_allTraffic";
-        public static final String FLOWS = "m_flows";
-        public static final String EQ_MASTER = "m_eqMaster";
-
-        public static final String UI_ATTACHED = "m_uiAttached";
-        public static final String CHECK_MARK = "checkMark";
-        public static final String X_MARK = "m_xMark";
-        public static final String TRIANGLE_UP = "triangleUp";
-        public static final String TRIANGLE_DOWN = "triangleDown";
-        public static final String PLUS = "plus";
-        public static final String MINUS = "minus";
-        public static final String PLAY = "play";
-        public static final String STOP = "stop";
-
-        public static final String CLOUD = "m_cloud";
-    }
-
-    /**
      * Defines constants for property names on the default summary and
      * details panels.
      */
@@ -142,5 +75,4 @@ public final class TopoConstants {
         public static final ButtonId SHOW_METER_VIEW =
                 new ButtonId("showMeterView");
     }
-
 }

@@ -74,14 +74,14 @@ class MapSelectorMessageHandler extends UiMessageHandler {
             UiTopoMapFactory mapFactory = ext.topoMapFactory();
 
             if (mapFactory != null) {
-                List<UiTopoMap> topoMaps = mapFactory.newMaps();
+                List<UiTopoMap> topoMaps = mapFactory.geoMaps();
 
                 topoMaps.forEach(m -> {
-                    maps.set(m.getId(), objectNode().put(MAP_ID, m.getId())
-                            .put(DESCRIPTION, m.getDescription())
-                            .put(FILE_PATH, m.getFilePath())
-                            .put(SCALE, m.getScale()));
-                    order.add(m.getId());
+                    maps.set(m.id(), objectNode().put(MAP_ID, m.id())
+                            .put(DESCRIPTION, m.description())
+                            .put(FILE_PATH, m.filePath())
+                            .put(SCALE, m.scale()));
+                    order.add(m.id());
                 });
             }
         });

@@ -23,6 +23,7 @@ import org.onlab.osgi.ServiceDirectory;
 import org.onlab.osgi.ServiceNotFoundException;
 import org.onosproject.cluster.ClusterService;
 import org.onosproject.cluster.ControllerNode;
+import org.onosproject.ui.GlyphConstants;
 import org.onosproject.ui.UiConnection;
 import org.onosproject.ui.UiExtensionService;
 import org.onosproject.ui.UiMessageHandler;
@@ -32,7 +33,6 @@ import org.onosproject.ui.UiTopoOverlayFactory;
 import org.onosproject.ui.impl.topo.UiTopoSession;
 import org.onosproject.ui.impl.topo.model.UiSharedTopologyModel;
 import org.onosproject.ui.model.topo.UiTopoLayout;
-import org.onosproject.ui.topo.TopoConstants;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -293,7 +293,7 @@ public class UiWebSocket
             ObjectNode instance = mapper.createObjectNode()
                     .put(ID, node.id().toString())
                     .put(IP, node.ip().toString())
-                    .put(TopoConstants.Glyphs.UI_ATTACHED,
+                    .put(GlyphConstants.UI_ATTACHED,
                             node.equals(service.getLocalNode()));
             instances.add(instance);
         }