Add minimal support for sending notifications

pkg/analyzer_plugin/lib/plugin/plugin.dart

Index: pkg/analyzer_plugin/lib/plugin/plugin.dart
diff --git a/pkg/analyzer_plugin/lib/plugin/plugin.dart b/pkg/analyzer_plugin/lib/plugin/plugin.dart
index 5179732ddcb50f0f62652a43686f39e0ab5561c6..496eb49809a54d9cbd334ff244082180a251ddae 100644
--- a/pkg/analyzer_plugin/lib/plugin/plugin.dart
+++ b/pkg/analyzer_plugin/lib/plugin/plugin.dart
@@ -4,6 +4,7 @@
 
 import 'dart:async';
 
+import 'package:analyzer/dart/analysis/results.dart';
 import 'package:analyzer/file_system/file_system.dart';
 import 'package:analyzer/file_system/physical_file_system.dart';
 import 'package:analyzer/src/dart/analysis/byte_store.dart';
@@ -427,13 +428,95 @@ abstract class ServerPlugin {
   void onError(Object exception, StackTrace stackTrace) {}
 
   /**
-   * Send notifications corresponding to the given description of subscriptions.
-   * The map is keyed by the path of each file for which notifications should be
-   * sent and has values representing the list of services associated with the
-   * notifications to send.
+   * If the plugin provides folding information, send a folding notification
+   * for the file with the given [path] to the server.
+   *
+   * If a [result] is provided then it is expected to be the result of analyzing
+   * the file at the given [path].
+   */
+  Future<Null> sendFoldingNotification(String path, {ResolveResult result}) {
+    return new Future.value();
+  }
+
+  /**
+   * If the plugin provides highlighting information, send a highlights
+   * notification for the file with the given [path] to the server.
+   *
+   * If a [result] is provided then it is expected to be the result of analyzing
+   * the file at the given [path].
+   */
+  Future<Null> sendHighlightsNotification(String path, {ResolveResult result}) {

[scheglov, 2017/08/22 17:55:27]

I think `result` must be a required parameter in all specific
sendXxxNotification() methods. If we have to pull this result, we will do it
once, in the enclosing `sendNotificationsForFile` invocation.

I guess also that computing notification is synchronous, so we might not need
asynchrony here.

[Brian Wilkerson, 2017/08/22 18:33:15]

For performance reasons? In spite of the fact that we're caching results for
priority files?
If it's a required parameter in `sendXxxNotification` methods, then I'd make it
a required parameter in `sendNotificationsForFile`. The place where we'd have to
get a result is in `sendNotificationsForSubscriptions`, and we don't currently
have a way to get results, so we'd either need to add a `getAnalysisResults`
method or leave it an abstract method.
If we never need to compute results, that should be true.

[scheglov, 2017/08/22 18:49:21]

Well, you're probably right.
It's OK with me to keep these "result" parameters optional.
We will pull only when user switches between editor tabs, so we get new
subscriptions.
This should be rare enough, so it does not matter.
And for "push" from AnalysisDriver.results we will work efficiently.

And in theory plugins could optimize some notifications by using something other
than full ResolveResult. Although given that the most useful notifications are
navigation and semantic highlighting, and they require full analysis, if we
cannot provide them quickly, we have a problem and must fix it anyway.
Never mind, keep it async :-)

[Brian Wilkerson, 2017/08/23 14:06:43]

But we need to keep them?

If I've understood Mike correctly, we would need to change all of the signatures
to something like

Future<Null> sendHighlightsNotification(String path, {Object result});

because the angular plugin need to pass a DirectivesResult rather than a
ResolveResult and Object is the only common supertype.

If it were efficient enough that each sendXxxNotification method could create
its own result (and I think we decided that it *is* or they couldn't be
optional) then we could get rid of the optional parameter.

Obviously, I like it better with the parameter because it seems wasteful to
re-access data we could already have, but I don't like the idea of declaring it
to be of type Object.

The other option (that Mike mentioned) is to make it be of type 'R', where R is
a type parameter for the class. We could define a convenience class for "normal"
plugin developers:

abstract class DartServerPlugin extends ServerPlugin<ResolveResult> {}

but I'm concerned about the number of type parameters we'd need in order to make
everything as flexible as it might need to be. That said, I kind of like this
better than using Object, but removing the argument seems even cleaner.

+    return new Future.value();
+  }
+
+  /**
+   * If the plugin provides navigation information, send a navigation
+   * notification for the file with the given [path] to the server.
+   *
+   * If a [result] is provided then it is expected to be the result of analyzing
+   * the file at the given [path].
+   */
+  Future<Null> sendNavigationNotification(String path, {ResolveResult result}) {
+    return new Future.value();
+  }
+
+  /**
+   * Send notifications for the services subscribed to for the file with the
+   * given [path].
+   *
+   * If a [result] is provided then it is expected to be the result of analyzing
+   * the file at the given [path].
+   *
+   * This is a convenience method that subclasses can use to send notifications
+   * after analysis has been performed on a file.
+   */
+  void sendNotificationsForFile(String path, {ResolveResult result}) {
+    for (AnalysisService service in subscriptionManager.servicesForFile(path)) {
+      _sendNotificationForFile(path, service, result: result);
+    }
+  }
+
+  /**
+   * Send notifications corresponding to the given description of
+   * [subscriptions]. The map is keyed by the path of each file for which
+   * notifications should be sent and has values representing the list of
+   * services associated with the notifications to send.
+   *
+   * This method is used when the set of subscribed notifications has been
+   * changed and notifications need to be sent even when the specified files
+   * have already been analyzed.
    */
   void sendNotificationsForSubscriptions(
-      Map<String, List<AnalysisService>> subscriptions);
+      Map<String, List<AnalysisService>> subscriptions) {
+    subscriptions.forEach((String path, List<AnalysisService> services) {
+      for (AnalysisService service in services) {
+        _sendNotificationForFile(path, service);
+      }
+    });
+  }
+
+  /**
+   * If the plugin provides occurrences information, send an occurrences
+   * notification for the file with the given [path] to the server.
+   *
+   * If a [result] is provided then it is expected to be the result of analyzing
+   * the file at the given [path].
+   */
+  Future<Null> sendOccurrencesNotification(String path,
+      {ResolveResult result}) {
+    return new Future.value();
+  }
+
+  /**
+   * If the plugin provides outline information, send an outline notification
+   * for the file with the given [path] to the server.
+   *
+   * If a [result] is provided then it is expected to be the result of analyzing
+   * the file at the given [path].
+   */
+  Future<Null> sendOutlineNotification(String path, {ResolveResult result}) {
+    return new Future.value();
+  }
 
   /**
    * Start this plugin by listening to the given communication [channel].
@@ -562,4 +645,32 @@ abstract class ServerPlugin {
       _channel.sendResponse(response);
     }
   }
+
+  /**
+   * Send a notification for the file at the given [path] corresponding to the
+   * given [service].
+   *
+   * If a [result] is provided then it is expected to be the result of analyzing
+   * the file at the given [path].
+   */
+  void _sendNotificationForFile(String path, AnalysisService service,
+      {ResolveResult result}) {
+    switch (service) {
+      case AnalysisService.FOLDING:
+        sendFoldingNotification(path, result: result);
+        break;
+      case AnalysisService.HIGHLIGHTS:
+        sendHighlightsNotification(path, result: result);
+        break;
+      case AnalysisService.NAVIGATION:
+        sendNavigationNotification(path, result: result);
+        break;
+      case AnalysisService.OCCURRENCES:
+        sendOccurrencesNotification(path, result: result);
+        break;
+      case AnalysisService.OUTLINE:
+        sendOutlineNotification(path, result: result);
+        break;
+    }
+  }
 }