| // 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; | |
| import 'package:plugin/src/plugin_impl.dart'; | |
| /** | |
| * 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 the given [extensionPoint]. | |
| * | |
| * 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 identifier. | |
| */ | |
| typedef void RegisterExtensionPoint(ExtensionPoint extensionPoint); | |
| /** | |
| * 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 may not extend, implement or mix-in 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 may not extend, implement or mix-in this class. | |
| */ | |
| abstract class ExtensionPoint<E> { | |
| /** | |
| * Initialize a newly created extension point to be defined by the given | |
| * [plugin] with the given [simpleIdentifier]. The [validateExtension] | |
| * function will be used to validate extensions for this extension point. | |
| */ | |
| factory ExtensionPoint(Plugin plugin, String simpleIdentifier, | |
| ValidateExtension validateExtension) = ExtensionPointImpl<E>; | |
| /** | |
| * Return an immutable list containing all of the extensions that were | |
| * registered for this extension point. | |
| */ | |
| List<E> 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 host application that can extend the behavior of the | |
| * application while also allowing other plugins to extend it's behavior. | |
| * | |
| * Clients may implement 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'; | |
| } |