Learn how easy it is to sync an existing GitHub or Google Code repo to a SourceForge project! See Demo

Close

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

4.6.FC
fixed
None
enhancement
imm
-
major
2015-03-12
2013-11-28
No

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.

1 Attachments

Related

Tickets: #1277
Tickets: #191
Tickets: #643
Tickets: #873
Tickets: #886
Tickets: #930

Discussion

1 2 > >> (Page 1 of 2)
    • summary: IMM: API that uses replaces SaNameT with SaStringT and SA_IMM_ATTR_DN --> IMM: API that replaces SaNameT with SaStringT and SA_IMM_ATTR_DN
     
  • 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.

     
    • 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.
    
     
    • status: unassigned --> accepted
     
    • status: accepted --> review
     
  • Interface patch sent out for review.

     
    • Description has changed:

    Diff:

    --- old
    +++ new
    @@ -1,6 +1,6 @@
     The IMM service should provide an updated API where all use of the troublesome
    -SaNameT type is replaced by the SaStringT type. Also needed is a new flag value
    -for attribute definitions: SA_IMM_ATTR_DN. 
    +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
    @@ -21,69 +21,5 @@
     All the other flags may also be used in combination with SA_IMM_ATTR_DN, with
     the normal meaning. 
    
    -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
    -    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
    -    saImmOmAdminOwnerSet_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);
    -
    -    /* Argument objecName replaces parentName. See #38 */
    ----------------------------------------------------------------------
    -    SaAisErrorT
    -    saImmOmCcbObjectDelete_o3(SaImmCcbHandleT ccbHandle,
    -        const SaStringT objectName);
    ---------------------------------------------------------------------
    -    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);
    -------------------------------------------------------------
    -
    -The pattern should be clear.
    -
    -Corresponding OI APIs for both callbacks and downcalls where SaNameT parameter
    -is replaced with SaStringT would also be provided. 
    
    -
    
     
  •  
  • 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
    Anders Widell
    2014-04-03

    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
    Anders Widell
    2014-04-03

    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.

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

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

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

     
  •  
    • status: review --> assigned
    • assigned_to: Anders Bjornerstedt --> Zoran Milinkovic
    • Milestone: 4.5.FC --> 4.6.FC
     
  • 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).

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

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

     
    • status: assigned --> accepted
     
    • status: accepted --> review
     
  • 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.

     
    • status: review --> accepted
     
    • Description has changed:

    Diff:

    --- old
    +++ new
    @@ -14,9 +14,16 @@
         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.4) will only be allowed 
    +    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. 
    +    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.
    
     
1 2 > >> (Page 1 of 2)