Pegasus Enhancement Proposal (PEP)
PEP #: 304
PEP Type: Functional PEP
Title: More Flexible namespace naming in Pegasus for the Interop namespace
Version: 1.6
Created: 3 July 2007
Authors: K. schopmeyer
Status: Approved
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.6 |
25
June 2013 |
Rohini |
Updated PEP after actual implementation |
Abstract: Changes to Pegasus to allow more flexible naming of namespaces for all environments (development, release, etc.)
This version of the PEP defines how ways to use Interop namespace in Open Pegasus. Reasons have been updated for earlier alternatives that have not been chosen.
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:
- interop
- root/interop
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.
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).
(2) and (3) will not be implemented since there is no need for it.
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.
3. Have an option in “repupgrade” to move namespace “root/PG_InterOp” to “interop”. Using this option an existing repository can be upgraded to use “interop” namespace instead of “root/PG_InterOp”.
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).
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).
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 an internal mapping fixed at build time so
that any request for the /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 mapper at build time and it would be fixed. This
should be an easy extension to the Repository code to provide the mapping and a
second change to the output display mechanisms (__namespace and CIM_Namepspace to show the alias namespaces. The requirements
for change to accomplish this are as follows:
i - Internal mapping table from name such as interop or root/interop to root/PG_Interop. This would be a table that would be defined at build time. An empty table would imply no alias.
ii - Code in the Repository Namespace manager and CIMRepository to use this 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: I am not certain that this component is necessary since if we do iii below before the first access to the repository (typically the class exists test) the namespace would be mapped before the repository access. 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 - Extensions to the namespace display mechanism so that if the PG_InterOp namespace exists, any display of existing namespaces will also list the alias. This will mean changes to the __Namespace and CIM_Namespace providers to specifically include the alias namespaces from the table if root/PG_Interop exists so that users of namespace lists see these as existing namespaces. Note that these aliases would show up in the namespace output list ONLY if the real interop namespace exists.
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.
3. Add an additional option in “repupgrade” so that namespace “root/PG_InterOp” can be migrated to “inetrop”. This option will be available only when you build OpenPegasus with the build time option “PEGASUS_INTEROP_NAMESPACE” set to “interop”.
The option (1) is available
in Pegasus 2.12. There is a new build time configuration option “PEGASUS_INTEROP_NAMESPACE”
which can be used to decide which interop namespace one
wants to use. It can be set to either “interop” or “root/interop”. Open Pegasus advises “interop”
namespace. This option will create an “interop”
namespace in your repository instead “root/PG_InterOp.
Namespace “root/PG_InterOp” will cease to exist. Please
see the Release notes for 2.12 for more details. This option will not help if
you want to retain your older repository. Use option (3) that is enabled with
2.13 Open Pegasus. All tests will now run with “interop”.
Make sure your clients use “interop” namespace.
The option (3) of repupgrade is enabled in Open Pegasus 2.13. A new option “-I”
is introduced in repupgrade command. With this option
the namespace “root/PG_InterOp” will be moved to “interop”. Any references, associations containing “root/PG_InterOp” will also be moved to “interop”.
Therefore, the new repository after running “repupgrade
–i” will contain only interop
and “root/PG_InterOp” will cease to exist. All
clients should now use “interop” namespace instead of
“root/PG_InterOp”.
The option (2) of aliasing
was stopped after a discussion in Face to Face meeting due to the following
reasons
-after testing a number of
design approaches found that due to namespaces being included in String
properties, reference properties, embedded instances andnamespace
parameters there is no approach for a 100% clean solution
-effort for building the
alias is estimated as an at least three month effort
PEP
Submission - 28 July 2011 (For ballot)
Approval - 4th August
Option (1) build time option is available in Open
Pegasus 2.12
Option (3) repupgrade “interop” support is available in Open Pegasus 2.13
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]
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