Added support for using application context during the creation of a

anthony-tuininga · anthony-tuininga · commit ff01f65a7ccb · 2017-02-17T16:53:33.000-08:00
connection. This should be used in preference to the module, action and
clientinfo arguments which are now deprecated.
diff --git a/doc/module.rst b/doc/module.rst
@@ -23,8 +23,8 @@ Module Interface
       available in Oracle 10g Release 2 and higher.
 
 
-.. function:: Connection([user, password, dsn, mode, handle, pool, threaded, twophase, events, cclass, purity, newpassword, encoding, nencoding, module, action, clientinfo, edition])
-              connect([user, password, dsn, mode, handle, pool, threaded, twophase, events, cclass, purity, newpassword, encoding, nencoding, module, action, clientinfo, edition])
+.. function:: Connection([user, password, dsn, mode, handle, pool, threaded, twophase, events, cclass, purity, newpassword, encoding, nencoding, module, action, clientinfo, edition, appcontext])
+              connect([user, password, dsn, mode, handle, pool, threaded, twophase, events, cclass, purity, newpassword, encoding, nencoding, module, action, clientinfo, edition, appcontext])
 
    Constructor for creating a connection to the database. Return a Connection
    object (:ref:`connobj`). All arguments are optional and can be specified as
@@ -84,14 +84,24 @@ Module Interface
    The nencoding argument is expected to be a string if specified and sets the
    national encoding to use for national character set database strings.
 
-   The module, action and clientinfo arguments are expected to be strings if
-   specified and sets the module, action and client_info attributes on the
-   connection respectively.
+   The module, action and clientinfo arguments are expected to be strings, if
+   specified, and sets the module, action and client_info attributes on the
+   connection respectively. These arguments are deprecated and will be removed
+   in a future version of cx_Oracle since Oracle does not support their use
+   during the establishing of a connection. Instead, application context (see
+   below) should be used.
 
    The edition argument is expected to be a string if specified and sets the
    edition to use for the session. It is only relevant if both the client and
    the server are at least Oracle Database 11.2.
 
+   The appcontext argument is expected to be a list of 3-tuples, if specified,
+   and sets the application context for the connection. Application context
+   is available in the database by using the sys_context() PL/SQL method and
+   can be used within a logon trigger as well as any other PL/SQL procedures.
+   Each entry in the list is expected to contain three strings: the namespace,
+   the name and the value.
+
 
 .. function:: Cursor(connection)
 
diff --git a/doc/releasenotes.rst b/doc/releasenotes.rst
@@ -57,6 +57,9 @@ Version 5.3 (TBD)
     connection directly. The use of the twophase argument is now deprecated.
     Applications should set the internal_name and external_name attributes
     directly to a value appropriate to the application.
+28) Added support for using application context during the creation of a
+    connection. This should be used in preference to the module, action and
+    clientinfo arguments which are now deprecated.
 
 
 Version 5.2.1 (January 2016)
diff --git a/samples/AppContext.py b/samples/AppContext.py
@@ -0,0 +1,27 @@
+#------------------------------------------------------------------------------
+# AppContext.py
+#   This script demonstrates the use of application context. Application
+# context is available within logon triggers and can be retrieved by using the
+# function sys_context().
+#------------------------------------------------------------------------------
+
+from __future__ import print_function
+
+import cx_Oracle
+
+# define constants used throughout the script; adjust as desired
+CONNECT_STRING = "cx_Oracle/dev@localhost/orcl"
+APP_CTX_NAMESPACE = "CLIENTCONTEXT"
+APP_CTX_ENTRIES = [
+    ( APP_CTX_NAMESPACE, "ATTR1", "VALUE1" ),
+    ( APP_CTX_NAMESPACE, "ATTR2", "VALUE2" ),
+    ( APP_CTX_NAMESPACE, "ATTR3", "VALUE3" )
+]
+
+connection = cx_Oracle.Connection(CONNECT_STRING, appcontext = APP_CTX_ENTRIES)
+cursor = connection.cursor()
+for namespace, name, value in APP_CTX_ENTRIES:
+    cursor.execute("select sys_context(:1, :2) from dual", (namespace, name))
+    value, = cursor.fetchone()
+    print("Value of context key", name, "is", value)
+
diff --git a/src/Connection.c b/src/Connection.c
@@ -607,6 +607,109 @@ static PyObject *Connection_ChangePasswordExternal(
 }
 
 
