Package com.hazelcast.dataconnection

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 released via release(). Otherwise, the data connection cannot be closed and the connection will leak.

DataConnection is supposed to be used in Jet jobs, SQL mappings and other places 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 SqlConnectors. 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.
However, the connector might implement any other appropriate strategy.

When a DataConnection is released, connections obtained from it 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 Details

    • getName

      @Nonnull String getName()
      Returns the name of this data connection as specified in the DataConnectionConfig or the CREATE DATA CONNECTION command.
      Returns:
      the name of this DataConnection

    • listResources

      @Nonnull Collection<DataConnectionResource> listResources()
      Returns list of DataConnectionResources 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 Collection<String> resourceTypes()
      Returns the list of possible values for DataConnectionResource.type(), that will be returned when listResources() is called. Returned values are case-insensitive, e.g. DataConnectionResource.type() may return MY_RES and this method my_res.

    • getConfig

      @Nonnull DataConnectionConfig getConfig()
      Returns the configuration of this DataConnection.

    • options

      @Nonnull default Map<String,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:
      IllegalStateException - if the data connection is already closed

    • release

      void release()
      Release a retained data connection. Must be called after every retain() 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.