Class AdbKeepOpenConnection
An Adb "KeepOpen" database connection that allows a connection to stay open across multiple workers. It is similar to a DbConnection, including creating database commands, with extra information and functionality. It is created by an AdbKeepOpenConnectionBuilder instance.
The key feature of "KeepOpen" connections is that they keep the underlying .NET
DbConnection open even after a worker calls Close()
and Dispose(). This allows using a single transaction or specific temporary table(s)
across multiple workers, which can be very useful. When this functionality
is not needed, a standard AdbConnection should be used instead.
Note: This connection must be disposed after use. This will however not close the underlying .NET connection - that only happens when the AdbKeepOpenConnectionBuilder instance that created this connection is disposed. See Disposing Disposables for details.
Note that typically this class is not used directly, instead IAdbConnection is used, and then only when implementing Adb workers (as opposed to using pre-existing ones).
Inherited Members
Namespace: actionETL.Adb
Assembly: actionETL.dll
Syntax
public sealed class AdbKeepOpenConnection : AdbConnection, IAdbConnection, IDisposableRemarks
Note that the AdbKeepOpenConnection instance is not thread-safe, and the library user must ensure
that it is only used in a single place (in a single worker) at any one time.
When instantiating these workers, this simply requires the parent to do it serially as per normal,
i.e. not in multiple threads, or in multiple parents that might run concurrently.
When these workers run, this is normally ensured by using start constraints and by grouping workers appropriately.
Also note that all workers in a dataflow can run in parallel, making them unsuitable for use with
AdbKeepOpenConnection, unless:
- It doesn't collide with any non-dataflow workers, and
- Only one of the dataflow workers use the connection, or the use of fully blocking workers ensures that only one dataflow worker (using this connection) at a time will be running
The connection can be opened and closed multiple times as needed, and it must
be disposed after use. Disposal should almost always be done by whoever created the
connection, typically via
DisposeOnFinished<TDisposable>(TDisposable)
or UsingActionWorker<TDisposable> if used across multiple method calls,
or by a using statement if created and disposed in a single method and thread, without
being passed to any other workers.
See Disposing Disposables for details.
After the connection instance has been disposed (potentially multiple times across multiple workers), the AdbKeepOpenConnectionBuilder instance that created it must also be disposed (by whoever had created it), which is when the underlying .NET connection will be closed and disposed.
Do design database workers to take AdbConnectionString,
IAdbConnectionBuilder, and AdbCommandBuilder instances as parameters, which allows
them to support connections with different AdbConnectionMode. Conversely,
avoid passing AdbConnection, AdbKeepOpenConnection, AdbCommand,
or connection (text) strings to workers.
Methods
Close()
No-op. The underlying .NET connection is only closed and disposed when the AdbKeepOpenConnectionBuilder instance that created it is disposed.
Declaration
public override void Close()Overrides
Dispose(Boolean)
No-op. This AdbKeepOpenConnection instance is instead disposed by disposing the
AdbKeepOpenConnectionBuilder instance that created it.
Declaration
protected override void Dispose(bool disposing)Parameters
| Type | Name | Description |
|---|---|---|
| Boolean | disposing | Ignored. |
Overrides
Open()
Opens the connection if it's closed, otherwise does nothing.
Declaration
public override void Open()Overrides
Exceptions
| Type | Condition |
|---|---|
| Exception | (See the provider documentation for specific exceptions.) |
OpenAsync()
Opens the connection asynchronously if the provider supports it, otherwise it calls Open()
and returns a completed task.
Any exceptions thrown by Open() will be communicated via the returned task Exception
property. Do not invoke other methods and properties of the connection object until the returned task is
complete.
Declaration
public override Task OpenAsync()Returns
| Type | Description |
|---|---|
| Task | A task representing the asynchronous operation. The task will contain any exceptions raised (see the provider documentation for specific exceptions). |
Overrides
OpenAsync(CancellationToken)
Opens the connection asynchronously if the provider supports it, otherwise it calls Open()
and returns a completed task (or a canceled task if cancellationToken is canceled).
Any exceptions thrown by Open() will be communicated via the returned task Exception
property. Do not invoke other methods and properties of the connection object until the returned task is
complete.
Declaration
public override Task OpenAsync(CancellationToken cancellationToken)Parameters
| Type | Name | Description |
|---|---|---|
| CancellationToken | cancellationToken | The cancellation token. |
Returns
| Type | Description |
|---|---|
| Task | A task representing the asynchronous operation. The task will contain any exceptions raised (see the provider documentation for specific exceptions). |