#643 IMM: API that replaces SaNameT with SaStringT and SA_IMM_ATTR_DN

[Anders Bjornerstedt]

The IMM service should provide an updated API where all use of the troublesome
SaNameT type is replaced by the SaStringT type or the SaConstStringT type #625.
Also needed is a new flag value for attribute definitions: SA_IMM_ATTR_DN.

Defining an attribute in an IMM class definition on the SaStringT type and
also setting the flag SA_IMM_ATTR_DN, will mean that the attribute is intended
to hold a value that should be a DN.

Other flags that make sense to also set on such an attribute definition where
applicable are:

SA_IMM_ATTR_RDN if this is the RDN attribute. Just as having SaNameT the 
type of an RDN attribute indicates that the class is an association class,
having SaStringT and SA_IMM_ATTR_DN combined with SA_IMM_ATTR_RDN would 
also indicate that this is an association class.

SA_IMM_ATTR_NO_DANGLING. Currently (OpenSAF 4.5) is only allowed 
on attributes of type SaNameT, but will of course be allowed also on
attributes of type SaStringT if the SA_IMM_ATTR_DN flag is also set.
The exception is the RDN attribute which still can not have the 
SA_IMM_ATTR_NO_DANGLING set. The reason is that the RDN atribute, 
even if defined on SaNameT, or on SaStringT with SA_IMM_ATTR_DN flag,
actually does not contain a simple DN value. The RDN attribute of an
association object contains a value on the form X=Y where the right hand
side is a DN. Strictly speaking the logical type of an RDN attribute
is never a simple DN/reference, even if the type is SaNameT.

All the other flags may also be used in combination with SA_IMM_ATTR_DN, with
the normal meaning.

[Anders Bjornerstedt]

The corresponding set of immUtils functions would also be provided.

In fact the immUtils variant of the SaStringT-ified IMM API could be provided
based only on a delivery of the long DN support #191.
This should be done first to secure the long DN support in the next
OpenSAF release.

[Anders Bjornerstedt]

• Description has changed:

Diff:

--- old
+++ new
@@ -23,61 +23,61 @@

 Given such new DN typing, the following new API should be defined:

-SaAisErrorT
-saImmOmSearchInitialize_o3(SaImmHandleT immHandle,
-                           const SaStringT rootName,
-                           SaImmScopeT scope,
-                           SaImmSearchOptionsT searchOptions,
-                           const SaImmSearchParametersT_2 *searchParam,
-                           const SaImmAttrNameT *attributeNames,
-                           SaImmSearchHandleT *searchHandle);
+    SaAisErrorT
+    saImmOmSearchInitialize_o3(SaImmHandleT immHandle,
+        const SaStringT rootName,
+        SaImmScopeT scope,
+        SaImmSearchOptionsT searchOptions,
+        const SaImmSearchParametersT_2 *searchParam,
+        const SaImmAttrNameT *attributeNames,
+        SaImmSearchHandleT *searchHandle);
 ----------------------
-SaAisErrorT
-saImmOmSearchNext_o3(SaImmSearchHandleT searchHandle,
-                     SaStringT *objectName,  /* out */
-                     SaImmAttrValuesT_2  ***attributes);
+    SaAisErrorT
+    saImmOmSearchNext_o3(SaImmSearchHandleT searchHandle,
+        SaStringT *objectName,  /* out */
+        SaImmAttrValuesT_2  ***attributes);
 --------------------
-SaAisErrorT
-saImmOmAccessorGet_o3(SaImmAccessorHandleT accessorHandle,
-                      const SaStringT objectName, /* in */
-                      const SaImmAttrNameT *attributeNames,
-                      SaImmAttrValuesT_2 ***attributes);
+    SaAisErrorT
+    saImmOmAccessorGet_o3(SaImmAccessorHandleT accessorHandle,
+        const SaStringT objectName, /* in */
+        const SaImmAttrNameT *attributeNames,
+        SaImmAttrValuesT_2 ***attributes);
 --------------------------------------------------------
