com.hazelcast.datalink

Interface DataLink

All Known Implementing Classes:

DataLinkBase, HazelcastDataLink, JdbcDataLink, KafkaDataLink, MongoDataLink

@Beta
public interface DataLink

DataLink 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 DataLink must be closed. Otherwise, the data link cannot be closed and the connection will leak.

DataLink 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.

DataLink is closely related to Jet connectors (sources and sinks) and to SqlConnectors. While the DataLink handles initialization, maintenance and closing of connections to the external system, the connections read and write actual data from/into them.

Instances of DataLinks should be obtained by calling DataLinkService.getAndRetainDataLink(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 link is closed.

However, the connector might implement any other appropriate strategy.

When a DataLink is closed, connections obtained from should continue to be functional, until all connections are returned. Replacing of a DataLink is handled as remove+create.

Implementations of DataLink must provide a constructor with a single argument of type DataLinkConfig.

Since:

5.3

Method Summary

Modifier and Type	Method and Description
void	destroy() Called by the member when shutting down.
DataLinkConfig	getConfig() Returns the configuration of this DataLink.
String	getName() Returns the name of this DataLink as specified in the DataLinkConfig or the CREATE DATA LINK command.
Collection<DataLinkResource>	listResources() Returns list of DataLinkResources accessible via this DataLink.
default Map<String,String>	options() Returns the properties / options this DataLink was created with.
void	release() Release a retained data link.
void	retain() Prevents the data link from being closed.

Method Detail

getName

@Nonnull
String getName()

Returns the name of this DataLink as specified in the DataLinkConfig or the CREATE DATA LINK command.

Returns:

the name of this DataLink

listResources

@Nonnull
Collection<DataLinkResource> listResources()

Returns list of DataLinkResources accessible via this DataLink.

It is not strictly required that the data link 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.

getConfig

@Nonnull
DataLinkConfig getConfig()

Returns the configuration of this DataLink.

options

@Nonnull
default Map<String,String> options()

Returns the properties / options this DataLink was created with.

retain

void retain()

Prevents the data link from being closed. It is useful when the processor wants to avoid the data link from being closed while it is obtaining connections from it. Multiple threads can retain the same DataLink concurrently.

Note that the DataLink 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 - fi the data link is already closed

release

void release()

Release a retained data link. Must be called after every retain() call, otherwise the data link will leak.

destroy

void destroy()

Called by the member when shutting down. Should unconditionally close all connections and release resources.