Pegasus
Enhancement Proposal (PEP)
PEP #: 304
PEP Type: Functional PEP
Title: More Flexible namespace naming in Pegasus for the Interop
namespace
Version: 1.7
Created: 3 July 2007
Authors: K. schopmeyer
Status: Ballot
Version History:
|
Version
|
Date
|
Author
|
Change
Description
|
|
1.0
|
3 July
2007
|
|
Initial Submission
|
|
1.1
|
2
August 2007
|
KS
|
UPdate to reflect comments and define proposed solution
|
|
1.11
|
3
August 2007
|
KS
|
Minor changes to show comments from version 1.0 and show source
of requirement
|
|
1.2
|
5
August 2007
|
KS
|
Augment description of changes.
|
|
1.4
|
28
July 2011
|
Rohini
and Sahana
|
Final PEP for approval for 2.12
|
|
1.5
|
5
August 2011
|
Rohini
and Sahana
|
Updated with the comments after ballot approval
|
|
1.7
|
22
September 2011
|
Rohini
|
PEP re-approval for 2.12.Change in alias
implementation for PG_InterOp using
compile time option due to time constraints.
Changes are highlighted in blue.
|
Abstract: Changes to Pegasus to allow more flexible naming of
namespaces for all environments (development, release, etc.)
This version of the PEP defines the possible alternatives and a short term
solution.
Definition of the Problem
Today we have one particular issue with namespaces. The name pegasus
uses for the interop namespace is root/PG_InterOp. the DMTF is in the
process of establishing through its specifications (first the indication
profile and now the PRP) that in order to maintain interoperability all system
compliant with these specifications must have one of two possible names for the
interop namespace:
These requirements are defined
in the following DMTF documents:
The DMTF Indication Profile - Not yet released But this was not considered a
complete enough reference to force this type of change so it was included in
the PRP (see below) also.
The DMTF PRP( DSP 1033) version 1.0.0c as follows:
279 7.2 Establishing a Consistent Interop Namespace
280 For the purposes of consistency across implementations, a namespace named
“Interop” should be utilized as the Interop Namespace..
3. CR WIP 425 to the PRP Clarifies and extends the above statement to state
that :
7.2 Establishing a Consistent Interop Namespace
An implementation of this profile shall include an Interop Namespace. The name
of this Interop Namespace should shall be either 'interop' (preferred) or
'root/interop'. A slash character (/) may precede the name of the Interop
Namespace. The name of the Interop Namespace preceded with a slash, when used
as an identification of a namespace either as a parameter to a CIM operation or
as a CIM Instance property value, shall be considered by implementations as
equivalent to the Interop Namespace without the preceding slash. Note that this
DOES NOT imply that there be only a single interop namespace simply that the
information required of an information namespace be available if the user uses
one of the above namespaces
Thus the name we have applied PG_Interop will no longer be compliant with future DMTF specifications. This has become an
issue because it is clear now that the service location concepts we originally
defined (SLP) were not universally enough used so that in all cases users could
depend on a service finding mechanism to provide information on the interop
namespace name for a particular system and without this information, nothing
else is really possible using profiles. The alternate would have been a
new operation to return the interop namespace name. It is clear that a
number of our users including the SNIA based users will want to move to one of
these namespaces as soon as possible (i.e. Late summer or fall 2007. Thus
the issue is one tied to Pegasus 2.7.
At the same time, we have a continuity problem in that we cannot simply
force the change of the name of this namespace from root/PG_InterOp to interop
with existing systems.
NOTE: I would expect that since we will not release Pegasus 2.7 until this
fall, that there will be at least limited requests to provide a solution for
Pegasus 2.6 also, at least for SNIA work. Note that this would be limited
largely to people who build there Pegasus systems themselves and we might be
able to avoid the issues of rpms compatibility for this.
In general at some point in the future once can see where concepts like
dynamic namespace change, moving things from one namespace to another, etc. are
logical. However, for now, the primary objective of this change is to
allow existing Pegasus users and those are compiling their own Pegasus
implementations easy modification of the name of this namespace to comply with
the upcoming specifications. It would appear the the order of dynamicism
might be:
1. Today, be able to compile Pegasus and the
repository with alternate namespace names (at least Interop).
2. Be able to create an interop namespace with an
alternate name on a prebuilt pegasus system (future)
3. Be able to dynamically modify a repository and
server to change the names of namespaces (further in the future).
Proposed Solution
Possible alternate solutions
There are several possible solutions short term.
1. Make the namespace name (at least for this namespace) part of the build
process so that at the time of a build, repository build, rpm build, an
alternate name could be established. Today there is a significant number
of uses of the absolute string root/PG_Interop including about 20 references in
.cpp files, a few in header files, a significant number in Makefiles and some
in the release generation mechanism. There is a single point of
definition of the Interop Namespace in Common/Constants.h and also, a
definition in the configSchema Makefile. The goal of this effort would be that
the definition in the configSchema makefile would drive the whole process of
the name for the interop namespace so that a user could modify this definition
and compile/build a pegasus system for an alternate namespace.
2. Create a namespace dynamic renaming/aliasing mechanism for the server so
that all requests for a particular namespace (ex. root/PG_Interop) would be
modified to use an alternate real namespace name at the interface. This
is a concept that has been discussed at times for a namespace mapper on the
front end of Pegasus so that client side operations would have the namespace
name mapped from the externally defined name (ex. interop) to the internal name
(root/PG_Interop). While this sounds simple if it simply meant
changing the namespace name in the incoming XML and http header, in fact it
would mean searching the objects themselves in some cases for further uses of
the namespace and also modifying objects on output if they contained the
namespace name in references, etc. While the actual code might not be
significant, it could be a significant additional load on Pegasus for each
operation.
Requirements for an alias mechanism
The goal of an alias mechanism would be to allow the Cimserver users to
address the server with alternate namespace names that represent real
namespaces within the server but do not have separate physical implementations
of the classes and instances in the namespace. Operations against the
alias namespace are executed internally against the corresponding real
namespace. There are a number of different users that should be considered:
CIM Operation Clients - This would mean that the CIM Operations
that reference an alias namespace would, in fact access the corresponding real
namespace. Note that there is no requirement to return all information
with the namespace set to the alias namespace. The repository and/or
providers can return responses using the real namespace or the alias
namespace. Internally, the providers and repository should never see
operations targeted for the alias namespace. The target namespace field would
be changed in the operation to the real namespace before providers or
repository were accessed. Thus, the providers, repository, provider
registration, and provider routing would never know about the alias namespace,
and would use the real namespace.
However, there is one issue with CIM Operations, those operations that
create and modify objects. A user could execute a create or modify
instance that included references which might include the alias namespace or
make a method call with a reference that included the the alias namespace. Thus
a user could create an association where a reference would include the alias
namespace or execute a method with a CIM Parameter that included the alias
namespace. In the case where assocations are created
Pegasus Compilers - Note that we need to consider this because, since
the paths are different for processing compiler directives depending on whether
we use cimmofl or cimmof the requirement to allow the compiler to use an alias
namespace could affect different code in the Cim server than for other CIM
operation Clients.
Indications Received - TBD (not considered at this point)
Indications Created - If we protect the providers from seeing any alias
information, they should never know about an alias namespace and should never
create indications identifying that namespace.
COMMENT: (from discussion of version 1.0): We agreed that we will
need to provide for both of the above eventually. Pegasus cannot remain
committed to a fixed name for the interop namespace forever and at the same
time we must protect environments that already use PG_InterOp and have the need
to use one of the dictated namespaces to receive namespace requests.
COMMENT: From the initial discussion it became clear that if if we
are to allow maintaining the current existing namespace and also providing for
requests on the new namespaces, we only need to insure that requests that
arrive with the new namespace name are internally mapped to use the existing
interop namespace. Thus, we do not need to return responses with the new
namespace name. We can receive a request for an enumerate on /interop and
return a response to instances in root/PG_Interop. If it is a request
type that involves namespace information in the responses, the user will
receive the "real" namespace in the response (ex an association) and
should have no problems if he uses that information in further requests to
Pegasus. Oun only issue is to be able to receive the requests with the
new namespace names and understand that they are really addressed to
root/PG_InterOp. Thus, we are looking at an alias scheme for received
operation requests (requests for specific namespace names would be redefined to
use an existing corresponding real namespace).
Solution Proposals
There are several components to resolving the problem completely as follows:
1. Allow alternate names for Interop Namespace - Make the coding
changes to that the implementor of a Pegasus system can choose the name of the
namespace that is to be used for interop and is not forced to use
root/PG_InterOp. This would mean that the user could define the name for
the interop namespace at build time and this would be the name used throughout
the build, tests, and standard schema repository loads for Pegasus. While
we have clean out most of the use of specific namespace names in the code now,
there are still a number of places where the literal for the namespace is used
(in particular in evaluating test results).
PEP {a href=
'http://www.openpegasus.org/pp/protected/upreviews/20/1906/ReleaseNotes.htm'
}
249{/a}
Description
{br}
Note
that the ability to change the name and pass at least most of the tests has not
been tested at this point.
2.
Create an alias mechanism so that the required new namespaces (interop
and/or root/interop) are aliased to root/PG_Interop for incoming requests.
a. Build time namespace alias -
Simply a build time option so that any request for the interop or
root/interop namespace gets mapped to the root/PG_Interop namespace. This
would mean that the system builder would have to make the choice to use this
alias build time option and it would be fixed. This should be an easy
extension to the Repository code to provide the mapping. The requirements for
change to accomplish this are as follows:
i
– Build time option will add “interop” and “root/interop” in Hash table of
NameSpaceManager. The NamespaceManager class holds a hash table of all
namespaces. The alias namespace will also have an entry in this table but the
remaining entries for the hashtable will be copied from the real namespace
name. Thus the alias namespace will also have an entry in this table but all
operations will be performed on the real namespace since the NameSpace pointer
is of the real namespace. The Hash table definition is as below in
NamespaceManager,
typedef HashTable <String,
NameSpace*, EqualNoCaseFunc, HashLowerCaseFunc> Table;
ii - Code in the Repository
Namespace manager and CIMRepository to use this hash table so that
requests with the alias namespace name would be modified to use the real
namespace name. Thus any request for classes, instances, or associations to the
repository would have the namespace changed from the alias to the corresponding
real namespace (ex. getclass for /interop would be mapped to getclass for
/root/PG_Interop. Note that any requests to modify or remove these
namespaces or to create real namespaces with the same names MUST be rejected by
the repository. Therefore, there will be at least some changes to the
repository code to provide this protection against changes. Also, we will not
allow deletion of these namespaces specifically; only the real namespace can be
deleted or deleted.
iii - Change to the
CIMOperationDispatcher to modify the namespace name for operations from the
alias to the real namespace as the dispatcher process the request. This
is necessary so that we do not have to map other areas of the system and that
once an operation is processed by the dispatcher; the operation reflects the
real namespace, not the alias.
iv – If enumerate namespaces in CIM
repository lists the alias namespaces it causes problems in cimsub and few
other tests. For example: Filter1 which exists only for PG_Interop is listed
thrice once each for PG_InterOp, interop and root/interop. Therefore, a real namespace should be listed
only once and alias namespaces should not be listed. This also implies that
PG_Namespace and __Namespace will also not list the alias. This logically is
correct since there is only one real namespace. For debugging purpose we can list
the alias namespace in trace level INFO whenever CIM repository
enumerateNamespace is called.
b. Real namespace Alias mechanism - A real namespace alias
mechanism that would provide the capability to externally define namespace
aliases as part of creating and modifying the repository. Typically this would
require the following:
i.
Extension to the repository to actually provide for the definition of a
namespace name as an alias for another namespace and to persist this
information. Since we already have the capability to add special
characteristics to namespace names (shared, parent, child, etc.) the persitence
could be considered an extension of these mechanisms for another namespace
"feature". PEP 130 defined the basics of the new features for
shared, parent, child, etc. and we would simply extend them so that there was
an additional type (alias) with the appropriate functions to define it,
retrieve it, build the internal mapping table, etc. in the NamespaceManager
class.
ii.
Extension to PG_Namespace to provide the new feature and to allow it to be
input and presented. This would mean adding a new property to PG_Namespace
(correspondingRealNamespace) that if set was the name of the real namespace
corresponding to the namespace defined by the CIMNamespace instance. If
this property was not NULL, this would be treated as an alias namespace name on
input. If the namespace was an alias, the resulting output would include
this property to show the relationship.
iii.
Means to define an alias namespace. Logically since namespaces are
defined today through the compiler this would be an extension to the compiler
to allow defining an alias.
iv.
The NamespaceManger holds a hash table containing all the namespaces. Here the
entry for alias namespace will actually point to the actual namespace. However
when new alias namespace is added, it will be added to the repository with
“correspondingRealNamespace” set.
v.
Most of the CIM operations handled by CIMOperationDispatcher do not require
modifying the alias to real namespace as it will be taken care in
NamespaceManager. Only functions like _lookupInstanceProvider() which calls the
ProviderRegistrationManager-> lookupInstanceProvider() have to change alias
to real namespace before calling the ProviderRegistrationManager functions.
There are three such changes required in CIMOperationDispatcher.
NOTE: With this implementation, since
there would be an actual namespace in in the system for the alias there would
be no need for changes to __Namespace.
Proposal
for Pegasus 2.12.0
Creating the changes defined above
in 1 & 2a.
Adding the new build time option in
BuildAndReleaseOptions.
NameSpace Manager unit test cases
and testing provider registration with alias namespace rather than root/PG_InterOp.
This can be done by registering the existing test provider registration mofs
with alias namespace “interop” or “root/interop”
Detailed
Changes for Pegasus 2.12.0
a.
Build
time option which can have following values
interop – to build interop namespace
instead of root/PG_InterOp
root/interop - to build root/interop
namespace instead of root/PG_InterOp
interop_alias – to use alias option
(2a) – it will create interop and root/interop as aliases to root/PG_InterOp
b.
The
NamespaceManager class holds a hash table of all namespaces. The alias
namespace will also have an entry in this table but the remaining entries for
the hashtable will be copied from the real namespace name. Thus the alias
namespace will also have an entry in this table but all operations will be
performed on the real namespace since the NameSpace pointer is of the real
namespace. The Hash table definition is as below in NamespaceManager,
typedef HashTable <String,
NameSpace*, EqualNoCaseFunc, HashLowerCaseFunc> Table;
c.
As
the requests is propagated through various components in Pegasus the alias
namespace will be used but then the request will eventually be forwarded to the
real namespace via the NamespaceManager hash table and changes in CIMRepository
and CIMOperationDispatcher.
d.
Take
care of passing most of the test cases for option 1.
Rationale
The option 2a was chosen for the
following reasons:
·
No
changes required in repository database ( no repository db is created for alias
namespaces)
·
The
function to change alias to real namespace is called from CIMRepository and
CIMOperationDispatcher only if this build option is used. So in normal
scenario, the additional
load of checking for alias is saved for each operation.
·
Currently
there is no need to define aliases for other namespaces other than
root/PG_InterOp.
·
If
the above need arises, we can extend the current functionality to accommodate
option 2b.
The current investigation on 2b
shows that adding a new attribute corRealNameSpace to the mof file does not
help because cimmofl/cimmof does not pass the attributes while creating
namespace. A separate command like CreateExtNS2(used in CMPI for setting
remoteInfo in namespace) has to be created for creating alias namespace in
repository.
Schedule
PEP
Submission – 15 Sep 2011 (For ballot)
Approval - 22nd Sep
Code submission – Code for option 1 is submitted. Code
for 2a will be submitted soon.
Discussion
Discussion from Vesion 1.0 of this PEP.
This
was a concept version and the conclusion was that :
1.
We needed a way to preserve the existing PG_Interop namespace for existing
users.
2.
Should should be a simple way to do the alias namespace mechanism since there
is no requirement in the DMTF that the returned namespace on operations
information match the input namespace name.
The
new version reflects that set of changes.
[ (k_schopmeyer) The source for
documentation for this requiement is as follows:
1. Originally the indication
specification. It was concluded that that was not a universaly enough reference.
2. PRP (DSP1033) version 10.0c.
279 7.2 Establishing a Consistent
Interop Namespace
280 For the purposes of consistency
across implementations, a namespace named “Interop” should be utilized as the
Interop Namespace.. 3. CR WIP 425 to the PRP Clarifies and extends the above
statement to state that :
7.2 Establishing a Consistent Interop
Namespace
An implementation of this profile
shall include an Interop Namespace. The name of this Interop Namespace should
shall be either 'interop' (preferred) or 'root/interop'. A slash character (/)
may precede the name of the Interop Namespace. The name of the Interop
Namespace preceded with a slash, when used as an identification of a namespace
either as a parameter to a CIM operation or as a CIM Instance property value,
shall be considered by implementations as equivalent to the Interop Namespace
without the preceding slash. Note that this DOES NOT imply that there be only a
single interop namespace simply that the information required of an information
namespace be available if the user uses one of the above namespaces
¤28] Today we have one particular issue. The
name pegasus uses for the interop namespace is pG_Interop. the DMTF is in
the process of establishing through its specifications (first the indication
profile and now the PRP) that in order to maintain interoperability all system
compliant with these specifications must have one of two possible names for the
interop namespace:
[ ¤41] 2. Create some namespace dynamic renaming
mechanism for the server so that all requests for a particular namespace (ex.
root/PG_Interop) would be modified to use an alternate name at the
interface. This is a concept that has been discussed at times for a
namespace mapper on the front end of Pegasus so that client side operations
would have the namespace name mapped from the externally defined name (ex.
interop) to the internal name (root/PG_Interop). While this sounds
simple if it simply meant changing the namespace name in the incoming XML and
http header, in fact it would mean searching the objects themselves in some
cases for further uses of the namespace and also modifying objects on output if
they contained the namespace name in references, etc. While the actual
code might not be significant, it could be a significant additional load on
Pegasus for each operation.
[ (r_kumpf) It seems like the second approach is necessary. For
compatibility, root/PG_InterOp needs to continue to be supported.
(k_schopmeyer) It
worries me that this may be the case since this puts a significant load on
scanning mechanisms to modify the namespace information as information is
passed to and from the client.
I think roger is pointing out that we may well have future requirements
for implementations that want to continue to use exactly the existing interop
namespace for providers, adminstration, etc. but will require compliance with
the PRP.
To date, the implementations
we know about in the SNIA world do not have this requirement. They will want to
release a complete implementation with the namespace moved to the proper name.
(venkat_puvvada) We may use shared schema support as proposed in PEP 129. We can make
root/PG_InterOp as primary namespace and root/interop as readwrite secondary
namespace. Any updations to root/Interop namespace can be made to
root/PG_InterOP namespace.
¤42]
[ (r_kumpf) I don't think it is
necessary to convert the Interop namespace names to the standard names in all
CIM Server traffic. It may be sufficient to just treat the names as equivalent.
Discussion from version 1.4
of this PEP
While we have clean out most of the use of specific namespace
names in the code now, there are still a number of places where the literal for
the namespace is used (in particular in evaluating test results). [(k_schopmeyer) Need to document this since
it is not apparent
[ (rohini_deshpande) Just
to clarify, we'll do 1(Allow alternate names for Interop Namespace during build
time) and 2b(Real namespace Alias mechanism).
¤146] Creating the changes defined above in 2b.
[ (k_schopmeyer) I
assume you meant the PG_Namespace class here
(rohini_deshpande) Yes, both
PG_Namespace and Namespace.
¤152] Add new property “correspondingRealNamespace”
to the Namespace class. This will hold the pointer to real Namespace for alias
namespaces.
[ (k_schopmeyer) What
do you mean with the phrase 'by default'? I am still not sure how if you want
to insert a namespace x as alias to y we get it into the system. Do we want to
use the create Instance function of PG_Namespace or some other mechanism?
(rohini_deshpande) Yes createInstance
function of PG_Namespace will be used. The attribute correspondingRealNamespace
will be set similar to other namespace attributes like shareable, parent in
createNamespace.
¤153] Cimmof will be extended to handle the alias
namespace. By default interop and root/interop will be created as aliases for
PG_InterOp.
Copyright (c) 2006 Hewlett-Packard Development Company, L.P.; IBM Corp.;
EMC Corporation; Symantec Corporation; The Open Group.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"),
to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
BUT NOT
LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Template
last modified: March 26th 2006 by Martin Kirk
Template version: 1.11