-SaAisErrorT
-saImmOmAdminOwnerSet_o3(SaImmAdminOwnerHandleT ownerHandle,
-                        const SaStringT *objectNames. 
-                        SaImmScopeT scope);
+    SaAisErrorT
+    saImmOmAdminOwnerSet_o3(SaImmAdminOwnerHandleT ownerHandle,
+        const SaStringT *objectNames. 
+        SaImmScopeT scope);
 ----------------------------------------------------------
-SaAisErrorT
-saImmOmAdminOwnerRelease_o3(SaImmAdminOwnerHandleT ownerHandle,
-                            const SaStringT *objectNames. 
-                            SaImmScopeT scope);
+    SaAisErrorT
+    saImmOmAdminOwnerRelease_o3(SaImmAdminOwnerHandleT ownerHandle,
+        const SaStringT *objectNames. 
+        SaImmScopeT scope);
 --------------------------------------------------------------
-SaAisErrorT
-saImmOmCcbObjectCreate_o3(SaImmCcbHandleT ccbHandle,
-                          const SaImmClassNameT className,
-                          const SaStringT objectName, /* in */
-                          const SaImmAttrValuesT_2 **attrValues);
+    SaAisErrorT
+    saImmOmCcbObjectCreate_o3(SaImmCcbHandleT ccbHandle,
+        const SaImmClassNameT className,
+        const SaStringT objectName, /* in */
+        const SaImmAttrValuesT_2 **attrValues);

-/* Argument objecName replaces parentName. See #38 */
+    /* Argument objecName replaces parentName. See #38 */
 ---------------------------------------------------------------------
-SaAisErrorT
-saImmOmCcbObjectDelete_o3(SaImmCcbHandleT ccbHandle,
-                       const SaStringT objectName);
+    SaAisErrorT
+    saImmOmCcbObjectDelete_o3(SaImmCcbHandleT ccbHandle,
+        const SaStringT objectName);
 --------------------------------------------------------------------
-SaAisErrorT
-saImmOmCcbObjectModify_o3(SaImmCcbHandleT ccbHandle,
-                          const SaStringT objectName,
-                          const SaImmAttrModificationT_2 **attrMods);
+    SaAisErrorT
+    saImmOmCcbObjectModify_o3(SaImmCcbHandleT ccbHandle,
+        const SaStringT objectName,
+        const SaImmAttrModificationT_2 **attrMods);
 --------------------------------------------------------------------
-SaAisErrorT
-saImmOmAdminOperationInvoke_o3(SaImmAdminOwnerHandleT ownerHandle,
-                               const SaStringT objectName,
-                               SaImmContinuationIdT continuationId,
-                               SaImmAdminOperationIdT operationId,
-                               const SaImmAdminOperationParamsT_2 **params,
-                               SaAisErrorT *operationReturnValue,
-                               SaTimeT timeout);
+    SaAisErrorT
+    saImmOmAdminOperationInvoke_o3(SaImmAdminOwnerHandleT ownerHandle,
+        const SaStringT objectName,
+        SaImmContinuationIdT continuationId,
+        SaImmAdminOperationIdT operationId,
+        const SaImmAdminOperationParamsT_2 **params,
+        SaAisErrorT *operationReturnValue,
+        SaTimeT timeout);
 ------------------------------------------------------------

 The pattern should be clear.

[Anders Bjornerstedt]

Interface patch sent out for review.

[Anders Bjornerstedt]

Backwards compatibility protection is needed when support for long DNs
is introduced in parts of OpenSAF.

The IMM will provide a guard for this through a new environment variable
IMMA_LONG_DN. This variable is expected to have the value of either 1 or 0,
where 1 means that long DNs are allowed over the IMMA API using the handle;
and 0 means that long DNs are not allowed over the IMMA API using the handle.

The environment variable is sampled at handle-initialize and tags
that handle for the rest of its lifetime.