+//-----------------------------------------------------------------------------
+// Connection_ProcessAppContext()
+//   Process application context during the establishing of a session. This is
+// intended to replace setting module, action and clientinfo (which was never
+// intended to be supported anyway!) and is more flexible in any case.
+//-----------------------------------------------------------------------------
+static int Connection_ProcessAppContext(
+    udt_Connection *self,               // connection
+    PyObject *appContextObj)            // app context value
+{
+    void *listHandle, *entryHandle;
+    PyObject *entryObj;
+    udt_Buffer buffer;
+    ub4 numEntries, i;
+    sword status;
+
+    // validate context is a list with at least one entry in it
+    if (!appContextObj)
+        return 0;
+    if (!PyList_Check(appContextObj)) {
+        PyErr_SetString(PyExc_TypeError,
+                "appcontext should be a list of 3-tuples");
+        return -1;
+    }
+    numEntries = (ub4) PyList_GET_SIZE(appContextObj);
+    if (numEntries == 0)
+        return 0;
+
+    // set the number of application context entries
+    status = OCIAttrSet(self->sessionHandle, OCI_HTYPE_SESSION,
+            (void*) &numEntries, sizeof(ub4),
+            OCI_ATTR_APPCTX_SIZE, self->environment->errorHandle);
+    if (Environment_CheckForError(self->environment, status,
+            "Connection_ProcessAppContext(): set app context size") < 0)
+        return -1;
+
+    // get the application context list handle
+    status = OCIAttrGet(self->sessionHandle, OCI_HTYPE_SESSION, &listHandle, 0,
+            OCI_ATTR_APPCTX_LIST, self->environment->errorHandle);
+    if (Environment_CheckForError(self->environment, status,
+            "Connection_ProcessAppContext(): get list handle") < 0)
+        return -1;
+
+    // set each application context entry
+    for (i = 0; i < numEntries; i++) {
+
+        // get entry
+        entryObj = PyList_GET_ITEM(appContextObj, i);
+        if (!PyTuple_Check(entryObj) || PyTuple_GET_SIZE(entryObj) != 3) {
+            PyErr_SetString(PyExc_TypeError,
+                    "appcontext should be a list of 3-tuples");
+            return -1;
+        }
+
+        // retrieve the context element descriptor
+        status = OCIParamGet(listHandle, OCI_DTYPE_PARAM,
+                self->environment->errorHandle, &entryHandle, i + 1);
+        if (Environment_CheckForError(self->environment, status,
+                "Connection_ProcessAppContext(): get entry handle") < 0)
+            return -1;
+
+        // set the namespace name
+        if (cxBuffer_FromObject(&buffer, PyTuple_GET_ITEM(entryObj, 0),
+                self->environment->encoding) < 0)
+            return -1;
+        status = OCIAttrSet(entryHandle, OCI_DTYPE_PARAM,
+                (void*) buffer.ptr, buffer.size, OCI_ATTR_APPCTX_NAME,
+                self->environment->errorHandle);
+        cxBuffer_Clear(&buffer);
+        if (Environment_CheckForError(self->environment, status,
+                "Connection_ProcessAppContext(): set namespace name") < 0)
+            return -1;
+
+        // set the name
+        if (cxBuffer_FromObject(&buffer, PyTuple_GET_ITEM(entryObj, 1),
+                self->environment->encoding) < 0)
+            return -1;
+        status = OCIAttrSet(entryHandle, OCI_DTYPE_PARAM,
+                (void*) buffer.ptr, buffer.size, OCI_ATTR_APPCTX_ATTR,
+                self->environment->errorHandle);
+        cxBuffer_Clear(&buffer);
+        if (Environment_CheckForError(self->environment, status,
+                "Connection_ProcessAppContext(): set name") < 0)
+            return -1;
+
+        // set the value
+        if (cxBuffer_FromObject(&buffer, PyTuple_GET_ITEM(entryObj, 2),
+                self->environment->encoding) < 0)
+            return -1;
+        status = OCIAttrSet(entryHandle, OCI_DTYPE_PARAM,
+                (void*) buffer.ptr, buffer.size, OCI_ATTR_APPCTX_VALUE,
+                self->environment->errorHandle);
+        cxBuffer_Clear(&buffer);
+        if (Environment_CheckForError(self->environment, status,
+                "Connection_ProcessAppContext(): set value") < 0)
+            return -1;
+
+    }
+
+    return 0;
+}
+
+
 //-----------------------------------------------------------------------------
 // Connection_Connect()
 //   Create a new connection object by connecting to the database.
