GUI -- Beginnings of structure for topology Overlay API.

- Re-implemented RequestSummary / ShowSummary in Alt implementation.

Change-Id: Idb86c7bf3ede8f8815abcb488bbf9b0a7041ef79

@@ -56,6 +56,7 @@ public abstract class RequestHandler {
      * @param sid message sequence identifier
      * @param payload request message payload
      */
+    // TODO: remove sid from signature
     public abstract void process(long sid, ObjectNode payload);
 
 

@@ -18,6 +18,8 @@ package org.onosproject.ui;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.node.ObjectNode;
 import org.onlab.osgi.ServiceDirectory;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
 import java.util.Collection;
 import java.util.Collections;
@@ -46,6 +48,7 @@ import static com.google.common.base.Preconditions.checkNotNull;
  */
 public abstract class UiMessageHandler {
 
+    private final Logger log = LoggerFactory.getLogger(getClass());
     private final Map<String, RequestHandler> handlerMap = new HashMap<>();
 
     private UiConnection connection;
@@ -56,7 +59,6 @@ public abstract class UiMessageHandler {
      */
     protected final ObjectMapper mapper = new ObjectMapper();
 
-
     /**
      * Subclasses must return the collection of handlers for the
      * message types they handle.
@@ -82,6 +84,7 @@ public abstract class UiMessageHandler {
      */
     public void process(ObjectNode message) {
         String type = JsonUtils.eventType(message);
+        // TODO: remove sid
         long sid = JsonUtils.sid(message);
         ObjectNode payload = JsonUtils.payload(message);
         exec(type, sid, payload);
@@ -94,9 +97,11 @@ public abstract class UiMessageHandler {
      * @param sid       sequence identifier
      * @param payload   message payload
      */
+    // TODO: remove sid from signature
     void exec(String eventType, long sid, ObjectNode payload) {
         RequestHandler handler = handlerMap.get(eventType);
         if (handler != null) {
+            log.debug("process {} event...", eventType);
             handler.process(sid, payload);
         }
     }

@@ -19,29 +19,40 @@ package org.onosproject.ui.impl;
 
 import com.fasterxml.jackson.databind.node.ObjectNode;
 import com.google.common.collect.ImmutableSet;
+import com.google.common.collect.Maps;
 import org.onlab.osgi.ServiceDirectory;
 import org.onosproject.core.CoreService;
+import org.onosproject.ui.JsonUtils;
 import org.onosproject.ui.RequestHandler;
 import org.onosproject.ui.UiConnection;
 import org.onosproject.ui.UiMessageHandler;
+import org.onosproject.ui.impl.topo.OverlayService;
+import org.onosproject.ui.impl.topo.SummaryData;
 import org.onosproject.ui.impl.topo.TopoUiEvent;
 import org.onosproject.ui.impl.topo.TopoUiListener;
 import org.onosproject.ui.impl.topo.TopoUiModelService;
+import org.onosproject.ui.impl.topo.overlay.AbstractSummaryGenerator;
+import org.onosproject.ui.impl.topo.overlay.SummaryGenerator;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 import java.util.Collection;
+import java.util.HashMap;
+import java.util.Map;
 
 import static com.google.common.base.Preconditions.checkNotNull;
+import static org.onosproject.ui.impl.topo.TopoUiEvent.Type.SUMMARY_UPDATE;
 
 /**
  * Facility for handling inbound messages from the topology view, and
  * generating outbound messages for the same.
  */
-public class AltTopoViewMessageHandler extends UiMessageHandler {
+public class AltTopoViewMessageHandler extends UiMessageHandler
+            implements OverlayService {
 
     private static final String TOPO_START = "topoStart";
     private static final String TOPO_STOP = "topoStop";
+    private static final String REQ_SUMMARY = "requestSummary";
 
     private final Logger log = LoggerFactory.getLogger(getClass());
 
@@ -50,6 +61,9 @@ public class AltTopoViewMessageHandler extends UiMessageHandler {
 
     private TopoUiListener modelListener;
     private String version;
+    private SummaryGenerator defaultSummaryGenerator;
+    private SummaryGenerator currentSummaryGenerator;
+
 
     private boolean topoActive = false;
 
@@ -58,9 +72,12 @@ public class AltTopoViewMessageHandler extends UiMessageHandler {
         super.init(connection, directory);
         this.directory = checkNotNull(directory, "Directory cannot be null");
         modelService = directory.get(TopoUiModelService.class);
+        defaultSummaryGenerator = new DefSummaryGenerator("node", "ONOS Summary");
 
+        bindEventHandlers();
         modelListener = new ModelListener();
         version = getVersion();
+        currentSummaryGenerator = defaultSummaryGenerator;
     }
 
 
@@ -74,11 +91,33 @@ public class AltTopoViewMessageHandler extends UiMessageHandler {
     protected Collection<RequestHandler> getHandlers() {
         return ImmutableSet.of(
                 new TopoStart(),
-                new TopoStop()
+                new TopoStop(),
+                new ReqSummary()
+                // TODO: add more handlers here.....
         );
     }
 
     // =====================================================================
+    // Overlay Service
+    // TODO: figure out how we are going to switch overlays in and out...
+
+    private final Map<String, SummaryGenerator> summGenCache = Maps.newHashMap();
+
+    @Override
+    public void addSummaryGenerator(String overlayId, SummaryGenerator generator) {
+        log.info("Adding custom Summary Generator for overlay [{}]", overlayId);
+        summGenCache.put(overlayId, generator);
+    }
+
+    @Override
+    public void removeSummaryGenerator(String overlayId) {
+        summGenCache.remove(overlayId);
+        log.info("Custom Summary Generator for overlay [{}] removed", overlayId);
+    }
+
+
+
+    // =====================================================================
     // Request Handlers for (topo view) events from the UI...
 
     private final class TopoStart extends RequestHandler {
@@ -91,7 +130,6 @@ public class AltTopoViewMessageHandler extends UiMessageHandler {
             topoActive = true;
             modelService.addListener(modelListener);
             sendMessages(modelService.getInitialState());
-            log.debug(TOPO_START);
         }
     }
 
@@ -104,7 +142,43 @@ public class AltTopoViewMessageHandler extends UiMessageHandler {
         public void process(long sid, ObjectNode payload) {
             topoActive = false;
             modelService.removeListener(modelListener);
-            log.debug(TOPO_STOP);
+        }
+    }
+
+    private final class ReqSummary extends RequestHandler {
+        private ReqSummary() {
+            super(REQ_SUMMARY);
+        }
+
+        @Override
+        public void process(long sid, ObjectNode payload) {
+            modelService.startSummaryMonitoring();
+            // NOTE: showSummary messages forwarded through the model listener
+        }
+    }
+
+    // =====================================================================
+
+    private final class DefSummaryGenerator extends AbstractSummaryGenerator {
+        public DefSummaryGenerator(String iconId, String title) {
+            super(iconId, title);
+        }
+
+        @Override
+        public ObjectNode generateSummary() {
+            SummaryData data = modelService.getSummaryData();
+            iconId("node");
+            title("ONOS Summary");
+            clearProps();
+            prop("Devices", format(data.deviceCount()));
+            prop("Links", format(data.linkCount()));
+            prop("Hosts", format(data.hostCount()));
+            prop("Topology SCCs", format(data.clusterCount()));
+            separator();
+            prop("Intents", format(data.intentCount()));
+            prop("Flows", format(data.flowRuleCount()));
+            prop("Version", version);
+            return buildObjectNode();
         }
     }
 
@@ -120,6 +194,15 @@ public class AltTopoViewMessageHandler extends UiMessageHandler {
         }
     }
 
+    private void sendMessages(ObjectNode message) {
+        if (topoActive) {
+            UiConnection connection = connection();
+            if (connection != null) {
+                connection.sendMessage(message);
+            }
+        }
+    }
+
     // =====================================================================
     // Our listener for model events so we can push changes out to the UI...
 
@@ -127,7 +210,46 @@ public class AltTopoViewMessageHandler extends UiMessageHandler {
         @Override
         public void event(TopoUiEvent event) {
             log.debug("Handle Event: {}", event);
-            // TODO: handle event
+            ModelEventHandler handler = eventHandlerBinding.get(event.type());
+
+            // any handlers not bound explicitly are assumed to be pass-thru...
+            if (handler == null) {
+                handler = passThruHandler;
+            }
+            handler.handleEvent(event);
+        }
+    }
+
+
+    // =====================================================================
+    // Model Event Handler definitions and bindings...
+
+    private interface ModelEventHandler {
+        void handleEvent(TopoUiEvent event);
+    }
+
+    private ModelEventHandler passThruHandler = event -> {
+        // simply forward the event message as is
+        ObjectNode message = event.subject();
+        if (message != null) {
+            sendMessages(event.subject());
         }
+    };
+
+    private ModelEventHandler summaryHandler = event -> {
+        // use the currently selected summary generator to create the body..
+        ObjectNode payload = currentSummaryGenerator.generateSummary();
+        sendMessages(JsonUtils.envelope("showSummary", payload));
+    };
+
+
+    // TopoUiEvent type binding of handlers
+    private final Map<TopoUiEvent.Type, ModelEventHandler>
+            eventHandlerBinding = new HashMap<>();
+
+    private void bindEventHandlers() {
+        eventHandlerBinding.put(SUMMARY_UPDATE, summaryHandler);
+        // NOTE: no need to bind pass-thru handlers
     }
+
 }

@@ -194,6 +194,7 @@ public class TopologyViewMessageHandler extends TopologyViewMessageHandlerBase {
 
     // ==================================================================
 
+    @Deprecated
     private final class TopoStart extends RequestHandler {
         private TopoStart() {
             super(TOPO_START);
@@ -209,6 +210,7 @@ public class TopologyViewMessageHandler extends TopologyViewMessageHandlerBase {
         }
     }
 
+    @Deprecated
     private final class TopoStop extends RequestHandler {
         private TopoStop() {
             super(TOPO_STOP);
@@ -221,6 +223,7 @@ public class TopologyViewMessageHandler extends TopologyViewMessageHandlerBase {
         }
     }
 
+    @Deprecated
     private final class ReqSummary extends RequestHandler {
         private ReqSummary() {
             super(REQ_SUMMARY);

@@ -29,6 +29,8 @@ import org.onosproject.ui.UiExtensionService;
 import org.onosproject.ui.UiMessageHandlerFactory;
 import org.onosproject.ui.UiView;
 import org.onosproject.ui.UiViewHidden;
+import org.onosproject.ui.impl.topo.OverlayService;
+import org.onosproject.ui.impl.topo.overlay.SummaryGenerator;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -46,7 +48,8 @@ import static org.onosproject.ui.UiView.Category.PLATFORM;
  */
 @Component(immediate = true)
 @Service
-public class UiExtensionManager implements UiExtensionService, SpriteService {
+public class UiExtensionManager
+        implements UiExtensionService, SpriteService, OverlayService {
 
     private final Logger log = LoggerFactory.getLogger(getClass());
 
@@ -59,9 +62,13 @@ public class UiExtensionManager implements UiExtensionService, SpriteService {
     // Core views & core extension
     private final UiExtension core = createCoreExtension();
 
+    // Topology Message Handler
+    private final AltTopoViewMessageHandler topoHandler =
+            new AltTopoViewMessageHandler();
+
 
     // Creates core UI extension
-    private static UiExtension createCoreExtension() {
+    private UiExtension createCoreExtension() {
         List<UiView> coreViews = of(
                 new UiView(PLATFORM, "app", "Applications", "nav_apps"),
                 new UiView(PLATFORM, "cluster", "Cluster Nodes", "nav_cluster"),
@@ -78,7 +85,7 @@ public class UiExtensionManager implements UiExtensionService, SpriteService {
         UiMessageHandlerFactory messageHandlerFactory =
                 () -> ImmutableList.of(
                         new TopologyViewMessageHandler(),
-//                        new AltTopoViewMessageHandler(),
+//                        topoHandler,
                         new DeviceViewMessageHandler(),
                         new LinkViewMessageHandler(),
                         new HostViewMessageHandler(),
@@ -119,7 +126,8 @@ public class UiExtensionManager implements UiExtensionService, SpriteService {
     @Override
     public synchronized void unregister(UiExtension extension) {
         extensions.remove(extension);
-        extension.views().stream().map(UiView::id).collect(toSet()).forEach(views::remove);
+        extension.views().stream()
+                .map(UiView::id).collect(toSet()).forEach(views::remove);
     }
 
     @Override
@@ -132,9 +140,10 @@ public class UiExtensionManager implements UiExtensionService, SpriteService {
         return views.get(viewId);
     }
 
-
+    // =====================================================================
     // Provisional tracking of sprite definitions
-    private Map<String, JsonNode> sprites = Maps.newHashMap();
+
+    private final Map<String, JsonNode> sprites = Maps.newHashMap();
 
     @Override
     public Set<String> getNames() {
@@ -152,4 +161,18 @@ public class UiExtensionManager implements UiExtensionService, SpriteService {
         return sprites.get(name);
     }
 
+
+    // =====================================================================
+    // Topology Overlay API -- pass through to topology message handler
+
+    // NOTE: while WIP, comment out calls to topoHandler (for checked in code)
+    @Override
+    public void addSummaryGenerator(String overlayId, SummaryGenerator generator) {
+        topoHandler.addSummaryGenerator(overlayId, generator);
+    }
+
+    @Override
+    public void removeSummaryGenerator(String overlayId) {
+        topoHandler.removeSummaryGenerator(overlayId);
+    }
 }

+/*
+ * Copyright 2015 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.impl.topo;
+
+import org.onosproject.ui.impl.topo.overlay.SummaryGenerator;
+
+/**
+ * Provides the API for external agents to inject topology overlay behavior.
+ */
+public interface OverlayService {
+
+    /**
+     * Registers a custom summary generator for the specified overlay.
+     *
+     * @param overlayId overlay identifier
+     * @param generator generator to register
+     */
+    void addSummaryGenerator(String overlayId, SummaryGenerator generator);
+
+    /**
+     * Unregisters the generator associated with the specified overlay.
+     *
+     * @param overlayId overlay identifier
+     */
+    void removeSummaryGenerator(String overlayId);
+}

+/*
+ * Copyright 2015 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.impl.topo;
+
+/**
+ * Provides basic summary data for the topology.
+ */
+public interface SummaryData {
+
+    /**
+     * Returns the number of devices.
+     *
+     * @return number of devices
+     */
+    int deviceCount();
+
+    /**
+     * Returns the number of links.
+     *
+     * @return number of links
+     */
+    int linkCount();
+
+    /**
+     * Returns the number of hosts.
+     *
+     * @return number of hosts
+     */
+    int hostCount();
+
+    /**
+     * Returns the number of clusters (topology SCCs).
+     *
+     * @return number of clusters
+     */
+    int clusterCount();
+
+    /**
+     * Returns the number of intents in the system.
+     *
+     * @return number of intents
+     */
+    long intentCount();
+
+    /**
+     * Returns the number of flow rules in the system.
+     *
+     * @return number of flow rules
+     */
+    int flowRuleCount();
+
+}

@@ -29,6 +29,10 @@ public class TopoUiEvent extends AbstractEvent<TopoUiEvent.Type, ObjectNode> {
      * Type of Topology UI Model events.
      */
     public enum Type {
+        // notification events
+        SUMMARY_UPDATE,
+
+        // unsolicited topology events
         INSTANCE_ADDED,
         INSTANCE_REMOVED,
         DEVICE_ADDED,

@@ -35,10 +35,14 @@ import org.onosproject.net.Host;
 import org.onosproject.net.Link;
 import org.onosproject.net.device.DeviceEvent;
 import org.onosproject.net.device.DeviceService;
+import org.onosproject.net.flow.FlowRuleService;
 import org.onosproject.net.host.HostEvent;
 import org.onosproject.net.host.HostService;
+import org.onosproject.net.intent.IntentService;
 import org.onosproject.net.link.LinkEvent;
 import org.onosproject.net.link.LinkService;
+import org.onosproject.net.topology.Topology;
+import org.onosproject.net.topology.TopologyService;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -51,6 +55,7 @@ import static org.onosproject.cluster.ClusterEvent.Type.INSTANCE_ADDED;
 import static org.onosproject.net.device.DeviceEvent.Type.DEVICE_ADDED;
 import static org.onosproject.net.host.HostEvent.Type.HOST_ADDED;
 import static org.onosproject.net.link.LinkEvent.Type.LINK_ADDED;
+import static org.onosproject.ui.impl.topo.TopoUiEvent.Type.SUMMARY_UPDATE;
 
 
 /**
@@ -79,6 +84,14 @@ public class TopoUiModelManager implements TopoUiModelService {
     @Reference(cardinality = ReferenceCardinality.MANDATORY_UNARY)
     protected MastershipService mastershipService;
 
+    @Reference(cardinality = ReferenceCardinality.MANDATORY_UNARY)
+    protected IntentService intentService;
+
+    @Reference(cardinality = ReferenceCardinality.MANDATORY_UNARY)
+    protected FlowRuleService flowRuleService;
+
+    @Reference(cardinality = ReferenceCardinality.MANDATORY_UNARY)
+    protected TopologyService topologyService;
 
 
     @Reference(cardinality = ReferenceCardinality.MANDATORY_UNARY)
@@ -103,6 +116,7 @@ public class TopoUiModelManager implements TopoUiModelService {
                 linkService,
                 hostService,
                 mastershipService
+                // TODO: others??
         );
         log.info("Started");
     }
@@ -113,6 +127,17 @@ public class TopoUiModelManager implements TopoUiModelService {
         log.info("Stopped");
     }
 
+
+    // TODO: figure out how to cull zombie listeners
+    // The problem is when one refreshes the GUI (topology view)
+    //  a new instance of AltTopoViewMessageHandler is created and added
+    //  as a listener, but we never got a TopoStop event, which is what
+    //  causes the listener (for an AltTopoViewMessageHandler instance) to
+    //  be removed.
+    // ==== Somehow need to tie this in to the GUI-disconnected event.
+
+
+
     @Override
     public void addListener(TopoUiListener listener) {
         listenerRegistry.addListener(listener);
@@ -133,6 +158,60 @@ public class TopoUiModelManager implements TopoUiModelService {
         return results;
     }
 
+    @Override
+    public void startSummaryMonitoring() {
+        // TODO: set up periodic monitoring task
+        // send a summary now, and periodically...
+        post(new TopoUiEvent(SUMMARY_UPDATE, null));
+    }
+
+    @Override
+    public void stopSummaryMonitoring() {
+        // TODO: cancel monitoring task
+
+    }
+
+    @Override
+    public SummaryData getSummaryData() {
+        return new SummaryDataImpl();
+    }
+
+    // =====================================================================
+
+    private final class SummaryDataImpl implements SummaryData {
+        private final Topology topology = topologyService.currentTopology();
+
+        @Override
+        public int deviceCount() {
+            return topology.deviceCount();
+        }
+
+        @Override
+        public int linkCount() {
+            return topology.linkCount();
+        }
+
+        @Override
+        public int hostCount() {
+            return hostService.getHostCount();
+        }
+
+        @Override
+        public int clusterCount() {
+            return topology.clusterCount();
+        }
+
+        @Override
+        public long intentCount() {
+            return intentService.getIntentCount();
+        }
+
+        @Override
+        public int flowRuleCount() {
+            return flowRuleService.getFlowRuleCount();
+        }
+    }
+
     // =====================================================================
 
     private static final Comparator<? super ControllerNode> NODE_COMPARATOR =

@@ -47,8 +47,27 @@ public interface TopoUiModelService {
      * These will be in the form of "addInstance", "addDevice", "addLink",
      * and "addHost" events, as appropriate.
      *
-     * @return initial state events
+     * @return initial state messages
      */
     List<ObjectNode> getInitialState();
 
+    /**
+     * Starts the summary monitoring process.
+     * <p>
+     * Sends a "showSummary" message now, and schedules a task to send
+     * updates whenever the data changes.
+     */
+    void startSummaryMonitoring();
+
+    /**
+     * Cancels the task that sends summary updates.
+     */
+    void stopSummaryMonitoring();
+
+    /**
+     * Returns base data about the topology.
+     *
+     * @return summary data
+     */
+    SummaryData getSummaryData();
 }

+/*
+ * Copyright 2015 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.impl.topo.overlay;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ArrayNode;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+
+import java.text.DecimalFormat;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Base implementation of a {@link SummaryGenerator}. Provides convenience
+ * methods for compiling a list of properties to be displayed in the summary
+ * panel on the UI.
+ */
+public abstract class AbstractSummaryGenerator implements SummaryGenerator {
+    private static final String NUMBER_FORMAT = "#,###";
+    private static final DecimalFormat DF = new DecimalFormat(NUMBER_FORMAT);
+    private static final ObjectMapper MAPPER = new ObjectMapper();
+
+    private final List<Prop> props = new ArrayList<>();
+    private String iconId;
+    private String title;
+
+    /**
+     * Constructs a summary generator without specifying the icon ID or title.
+     * It is expected that the title (and optionally the icon ID) will be set
+     * later via {@link #title(String)} (and {@link #iconId(String)}), before
+     * {@link #buildObjectNode()} is invoked to generate the message payload.
+     */
+    public AbstractSummaryGenerator() {
+    }
+
+    /**
+     * Constructs a summary generator that uses the specified iconId ID and
+     * title in its generated output.
+     *
+     * @param iconId iconId ID
+     * @param title title
+     */
+    public AbstractSummaryGenerator(String iconId, String title) {
+        this.iconId = iconId;
+        this.title = title;
+    }
+
+    /**
+     * Subclasses need to provide an implementation.
+     *
+     * @return the summary payload
+     */
+    @Override
+    public abstract ObjectNode generateSummary();
+
+    /**
+     * Formats the given number into a string, using comma separator.
+     *
+     * @param number the number
+     * @return formatted as a string
+     */
+    protected String format(Number number) {
+        return DF.format(number);
+    }
+
+    /**
+     * Sets the iconId ID to use.
+     *
+     * @param iconId iconId ID
+     */
+    protected void iconId(String iconId) {
+        this.iconId = iconId;
+    }
+
+    /**
+     * Sets the summary panel title.
+     *
+     * @param title the title
+     */
+    protected void title(String title) {
+        this.title = title;
+    }
+
+    /**
+     * Clears out the cache of properties.
+     */
+    protected void clearProps() {
+        props.clear();
+    }
+
+    /**
+     * Adds a property to the summary. Note that the value is converted to
+     * a string by invoking the <code>toString()</code> method on it.
+     *
+     * @param label the label
+     * @param value the value
+     */
+    protected void prop(String label, Object value) {
+        props.add(new Prop(label, value));
+    }
+
+    /**
+     * Adds a separator to the summary; when rendered on the client, a visible
+     * break between properties.
+     */
+    protected void separator() {
+        props.add(new Prop("-", ""));
+    }
+
+    /**
+     * Builds an object node from the current state of the summary generator.
+     *
+     * @return summary payload as JSON object node
+     */
+    protected ObjectNode buildObjectNode() {
+        ObjectNode result = MAPPER.createObjectNode();
+        // NOTE: "id" and "type" are currently used for title and iconID
+        //  so that this structure can be "re-used" with detail panel payloads
+        result.put("id", title).put("type", iconId);
+
+        ObjectNode pnode = MAPPER.createObjectNode();
+        ArrayNode porder = MAPPER.createArrayNode();
+
+        for (Prop p : props) {
+            porder.add(p.label);
+            pnode.put(p.label, p.value);
+        }
+        result.set("propOrder", porder);
+        result.set("props", pnode);
+
+        return result;
+    }
+
+    // ===================================================================
+
+    /**
+     * Abstraction of a property, that is, a label-value pair.
+     */
+    private static class Prop {
+        private final String label;
+        private final String value;
+
+        public Prop(String label, Object value) {
+            this.label = label;
+            this.value = value.toString();
+        }
+    }
+}

+/*
+ * Copyright 2015 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.impl.topo.overlay;
+
+import com.fasterxml.jackson.databind.node.ObjectNode;
+
+/**
+ * May be called upon to generate the summary messages for the topology view
+ * in the GUI.
+ * <p>
+ * It is assumed that if a custom summary generator is installed on the server
+ * (as part of a topology overlay), a peer custom summary message handler will
+ * be installed on the client side to handle the messages thus generated.
+ */
+public interface SummaryGenerator {
+    /**
+     * Generates the payload for the "showSummary" message.
+     *
+     * @return the message payload
+     */
+    ObjectNode generateSummary();
+}