Skip to content

Reviewed docs/development-guide/LoadablePlugins.md for grammar/simplifications #44

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 11, 2022
Merged

Reviewed docs/development-guide/LoadablePlugins.md for grammar/simplifications #44

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 18 additions & 22 deletions docs/development-guide/LoadablePlugins.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

@davecramer davecramer Aug 12, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this may need more verbiage to explain what is really happening here.


## 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`.
Expand All @@ -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)
Expand All @@ -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<String> getSubscribedMethods()` method.
The `Set<String> getSubscribedMethods()` method specifies a set of JDBC methods a plugin is subscribed to. All plugins must implement the `Set<String> 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`
Expand All @@ -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.
Expand All @@ -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<Connection, SQLException> connectFunc`, `JdbcCallable<T, E> 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<Connection, SQLException> connectFunc`, `JdbcCallable<T, E> 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:

Expand Down