For the new SaStringT/SaConstStringT IMM API, the default for this
variable will be 1, i.e. long DNs are allowed by default.

For the old IMM APIs based on SaNameT, the default value will be 0,
i.e. long DNS are not allowed by default. But if set to 1, then
long DNs will be allowed over the old APIS via the SaNameT "tunneling"
fix (ticket #191).

If long DNs are not allowed then any case where a long DN is detected
in a down-call, either as an input value from the user or as a result
out value from the library, then the call will fail with
SA_AIS_ERR_NAME_TOO_LONG.

If long DNs are not allowed then any case where a long DN from the
server destined for a callback is detected in the library, then the
callback will bounce back directly to the server (with no actual
callback to application made). The error code will depend on the
callback but should be either SA_AIS_ERR_BAD_OPERATION or
SA_AIS_ERR_FAILED_OPERATION.

In addition, a new config attribute should be provided for the immsv
controlling whether or not long DNs are allowed for the site.
If long DNs are not allowed for the site, then any attempt to create
an imm object with a long DN will be rejected. The config attribute
will by default be set to not allow long DNs. The config attribute
will of course only exist on systems running OpenSAF4.5 or higher.

[Anders Widell]

Some things to consider to ensure 100% backwards compatibility:

• SA_AIS_NAME_TOO_LONG is not listed as a possbile error code for all affected downcall APIs. So it might be better to use SA_AIS_ERR_INVALID_PARAM to be 100% compatible.

• The environment variable should probably also affect the RDN limit. I.e. when the variable is 1, there is no RDN length limit. When the variable is 0, then RDN length is limited to 64 bytes.

[Anders Widell]

Another thing to consider when introducing this new environment variable:

Maybe we should also let it affect how the RDN value is interpreted/presented to the application. I.e. whether the RDN attribute name is included in the value or not. So when the value is zero, the RDN attribute name is included, otherwise it is not.

[Anders Bjornerstedt]

Yes I suppose those are valid points, particularly the second.

On the first point, there is still something to be said for getting
a very clear and specific error code for this new potential problem.
The error code SA_AIS_ERR_INVALID_PARAM is typically not handled
by any applications because it implies an "interface violation"
committed by that application. But in a formal sense you are correct.

[Anders Bjornerstedt]

Regarding the RDN value presentation, I see that as an orthogonal issue.
it has nothing to do with long DNs or not. So I dont want to mix the two
issues.

With the an adjusted and simplified API for ccbObjectCreate (ticket #38
which is included in the new SaStringT based imm API #643), there is
no need any more for accessing the RDN attribute value.
Alternative presentation of the RDN attribute value (in accessor-get
and search-next) is tracked by #38.
Fortunately, the RDN attribute is not stored in the XML format,
which makes sense since it is totally redundant.

[Anders Bjornerstedt]

Ticket #643 API patch rebased on changeset 5412:cf91285fbaf7 attached.

[Anders Bjornerstedt]

This enhancement is postponed until 4.6 to reduce the documentation and testing burden for OpensAF 4.5 scheduled for FC in August.

We will try to provide a prototype extension of the immutils library
providing the same API functionality as proposed by this ticket
(replacing usage of SaNameT with SaStringT and SaConstStringT). I will
write a separate ticket for this.

The immutils library is used internally in OpenSAF but also available
under samples/immsv/immutil for opensaf users/deployers to copy.
Only doxygen documentation is provided (as part of the immutils source).

[Neelakanta Reddy]

saImmOmClassDescriptionGet_2 which has SaNameT parameter is missing in the attached P643.api.

[Neelakanta Reddy]

In The above post SaImmClassNameT is overlooked as SaNameT.
Above post is not valid.

[Zoran Milinkovic]

https://sourceforge.net/p/opensaf/mailman/message/33357693/

[Anders Bjornerstedt]

We need to review the server side design for this enhancement.
I realize that this may cause this one to slip to the next release.
Thats just the way it is with the 6 month release cycle.