ID	IEP-126
Author	Maksim Timonin
Sponsor
Created	10.09.2024
Status	DRAFT

Motivation

When processing data, users want to have access to non-tabular (not stored in cache structures) data. Example of such data is application attributes - an associative array specified on an application side. Usage scenarios:

To run certain logic that depends on the value of the attribute (for example, the application language [2], progress monitoring [4]).
To audit changes in the database (for example, CacheInterceptor extracts the user from the attributes and saves it along with data).
To optimize the transfer of parameters to processing functions (for example, multiple QuerySqlFunction use the same parameter and it is convenient to take it from the attributes, rather than transfer it separately to each function).

Another examples of non-tabular data that can be accessed are SecuritySubject, UserAttributes and current Transaction.

The requirements include:

Attributes must be accessible from user defined functions (QuerySqlFunction, CacheInterceptor).
Setting attributes via protocols: thin client, jdbc:thin.
Attribute values can change during the life of the connection (a connection from a connection pool can be sequentially used by different applications).

Ignite does not have a similar public API:

ServiceCallContext helps solve similar problems, but has several limitations. The main one is that it is only available in calls via the IgniteService API and cannot be used for single operations or transactions.
UserAttributes - allows to set user attributes, but the attribute values are fixed for the entire lifetime of the connection.
ClientListenerConnectionContext - it's available only on single node, which accepts connection from a client.

A similar context mechanism exists in Oracle [1] and it's widely used.

Description

Accessing attributes

ApplicationContext is an entrypoint for accessing all non-tabular data.
Access requires static methods, because objects injection isn't possible for user functions (QuerySqlFunction are static, CacheInterceptor is a singleton for cache).

/** ApplicationContext interface. It's an entrypoint for all non-tabular information. */
public class ApplicationContext {
    /** @return Application attributes set for current thread. */
    public static @Nullable Map<String, String> getAttributes();
 }
 
/** Example, use it in QuerySqlFunction. */
public static class UserDefinedFunctions {
    /** @return Session ID, application attribute. */
    @QuerySqlFunction
    public static String sessionId() {
        Map<String, String> appAttrs = ApplicationContext.getAttributes();
 
        return appAttrs == null ? null : appAttr.get(SESSION_ID);
    }
}

Setting attributes

Ignite

Ignite doesn't have support an abstraction "session". It also doesn't restrict usage on Ignite instance from multiple threads by different applications. Also the same thread can be shared between multiple applications.
The application attributes might be used in SQL, Cache API. The ApplicationContext should not depend on the used API.
Then minimal unit of interaction between application and Ignite is a transaction. I suggest to attach the attributes to a transaction.

// Extends the interface with new public method.
public interface IgniteTransactions {
 	...

    /** @param appAttrs Application attributes. */
    public IgniteTransactions withApplicationAttributes(Map<String, String> appAttrs);
}

// Example of usage.
try (Ignite ign = Ignition.localIgnite()) {
     Map<String, String> appAttrs = F.asMap("SESSION_ID", "1234");
 
     try (Transaction tx = ign.transactions().withApplicationAttributes(appAttrs).txStart()) { 
        ...
    }
}

IgniteClient (Java)

Client should mirror the logic of Ignite node.
New feature is needed in the ClientBitmaskFeature protocol.

// Extends the interface with new public method.
public interface ClientTransactions {
	...

    /** @param appAttrs Application attributes. */
    public ClientTransactions withApplicationAttributes(Map<String, String> appAttrs);
}

// Example of usage.
try (IgniteClient cln = Ignition.startClient(clnCfg)) {
    Map<String, String> appAttrs = F.asMap("SESSION_ID", "1234");

    try (ClientTransaction tx = cln.transactions().withApplicationAttributes(appAttrs).txStart()) {
        ...
    }
}

JDBC

The standard jdbc protocol describes the methods Connection#setClientInfo, which allow changing the values of client attributes during the life of the connection [3]. Implementation features:

The list of attributes that can be set using #setClientInfo is arbitrary. The documentation recommends strictly limiting the set of attributes, but this is not necessary. For example, Oracle does not have such a limitation [5]. The setClientInfo array is completely translated into the getClientAttributes array.
The parameters set in setClientInfo are passed along with each JdbcRequest (this requires a new feature in JdbcThinFeature).
The client must reset the set values itself.

// JDBC connection to Ignite server.
try (Connection conn = DriverManager.getConnection(URL)) {
    conn.setClientInfo("SESSION_ID", "1234");
 
    ...
}

Spreading context across cluster nodes

Via the QueryStartRequest SQL message protocol (for jdbc, SQL transactions)
Via the transaction protocol for handling inserts (CacheInterceptor), since inserts are not always performed on the request initiator node.