diff --git a/docs/development-guide/LoadablePlugins.md b/docs/development-guide/LoadablePlugins.md index d1a6631df..d9d8ba5d7 100644 --- a/docs/development-guide/LoadablePlugins.md +++ b/docs/development-guide/LoadablePlugins.md @@ -9,15 +9,15 @@ Plugins let users: - measure execution time - and more -The JDBC Wrapper has several built-in plugins as listed [here](../using-the-jdbc-wrapper/UsingTheJdbcWrapper.md#list-of-available-plugins). +The JDBC Wrapper has several built-in plugins; you can [see the list here](../using-the-jdbc-wrapper/UsingTheJdbcWrapper.md#list-of-available-plugins). ## Available Services -The plugins are notified by the connection plugin manager when changes in database occur and utilize the [plugin service](./PluginService.md) to establish connections and retrieve host information. +Plugins are notified by the connection plugin manager when changes to the database connection occur, and utilize the [plugin service](./PluginService.md) to establish connections and retrieve host information. ## Using Custom Plugins -There are 3 steps to use a custom plugin: +To use a custom plugin, you must: 1. Create a custom plugin. 2. Register the custom plugin to a wrapper profile. 3. Specify the custom plugin to use in `wrapperProfileName`. @@ -26,10 +26,10 @@ There are 3 steps to use a custom plugin: There are two ways to create a custom plugin: - implement the [ConnectionPlugin](../../wrapper/src/main/java/com/amazon/awslabs/jdbc/ConnectionPlugin.java) interface directly, or -- extend the [AbstractConnectionPlugin](../../wrapper/src/main/java/com/amazon/awslabs/jdbc/plugin/AbstractConnectionPlugin.java) class +- extend the [AbstractConnectionPlugin](../../wrapper/src/main/java/com/amazon/awslabs/jdbc/plugin/AbstractConnectionPlugin.java) class. The `AbstractConnectionPlugin` class provides a simple implementation for all the methods in `ConnectionPlugin`, -as it calls the provided JDBC method without additional operations. This is helpful when the custom plugin only needs to override one or a few methods from the `ConnectionPlugin` interface. +as it calls the provided JDBC method without additional operations. This is helpful when the custom plugin only needs to override one (or a few) methods from the `ConnectionPlugin` interface. See the following classes for examples: - [IamAuthConnectionPlugin](../../wrapper/src/main/java/com/amazon/awslabs/jdbc/plugin/IamAuthConnectionPlugin.java) @@ -39,19 +39,15 @@ See the following classes for examples: - [ExecutionTimeConnectionPlugin](../../wrapper/src/main/java/com/amazon/awslabs/jdbc/plugin/ExecutionTimeConnectionPlugin.java) - The `ExecutionTimeConnectionPlugin` only overrides the `execute` method because it is only concerned with elapsed time during execution, it does not establish new connections or set up any host list provider. -A `ConnectionPluginFactory` implementation is also required for the new custom plugin. This factory class is used to register and initialize custom plugins. -See [AuroraHostListConnectionPluginFactory](../../wrapper/src/main/java/com/amazon/awslabs/jdbc/plugin/AuroraHostListConnectionPluginFactory.java) for a simple implementation example. +A `ConnectionPluginFactory` implementation is also required for the new custom plugin. This factory class is used to register and initialize custom plugins. See [AuroraHostListConnectionPluginFactory](../../wrapper/src/main/java/com/amazon/awslabs/jdbc/plugin/AuroraHostListConnectionPluginFactory.java) for a simple implementation example. ### Subscribed Methods -All plugins must implement the `Set getSubscribedMethods()` method. +The `Set getSubscribedMethods()` method specifies a set of JDBC methods a plugin is subscribed to. All plugins must implement the `Set getSubscribedMethods()` method. -This method specifies a set of JDBC methods the plugin is subscribed to. +When executing a JDBC method, the plugin manager will only call a specific plugin method if the JDBC method is within its set of subscribed methods. For example, [LogQueryConnectionPlugin](../../wrapper/src/main/java/com/amazon/awslabs/jdbc/plugin/LogQueryConnectionPlugin.java) only subscribes to JDBC methods related to query execution, such as `Statement.execute`. This plugin will not be triggered by method calls like `Connection.isValid`. -When executing a JDBC method, the plugin manager will only call a specific plugin method if the JDBC method is within its set of subscribed methods. -For instance, [LogQueryConnectionPlugin](../../wrapper/src/main/java/com/amazon/awslabs/jdbc/plugin/LogQueryConnectionPlugin.java) only subscribes to JDBC methods related to query execution, such as `Statement.execute`. This plugin will not be triggered by method calls like `Connection.isValid`. - -Plugins can subscribe to any of the JDBC API methods as listed [here](https://docs.oracle.com/javase/8/docs/api/java/sql/package-summary.html), some examples are as follows: +Plugins can subscribe to any of the JDBC API methods listed [here](https://docs.oracle.com/javase/8/docs/api/java/sql/package-summary.html); some examples are as follows: - `Statement.executeQuery` - `PreparedStatement.executeQuery` @@ -64,8 +60,8 @@ Plugins can also subscribe to the [host list provider pipeline](./Pipelines.md#h ### Tips on Creating a Custom Plugin -The custom plugin can subscribe to all JDBC methods being executed, which means it may be active in every workflow. -It is recommended to be conscious of the performance impact of subscribing and performing demanding tasks for every JDBC method. +A custom plugin can subscribe to all JDBC methods being executed, which means it may be active in every workflow. +We recommend that you be aware of the performance impact of subscribing and performing demanding tasks for every JDBC method. ### Register the Custom Plugin The `DriverConfigurationProfiles` manages the plugin profiles. @@ -80,15 +76,15 @@ DriverConfigurationProfiles.addOrReplaceProfile("foo", Collections.singletonList When creating custom plugins, it is important to **avoid** the following bad practices in your plugin implementation: -1. keeping local copies of shared information +1. Keeping local copies of shared information: - information like current connection, or the host list provider are shared across all plugins - shared information may be updated by any plugin at any time and should be retrieved via the plugin service when required -2. using driver-specific properties or objects - - the JDBC Wrapper may be used with multiple drivers, therefore plugins must ensure its implementation is not restricted to a specific driver -3. making direct connections - - the plugins should always call the pipeline lambdas (i.e. `JdbcCallable connectFunc`, `JdbcCallable jdbcMethodFunc`) -4. running long tasks synchronously - - the JDBC method calls are executed by all subscribed plugins synchronously, if one plugin runs a long task during the execution it blocks the execution for the other plugins +2. Using driver-specific properties or objects: + - the JDBC Wrapper may be used with multiple drivers, therefore plugins must ensure implementation is not restricted to a specific driver +3. Making direct connections: + - the plugin should always call the pipeline lambdas (i.e. `JdbcCallable connectFunc`, `JdbcCallable jdbcMethodFunc`) +4. Running long tasks synchronously: + - the JDBC method calls are executed by all subscribed plugins synchronously; if one plugin runs a long task during the execution it blocks the execution for the other plugins See the following examples for more details: