You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ignite.apache.org by ti...@apache.org on 2025/05/30 11:59:29 UTC
(ignite) branch master updated: IGNITE-24402 Add SessionContext API documentation (#12082)
This is an automated email from the ASF dual-hosted git repository.
timoninmaxim pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/ignite.git
The following commit(s) were added to refs/heads/master by this push:
new a1d2b9c7698 IGNITE-24402 Add SessionContext API documentation (#12082)
a1d2b9c7698 is described below
commit a1d2b9c7698e81280fa50c363595584ae2587ad1
Author: Andrey Nadyktov <lo...@gmail.com>
AuthorDate: Fri May 30 14:59:22 2025 +0300
IGNITE-24402 Add SessionContext API documentation (#12082)
---
docs/_data/toc.yaml | 2 +
docs/_docs/SQL/custom-sql-func.adoc | 5 +-
.../ignite/snippets/IgniteSessionContext.java | 116 +++++++++++++++++++++
docs/_docs/session-context.adoc | 69 ++++++++++++
4 files changed, 191 insertions(+), 1 deletion(-)
diff --git a/docs/_data/toc.yaml b/docs/_data/toc.yaml
index 2aa404bfe45..3b7ce272095 100644
--- a/docs/_data/toc.yaml
+++ b/docs/_data/toc.yaml
@@ -376,6 +376,8 @@
url: data-structures/id-generator
- title: Distributed Locks
url: distributed-locks
+- title: Session Context
+ url: session-context
- title: REST API
url: restapi
- title: .NET Specific
diff --git a/docs/_docs/SQL/custom-sql-func.adoc b/docs/_docs/SQL/custom-sql-func.adoc
index 36d28947728..93320c072ab 100644
--- a/docs/_docs/SQL/custom-sql-func.adoc
+++ b/docs/_docs/SQL/custom-sql-func.adoc
@@ -61,8 +61,11 @@ include::{javaFile}[tags=sql-table-function-example, indent=0]
----
include::{javaFile}[tags=sql-table-function-config-query, indent=0]
----
+
+With custom SQL function you can get access to application attributes set on the client side via link:session-context#sql-function[SessionContext API].
+
NOTE: Creating custom functions in the system schema is forbidden. Creating a custom function in schema 'PUBLIC' is forbidden if the function name interferes with a standard function like 'TYPEOF' or 'SUBSTRING'.
-NOTE: The table functions also are available currently only with link:SQL/sql-calcite[Calcite, window=_blank].
+NOTE: The table functions and application attributes are currently available only with link:SQL/sql-calcite[Calcite, window=_blank].
NOTE: Classes registered with `CacheConfiguration.setSqlFunctionClasses(...)` must be added to the classpath of all the nodes where the defined custom functions might be executed. Otherwise, you will get a `ClassNotFoundException` error when trying to execute the custom function.
diff --git a/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/IgniteSessionContext.java b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/IgniteSessionContext.java
new file mode 100644
index 00000000000..a295169cb00
--- /dev/null
+++ b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/IgniteSessionContext.java
@@ -0,0 +1,116 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.ignite.snippets;
+
+import javax.cache.Cache;
+import java.sql.Connection;
+import java.sql.DriverManager;
+import java.sql.SQLException;
+import java.util.Map;
+
+import org.apache.ignite.cache.query.annotations.QuerySqlFunction;
+import org.apache.ignite.configuration.IgniteConfiguration;
+import org.apache.ignite.internal.util.typedef.F;
+import org.apache.ignite.cache.CacheInterceptor;
+import org.apache.ignite.lang.IgniteBiTuple;
+import org.apache.ignite.resources.SessionContextProviderResource;
+import org.apache.ignite.session.SessionContextProvider;
+import org.jetbrains.annotations.Nullable;
+
+public class IgniteSessionContext {
+
+ //tag::context[]
+ /** SessionContext interface. It's an entrypoint for all attributes. */
+ public interface SessionContext {
+
+ /** @return Attribute by name. */
+ public @Nullable String getAttribute(String attrName);
+ }
+ //end::context[]
+
+ //tag::sql-function[]
+ public class MyFunctions {
+
+ @SessionContextProviderResource
+ public SessionContextProvider sesCtxProv;
+
+ @QuerySqlFunction
+ public String sessionId() {
+ return sesCtxProv.getSessionContext().getAttribute("SESSION_ID");
+ }
+ }
+ //end::sql-function[]
+
+ //tag::cache-interceptor[]
+ public class SessionContextCacheInterceptor implements CacheInterceptor<Integer, String> {
+ /** */
+ @SessionContextProviderResource
+ private SessionContextProvider sesCtxPrv;
+
+ /** */
+ @Override public @Nullable String onGet(Integer key, @Nullable String val) {
+ String ret = sesCtxPrv.getSessionContext().getAttribute("onGet");
+
+ return ret == null ? val : ret + key;
+ }
+
+ /** */
+ @Override public @Nullable String onBeforePut(Cache.Entry<Integer, String> entry, String newVal) {
+ String ret = sesCtxPrv.getSessionContext().getAttribute("onBeforePut");
+
+ return ret == null ? newVal : ret + entry.getKey();
+ }
+
+ /** */
+ @Override public @Nullable IgniteBiTuple<Boolean, String> onBeforeRemove(Cache.Entry<Integer, String> entry) {
+ String ret = sesCtxPrv.getSessionContext().getAttribute("onBeforeRemove");
+
+ return new IgniteBiTuple<>(ret != null, entry.getValue());
+ }
+ }
+ //end::cache-interceptor[]
+
+ public void igniteSessContext() {
+ IgniteConfiguration ignCfg = new IgniteConfiguration();
+ //tag::ignite-context[]
+ try (Ignite ign = Ignition.start(ignCfg)) {
+
+ Map<String, String> appAttrs = F.asMap("SESSION_ID", "1234");
+
+ Ignite app = Ignite.withApplicationAttributes(appAttrs);
+
+ //Your code here...
+ }
+ //end::ignite-context[]
+ }
+
+ public void jdbcSessContext() {
+ String URL = "test";
+ //tag::jdbc-context[]
+ // JDBC connection to Ignite server.
+ try (Connection conn = DriverManager.getConnection(URL)) {
+
+ conn.setClientInfo("SESSION_ID", "1234");
+
+ //Your code here...
+ }
+ //end::jdbc-context[]
+ catch (SQLException e) {
+ throw new RuntimeException(e);
+ }
+ }
+}
\ No newline at end of file
diff --git a/docs/_docs/session-context.adoc b/docs/_docs/session-context.adoc
new file mode 100644
index 00000000000..9a73e9485ae
--- /dev/null
+++ b/docs/_docs/session-context.adoc
@@ -0,0 +1,69 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright ownership.
+// The ASF licenses this file to You under the Apache License, Version 2.0
+// (the "License"); you may not use this file except in compliance with
+// the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+= Session Context
+
+:javaFile: {javaCodeDir}/IgniteSessionContext.java
+
+== Overview
+
+Apache Ignite allows setting custom application attributes at runtime. These attributes may include session ID, application language, application name, etc. The attributes are set by the application only once for the Ignite API entry point (Ignite, JDBC) and are available on all participating nodes for application requests and queries.
+
+== SessionContext Interface
+
+`SessionContext` is an entry point for accessing attributes at all levels and other session-level data. Ignite provides `SessionContextProviderResource` annotation for access to SessionContext. User-defined functions, such as link:SQL/custom-sql-func[QuerySqlFunction] and `CacheInterceptor`, can access these attributes using `SessionContextProvider`.
+
+[source, java]
+----
+include::{javaFile}[tags=context,indent=0]
+----
+
+== Application Attributes in QuerySqlFunction [[sql-function]]
+
+User-defined SQL functions, like `QuerySqlFunction`, can utilize application attributes set on the client side:
+
+[source, java]
+----
+include::{javaFile}[tags=sql-function,indent=0]
+----
+
+NOTE: Attribute access is only available in the link:SQL/sql-calcite[Calcite] query engine. In such cases, the class must have a public zero-argument constructor.
+
+== Application Attributes in CacheInterceptor
+
+You can configure a custom `CacheInterceptor` and write callbacks with access to application attributes, which are invoked before and after main cache operations:
+
+[source, java]
+----
+include::{javaFile}[tags=cache-interceptor,indent=0]
+----
+
+== Setting application attributes
+
+=== Ignite
+
+You can set attributes using `Ignite.withApplicationAttributes(...)`. It returns an Ignite instance aware of the attributes. Application attributes are propagated to remote nodes:
+
+[source, java]
+----
+include::{javaFile}[tags=ignite-context,indent=0]
+----
+
+=== JDBC
+The standard JDBC protocol provides the method `Connection.setClientInfo(...)` to set client attributes, which are available during the connection’s lifetime. Attributes can be overriden by invoking `Connection.setClientInfo(...)` again with new parameters:
+
+[source, java]
+----
+include::{javaFile}[tags=jdbc-context,indent=0]
+----