Copied files
diff --git a/lib/plugin.dart b/lib/plugin.dart new file mode 100644 index 0000000..019acd2 --- /dev/null +++ b/lib/plugin.dart
@@ -0,0 +1,130 @@ +// Copyright (c) 2015, 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. + +library plugin; + +/** + * A function used to register the given [extension] to the extension point with + * the given unique [identifier]. + * + * An [ExtensionError] will be thrown if the [extension] is not appropriate + * for the extension point, such as an [extension] that does not implement the + * required interface. + */ +typedef void RegisterExtension(String identifier, Object extension); + +/** + * A function used to register an extension point with the given simple + * [identifier]. If given, the [validator] will be used to validate extensions + * to the extension point. + * + * An [ExtensionError] will be thrown if the extension point cannot be + * registered, such as when a plugin attempts to define two extension points + * with the same simple identifier. + */ +typedef ExtensionPoint RegisterExtensionPoint(String identifier, + [ValidateExtension validateExtension]); + +/** + * A function used by a plugin to validate an [extension] to a extension point. + * + * An [ExtensionError] should be thrown if the [extension] is not valid for the + * extension point, such as an [extension] that does not implement the required + * interface. + */ +typedef void ValidateExtension(Object extension); + +/** + * An exception indicating that an error occurred while attempting to register + * either an extension or an extension point. + * + * Clients are not expected to subtype this class. + */ +class ExtensionError implements Exception { + /** + * The message describing the error that occurred. + */ + final String message; + + /** + * Initialize a newly created error to have the given message. + */ + ExtensionError(this.message); +} + +/** + * A representation of an extension point. + * + * Clients are not expected to subtype this class. + */ +abstract class ExtensionPoint { + /** + * Return an immutable list containing all of the extensions that were + * registered for this extension point. + */ + List<Object> get extensions; + + /** + * Return the plugin that defined this extension point. + */ + Plugin get plugin; + + /** + * Return the identifier used to uniquely identify this extension point within + * the defining plugin. + */ + String get simpleIdentifier; + + /** + * Return the identifier used to uniquely identify this extension point. The + * unique identifier is the identifier for the plugin, followed by a period + * (`.`), followed by the [simpleIdentifier] for the extension point. + */ + String get uniqueIdentifier; +} + +/** + * A contribution to the analysis server that can extend the behavior of the + * server while also allowing other plugins to extend it's behavior. + * + * Clients are expected to subtype this class when implementing plugins. + */ +abstract class Plugin { + /** + * Return the identifier used to uniquely identify this plugin. + */ + String get uniqueIdentifier; + + /** + * Use the [register] function to register all of the extension points + * contributed by this plugin. + * + * Clients should not invoke the [register] function after this method has + * returned. + */ + void registerExtensionPoints(RegisterExtensionPoint register); + + /** + * Use the [register] function to register all of the extensions contributed + * by this plugin. + * + * Clients should not invoke the [register] function after this method has + * returned. + */ + void registerExtensions(RegisterExtension register); + + /** + * Return a unique identifier created from the unique identifier from the + * [plugin] and the [simpleIdentifier]. + */ + static String buildUniqueIdentifier(Plugin plugin, String simpleIdentifier) => + join(plugin.uniqueIdentifier, simpleIdentifier); + + /** + * Return an identifier created by joining the [pluginIdentifier] and the + * [simpleIdentifier]. + */ + static String join(String pluginIdentifier, String simpleIdentifier) => + '$pluginIdentifier.$simpleIdentifier'; +}
diff --git a/lib/src/plugin_impl.dart b/lib/src/plugin_impl.dart new file mode 100644 index 0000000..70a76e5 --- /dev/null +++ b/lib/src/plugin_impl.dart
@@ -0,0 +1,125 @@ +// Copyright (c) 2015, 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. + +library plugin.src.plugin_impl; + +import 'dart:collection'; + +import 'package:plugin/plugin.dart'; + +/** + * An object that manages the extension points for a single instance of the + * analysis server. + */ +class ExtensionManager { + /** + * A table mapping the id's of extension points to the corresponding + * extension points. + */ + Map<String, ExtensionPointImpl> extensionPoints = + new HashMap<String, ExtensionPointImpl>(); + + /** + * Process each of the given [plugins] by allowing them to register extension + * points and extensions. + * + * An [ExtensionError] will be thrown if any of the plugins throws such an + * exception while registering with this manager. + */ + void processPlugins(List<Plugin> plugins) { + for (Plugin plugin in plugins) { + plugin.registerExtensionPoints((String identifier, + [ValidateExtension validateExtension]) => + registerExtensionPoint(plugin, identifier, validateExtension)); + } + for (Plugin plugin in plugins) { + plugin.registerExtensions(registerExtension); + } + } + + /** + * Register an [extension] to the extension point with the given unique + * [identifier]. + */ + void registerExtension(String identifier, Object extension) { + ExtensionPointImpl extensionPoint = extensionPoints[identifier]; + if (extensionPoint == null) { + throw new ExtensionError( + 'There is no extension point with the id "$identifier"'); + } + extensionPoint.add(extension); + } + + /** + * Register an extension point being defined by the given [plugin] with the + * given simple [identifier] and [validateExtension]. + */ + ExtensionPoint registerExtensionPoint( + Plugin plugin, String identifier, ValidateExtension validateExtension) { + String uniqueIdentifier = Plugin.buildUniqueIdentifier(plugin, identifier); + if (extensionPoints.containsKey(uniqueIdentifier)) { + throw new ExtensionError( + 'There is already an extension point with the id "$identifier"'); + } + ExtensionPointImpl extensionPoint = + new ExtensionPointImpl(plugin, identifier, validateExtension); + extensionPoints[uniqueIdentifier] = extensionPoint; + return extensionPoint; + } +} + +/** + * A concrete representation of an extension point. + */ +class ExtensionPointImpl implements ExtensionPoint { + @override + final Plugin plugin; + + @override + final String simpleIdentifier; + + /** + * The function used to validate extensions to this extension point. + */ + final ValidateExtension validateExtension; + + /** + * The list of extensions to this extension point. + */ + final List<Object> _extensions = <Object>[]; + + /** + * Initialize a newly create extension point to belong to the given [plugin] + * and have the given [simpleIdentifier]. If [validateExtension] is non-`null` + * it will be used to validate extensions associated with this extension + * point. + */ + ExtensionPointImpl( + this.plugin, this.simpleIdentifier, this.validateExtension); + + /** + * Return a list containing all of the extensions that have been registered + * for this extension point. + */ + List<Object> get extensions => new UnmodifiableListView(_extensions); + + /** + * Return the identifier used to uniquely identify this extension point. The + * unique identifier is the identifier for the plugin, followed by a period + * (`.`), followed by the [simpleIdentifier] for the extension point. + */ + String get uniqueIdentifier => + Plugin.buildUniqueIdentifier(plugin, simpleIdentifier); + + /** + * Validate that the given [extension] is appropriate for this extension + * point, and if it is then add it to the list of registered exceptions. + */ + void add(Object extension) { + if (validateExtension != null) { + validateExtension(extension); + } + _extensions.add(extension); + } +}
diff --git a/test/plugin_impl_test.dart b/test/plugin_impl_test.dart new file mode 100644 index 0000000..d28ebb0 --- /dev/null +++ b/test/plugin_impl_test.dart
@@ -0,0 +1,174 @@ +// Copyright (c) 2015, 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. + +library test.operation; + +import 'package:plugin/plugin.dart'; +import 'package:plugin/src/plugin_impl.dart'; +import 'package:unittest/unittest.dart'; + +main() { + groupSep = ' | '; + + group('ExtensionManager', () { + test('processPlugins', () { + TestPlugin plugin1 = new TestPlugin('plugin1'); + TestPlugin plugin2 = new TestPlugin('plugin1'); + ExtensionManager manager = new ExtensionManager(); + manager.processPlugins([plugin1, plugin2]); + expect(plugin1.extensionPointsRegistered, true); + expect(plugin1.extensionsRegistered, true); + expect(plugin2.extensionPointsRegistered, true); + expect(plugin2.extensionsRegistered, true); + }); + + test('registerExtension - valid', () { + Plugin plugin = new TestPlugin('plugin'); + ExtensionManager manager = new ExtensionManager(); + ExtensionPoint point = + manager.registerExtensionPoint(plugin, 'point', null); + expect(point, isNotNull); + Object extension = 'extension'; + manager.registerExtension('plugin.point', extension); + List<Object> extensions = point.extensions; + expect(extensions, isNotNull); + expect(extensions, hasLength(1)); + expect(extensions[0], extension); + }); + + test('registerExtension - non existent', () { + ExtensionManager manager = new ExtensionManager(); + expect(() => manager.registerExtension('does not exist', 'extension'), + throwsA(new isInstanceOf<ExtensionError>())); + ; + }); + + test('registerExtensionPoint - non-conflicting', () { + Plugin plugin1 = new TestPlugin('plugin1'); + Plugin plugin2 = new TestPlugin('plugin2'); + ExtensionManager manager = new ExtensionManager(); + expect( + manager.registerExtensionPoint(plugin1, 'point1', null), isNotNull); + expect( + manager.registerExtensionPoint(plugin1, 'point2', null), isNotNull); + expect( + manager.registerExtensionPoint(plugin2, 'point1', null), isNotNull); + expect( + manager.registerExtensionPoint(plugin2, 'point2', null), isNotNull); + }); + + test('registerExtensionPoint - conflicting - same plugin', () { + Plugin plugin1 = new TestPlugin('plugin1'); + ExtensionManager manager = new ExtensionManager(); + expect( + manager.registerExtensionPoint(plugin1, 'point1', null), isNotNull); + expect(() => manager.registerExtensionPoint(plugin1, 'point1', null), + throwsA(new isInstanceOf<ExtensionError>())); + }); + + test('registerExtensionPoint - conflicting - different plugins', () { + Plugin plugin1 = new TestPlugin('plugin1'); + Plugin plugin2 = new TestPlugin('plugin1'); + ExtensionManager manager = new ExtensionManager(); + expect( + manager.registerExtensionPoint(plugin1, 'point1', null), isNotNull); + expect(() => manager.registerExtensionPoint(plugin2, 'point1', null), + throwsA(new isInstanceOf<ExtensionError>())); + }); + }); + + group('ExtensionPointImpl', () { + test('extensions - empty', () { + Plugin plugin = new TestPlugin('plugin'); + ExtensionPointImpl point = new ExtensionPointImpl(plugin, 'point', null); + List<Object> extensions = point.extensions; + expect(extensions, isNotNull); + expect(extensions, isEmpty); + }); + + test('uniqueIdentifier', () { + Plugin plugin = new TestPlugin('plugin'); + ExtensionPointImpl point = new ExtensionPointImpl(plugin, 'point', null); + expect(point.uniqueIdentifier, 'plugin.point'); + }); + + test('add - single', () { + Plugin plugin = new TestPlugin('plugin'); + ExtensionPointImpl point = new ExtensionPointImpl(plugin, 'point', null); + Object extension = 'extension'; + point.add(extension); + List<Object> extensions = point.extensions; + expect(extensions, isNotNull); + expect(extensions, hasLength(1)); + expect(extensions[0], extension); + }); + + test('add - multiple', () { + Plugin plugin = new TestPlugin('plugin'); + ExtensionPointImpl point = new ExtensionPointImpl(plugin, 'point', null); + point.add('extension 1'); + point.add('extension 2'); + point.add('extension 3'); + List<Object> extensions = point.extensions; + expect(extensions, isNotNull); + expect(extensions, hasLength(3)); + }); + + test('add - with validator - valid', () { + Plugin plugin = new TestPlugin('plugin'); + ExtensionPointImpl point = new ExtensionPointImpl(plugin, 'point', + (Object extension) { + if (extension is! String) { + throw new ExtensionError(''); + } + }); + point.add('extension'); + }); + + test('add - with validator - invalid', () { + Plugin plugin = new TestPlugin('plugin'); + ExtensionPointImpl point = new ExtensionPointImpl(plugin, 'point', + (Object extension) { + if (extension is! String) { + throw new ExtensionError(''); + } + }); + expect(() => point.add(1), throwsA(new isInstanceOf<ExtensionError>())); + }); + }); +} + +/** + * A simple plugin that can be used by tests. + */ +class TestPlugin extends Plugin { + /** + * A flag indicating whether the method [registerExtensionPoints] has been + * invoked. + */ + bool extensionPointsRegistered = false; + + /** + * A flag indicating whether the method [registerExtensions] has been invoked. + */ + bool extensionsRegistered = false; + + @override + String uniqueIdentifier; + + /** + * Initialize a newly created plugin to have the given identifier. + */ + TestPlugin(this.uniqueIdentifier); + + @override + void registerExtensionPoints(RegisterExtensionPoint register) { + extensionPointsRegistered = true; + } + + @override + void registerExtensions(RegisterExtension register) { + extensionsRegistered = true; + } +}