@@ -620,7 +723,8 @@ static int Connection_Connect(
     PyObject *moduleObj,                // session "module" value
     PyObject *actionObj,                // session "action" value
     PyObject *clientinfoObj,            // session "clientinfo" value
-    PyObject *editionObj)               // session "edition" value
+    PyObject *editionObj,               // session "edition" value
+    PyObject *appContextObj)            // app context value
 {
     ub4 credentialType = OCI_CRED_EXT;
     udt_Buffer buffer;
@@ -735,6 +839,7 @@ static int Connection_Connect(
             "Connection_Connect(): set session handle") < 0)
         return -1;
 
+    // set module (deprecated)
     if (moduleObj) {
         if (cxBuffer_FromObject(&buffer, moduleObj,
                 self->environment->encoding))
@@ -748,6 +853,7 @@ static int Connection_Connect(
             return -1;
     }
 
+    // set action (deprecated)
     if (actionObj) {
         if (cxBuffer_FromObject(&buffer, actionObj,
                 self->environment->encoding))
@@ -761,6 +867,7 @@ static int Connection_Connect(
             return -1;
     }
 
+    // set client info (deprecated)
     if (clientinfoObj) {
         if (cxBuffer_FromObject(&buffer, clientinfoObj,
                 self->environment->encoding))
@@ -774,6 +881,7 @@ static int Connection_Connect(
             return -1;
     }
 
+    // set edition
     if (editionObj) {
         if (cxBuffer_FromObject(&buffer, editionObj,
                 self->environment->encoding))
@@ -787,6 +895,10 @@ static int Connection_Connect(
             return -1;
     }
 
+    // set application context, if applicable
+    if (appContextObj && Connection_ProcessAppContext(self, appContextObj) < 0)
+        return -1;
+
     // if a new password has been specified, change it which will also
     // establish the session
     if (newPasswordObj)
@@ -883,7 +995,7 @@ static int Connection_Init(
 {
     PyObject *usernameObj, *passwordObj, *dsnObj, *cclassObj, *editionObj;
     PyObject *threadedObj, *twophaseObj, *eventsObj, *newPasswordObj;
-    PyObject *moduleObj, *actionObj, *clientinfoObj;
+    PyObject *moduleObj, *actionObj, *clientinfoObj, *appContextObj;
     int threaded, twophase, events;
     char *encoding, *nencoding;
     ub4 connectMode, purity;
@@ -894,24 +1006,24 @@ static int Connection_Init(
     static char *keywordList[] = { "user", "password", "dsn", "mode",
             "handle", "pool", "threaded", "twophase", "events", "cclass",
             "purity", "newpassword", "encoding", "nencoding", "module",
-            "action", "clientinfo", "edition", NULL };
+            "action", "clientinfo", "edition", "appcontext", NULL };
 
     // parse arguments
     pool = NULL;
     handle = NULL;
     connectMode = OCI_STMT_CACHE;
     threadedObj = twophaseObj = eventsObj = newPasswordObj = NULL;
     usernameObj = passwordObj = dsnObj = cclassObj = editionObj = NULL;
-    moduleObj = actionObj = clientinfoObj = NULL;
+    moduleObj = actionObj = clientinfoObj = appContextObj = NULL;
     threaded = twophase = events = purity = 0;
     encoding = nencoding = NULL;
     purity = OCI_ATTR_PURITY_DEFAULT;
     if (!PyArg_ParseTupleAndKeywords(args, keywordArgs,
-            "|OOOiiO!OOOOiOssOOOO", keywordList, &usernameObj, &passwordObj,
+            "|OOOiiO!OOOOiOssOOOOO", keywordList, &usernameObj, &passwordObj,
             &dsnObj, &connectMode, &handle, &g_SessionPoolType, &pool,
             &threadedObj, &twophaseObj, &eventsObj, &cclassObj, &purity,
             &newPasswordObj, &encoding, &nencoding, &moduleObj, &actionObj,
-            &clientinfoObj, &editionObj))
+            &clientinfoObj, &editionObj, &appContextObj))
         return -1;
     if (threadedObj) {
         threaded = PyObject_IsTrue(threadedObj);
@@ -957,7 +1069,7 @@ static int Connection_Init(
                 purity);
     return Connection_Connect(self, connectMode, twophase, passwordObj,
             newPasswordObj, moduleObj, actionObj, clientinfoObj,
-            editionObj);
+            editionObj, appContextObj);
 }
 
 
