Interface DataConnection
-
- All Known Implementing Classes:
DataConnectionBase
,HazelcastDataConnection
,KafkaDataConnection
,MongoDataConnection
public interface DataConnection
DataConnection is a reference to a single external system.It contains metadata needed to connect, and might or might not maintain a physical connection or connections, depending on the connector. The connection might be an instance of
Connection
, or of a driver or client to a 3rd party system etc.Every connection obtained from a DataConnection must be closed. Otherwise, the data link cannot be closed and the connection will leak.
DataConnection is supposed to be used in Jet jobs or SQL mappings where the same connection metadata, or even the same connection is to be reused.
DataConnection is closely related to Jet connectors (sources and sinks) and to
SqlConnector
s. While the DataConnection handles initialization, maintenance and closing of connections to the external system, the connections read and write actual data from/into them.Instances of DataConnections should be obtained by calling
DataConnectionService.getAndRetainDataConnection(java.lang.String, java.lang.Class<T>)
method.Conceptually, there are 3 types of sharing of the underlying instance between multiple (concurrent) Jet jobs or SQL queries:
- Single-use - the instance is created each time it is requested, it is destroyed after closing. It can be used by a single processor (thread) at a time and after use it cannot be re-used.
- Pooled - the instance is obtained from a pool and it is returned to the pool after closing. It can be used by a single processor (thread) at a time, but it is reused when the processor no longer needs it.
- Shared - the instance may be shared by multiple threads, hence it must be thread-safe, and it is only closed when the data connection is closed.
When a DataConnection is closed, connections obtained from should continue to be functional, until all connections are returned. Replacing of a DataConnection is handled as remove+create.
Implementations of DataConnection must provide a constructor with a single argument of type
DataConnectionConfig
. The constructor must not throw an exception under any circumstances. Any resource allocation should be done either asynchronously or lazily when the underlying instance is requested.- Since:
- 5.3
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description void
destroy()
Called by the member when shutting down.DataConnectionConfig
getConfig()
Returns the configuration of this DataConnection.java.lang.String
getName()
Returns the name of this data connection as specified in theDataConnectionConfig
or theCREATE DATA CONNECTION
command.java.util.Collection<DataConnectionResource>
listResources()
Returns list ofDataConnectionResource
s accessible via this DataConnection.default java.util.Map<java.lang.String,java.lang.String>
options()
Returns the properties / options this DataConnection was created with.void
release()
Release a retained data connection.java.util.Collection<java.lang.String>
resourceTypes()
Returns the list of possible values forDataConnectionResource.type()
, that will be returned whenlistResources()
is called.void
retain()
Prevents the data connection from being closed.
-
-
-
Method Detail
-
getName
@Nonnull java.lang.String getName()
Returns the name of this data connection as specified in theDataConnectionConfig
or theCREATE DATA CONNECTION
command.- Returns:
- the name of this DataConnection
-
listResources
@Nonnull java.util.Collection<DataConnectionResource> listResources()
Returns list ofDataConnectionResource
s accessible via this DataConnection.It is not strictly required that the data connection lists all resources; a resource can be used even if it is not listed. For example, the list of resources in Oracle database might not include tables available through a database link. In fact, it might list no resources at all, perhaps if the security in the target system prevents reading of such a list.
The returned list contains up-to-date list of resources. Any changes (added or removed resources) must be reflected in subsequent calls to this method.
-
resourceTypes
@Nonnull java.util.Collection<java.lang.String> resourceTypes()
Returns the list of possible values forDataConnectionResource.type()
, that will be returned whenlistResources()
is called. Returned values are case-insensitive, e.g.DataConnectionResource.type()
may returnMY_RES
and this methodmy_res
.
-
getConfig
@Nonnull DataConnectionConfig getConfig()
Returns the configuration of this DataConnection.
-
options
@Nonnull default java.util.Map<java.lang.String,java.lang.String> options()
Returns the properties / options this DataConnection was created with.
-
retain
void retain()
Prevents the data connection from being closed. It is useful when the processor wants to avoid the data connection from being closed while it is obtaining connections from it. Multiple threads can retain the same DataConnection concurrently.Note that the DataConnection also isn't closed until all shared connections obtained from it are returned. This feature, together with the lock allows the processor to avoid concurrent close while it is using the connection.
- Throws:
java.lang.IllegalStateException
- fi the data connection is already closed
-
release
void release()
Release a retained data connection. Must be called after everyretain()
call, otherwise the data connection will leak.
-
destroy
void destroy()
Called by the member when shutting down. Should unconditionally close all connections and release resources.
-
-