Add minimal support for sending notifications

pkg/analyzer_plugin/lib/plugin/plugin.dart

 // Copyright (c) 2017, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 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';
 import 'package:analyzer/src/dart/analysis/driver.dart'
     show AnalysisDriverGeneric, AnalysisDriverScheduler;
 import 'package:analyzer/src/dart/analysis/file_byte_store.dart';
 import 'package:analyzer/src/dart/analysis/file_state.dart';
 import 'package:analyzer/src/dart/analysis/performance_logger.dart';
 import 'package:analyzer/src/generated/sdk.dart';
 import 'package:analyzer_plugin/channel/channel.dart';
@@ skipping 403 matching lines @@
    */
   void onDone() {}
 
   /**
    * The method that is called when an error has occurred in the analysis
    * server. This method will not be invoked under normal conditions.
    */
   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].
    */
   void start(PluginCommunicationChannel channel) {
     _channel = channel;
     _channel.listen(_onRequest, onError: onError, onDone: onDone);
   }
 
   /**
@@ skipping 108 matching lines @@
     } catch (exception, stackTrace) {
       response = new Response(id, requestTime,
           error: new RequestError(
               RequestErrorCode.PLUGIN_ERROR, exception.toString(),
               stackTrace: stackTrace.toString()));
     }
     if (response != null) {
       _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;
+    }
+  }
 }