Issue 6047: Need global unique identifier scheme compliant with MOF 2.0 standard (deployment-ftf) Source: Rockwell Collins (Mr. David Fitkin, nobody) Nature: Uncategorized Issue Severity: Summary: Problem: "UUID names" need to be defined as hierarchical in nature to create global uniqueness, while still supporting a simple local uniqueness. This should be accomplished using the URI approach defined by W3C as referenced in MOF 2.0. This approach provides an unambiguous solution that is scalable. The following MOF 2.0 excerpt references the W3C URI uniqueness as a solution. P1_01_MOF-Architecture.fm ad/2002-12-10 1-18 7. MOF 2.0 models the concept of identity. The lack of this capability in MOF, UML, CWM etc., made interoperability of metadata difficult to implement. The submitters understand that modeling identity is not easy, but we plan to show its usefulness in a simple domain - identity of metadata first. A key design goal is to make it easy to map this model of identity to W3C identity and referencing mechanisms such as the URI. The following excerpt from the W3C URI spec introduces the concept of an absolute URI. Using this absolute URI as a tentative solution would resolve the current naming and uniqueness concerns. An objects globally unique name would consist of its local name space name prefixed with the names of all objects in its containment hierarchy. Berners-Lee, et. al. Standards Track [Page 10] RFC 2396 URI Generic Syntax August 1998 3. URI Syntactic Components The URI syntax is dependent upon the scheme. In general, absolute URI are written as follows: <scheme>:<scheme-specific-part> An absolute URI contains the name of the scheme being used (<scheme>) followed by a colon (":") and then a string (the <scheme-specific- part>) whose interpretation depends on the scheme. The URI syntax does not require that the scheme-specific-part have any general structure or set of semantics which is common among all URI. However, a subset of URI do share a common syntax for representing hierarchical relationships within the namespace. This "generic URI" syntax consists of a sequence of four main components: <scheme>://<authority><path>?<query> each of which, except <scheme>, may be absent from a particular URI. For example, some URI schemes do not allow an <authority> component, and others do not use a <query> component. absoluteURI = scheme ":" ( hier_part | opaque_part ) URI that are hierarchical in nature use the slash "/" character for separating hierarchical components. For some file systems, a "/" character (used to denote the hierarchical structure of a URI) is the delimiter used to construct a file name hierarchy, and thus the URI path will look similar to a file pathname. This does NOT imply that the resource is a file or that the URI maps to an actual filesystem pathname. hier_part = ( net_path | abs_path ) [ "?" query ] net_path = "//" authority [ abs_path ] abs_path = "/" path_segments URI that do not make use of the slash "/" character for separating hierarchical components are considered opaque by the generic URI parser. opaque_part = uric_no_slash *uric uric_no_slash = unreserved | escaped | ";" | "?" | ":" | "@" | "&" | "=" | "+" | "$" | "," We use the term <path> to refer to both the <abs_path> and <opaque_part> constructs, since they are mutually exclusive for any given URI and can be parsed as a single component. Proposed resolution: Require the use of unique component identifiers, these identifiers cannot be optional, duplicate, or blank/empty. All objects requiring identity management, or providing containment must have unique identifiers constructed using URI format and character content guidelines. NOTE: there could be both a "relative" local unique identifier, and a global unique identifier (absolute). All objects need the local unique, but not all objects need the absolute global identifier. This point requires further discussion. Use all unique component identifiers involved in an individual components containment hierarchy to produce a globally unique identifier for it. The W3C URI specification provided above states that this approach using identifiers with separator characters can be used for resources that are not related to file systems. These identifiers are intended to be global identifiers, and not necessarily paths to objects. It could be assumed that a well defined name would provide object locator information if properly used. The FTF team should feel free to define exactly this global identifier constructed using unique namespace identifiers and "separator characters". The scheme should be described, but left available for implementers to define. Resolution: Revised Text: Actions taken: August 1, 2003: received issue Discussion: End of Annotations:===== From: To: issues@omg.org Subject: New Issue for Deployment FTF X-Mailer: Lotus Notes Release 5.0.10 March 22, 2002 Date: Thu, 31 Jul 2003 19:56:35 -0500 X-MIMETrack: Serialize by Router on CollinsCRSMTP02/CedarRapids/RockwellCollins(Release 5.0.10 |March 22, 2002) at 07/31/2003 07:56:36 PM, Serialize complete at 07/31/2003 07:56:36 PM Issue for Deployment and Configuration FTF Subject: Need global unique identifier scheme compliant with MOF 2.0 standard Problem: "UUID names" need to be defined as hierarchical in nature to create global uniqueness, while still supporting a simple local uniqueness. This should be accomplished using the URI approach defined by W3C as referenced in MOF 2.0. This approach provides an unambiguous solution that is scalable. The following MOF 2.0 excerpt references the W3C URI uniqueness as a solution. P1_01_MOF-Architecture.fm ad/2002-12-10 1-18 7. MOF 2.0 models the concept of identity. The lack of this capability in MOF, UML, CWM etc., made interoperability of metadata difficult to implement. The submitters understand that modeling identity is not easy, but we plan to show its usefulness in a simple domain - identity of metadata first. A key design goal is to make it easy to map this model of identity to W3C identity and referencing mechanisms such as the URI. The following excerpt from the W3C URI spec introduces the concept of an absolute URI. Using this absolute URI as a tentative solution would resolve the current naming and uniqueness concerns. An objects globally unique name would consist of its local name space name prefixed with the names of all objects in its containment hierarchy. Berners-Lee, et. al. Standards Track [Page 10] RFC 2396 URI Generic Syntax August 1998 3. URI Syntactic Components The URI syntax is dependent upon the scheme. In general, absolute URI are written as follows: : An absolute URI contains the name of the scheme being used () followed by a colon (":") and then a string (the ) whose interpretation depends on the scheme. The URI syntax does not require that the scheme-specific-part have any general structure or set of semantics which is common among all URI. However, a subset of URI do share a common syntax for representing hierarchical relationships within the namespace. This "generic URI" syntax consists of a sequence of four main components: ://? each of which, except , may be absent from a particular URI. For example, some URI schemes do not allow an component, and others do not use a component. absoluteURI = scheme ":" ( hier_part | opaque_part ) URI that are hierarchical in nature use the slash "/" character for separating hierarchical components. For some file systems, a "/" character (used to denote the hierarchical structure of a URI) is the delimiter used to construct a file name hierarchy, and thus the URI path will look similar to a file pathname. This does NOT imply that the resource is a file or that the URI maps to an actual filesystem pathname. hier_part = ( net_path | abs_path ) [ "?" query ] net_path = "//" authority [ abs_path ] abs_path = "/" path_segments URI that do not make use of the slash "/" character for separating hierarchical components are considered opaque by the generic URI parser. opaque_part = uric_no_slash *uric uric_no_slash = unreserved | escaped | ";" | "?" | ":" | "@" | "&" | "=" | "+" | "$" | "," We use the term to refer to both the and constructs, since they are mutually exclusive for any given URI and can be parsed as a single component. Proposed resolution: Require the use of unique component identifiers, these identifiers cannot be optional, duplicate, or blank/empty. All objects requiring identity management, or providing containment must have unique identifiers constructed using URI format and character content guidelines. NOTE: there could be both a "relative" local unique identifier, and a global unique identifier (absolute). All objects need the local unique, but not all objects need the absolute global identifier. This point requires further discussion. Use all unique component identifiers involved in an individual components containment hierarchy to produce a globally unique identifier for it. The W3C URI specification provided above states that this approach using identifiers with separator characters can be used for resources that are not related to file systems. These identifiers are intended to be global identifiers, and not necessarily paths to objects. It could be assumed that a well defined name would provide object locator information if properly used. The FTF team should feel free to define exactly this global identifier constructed using unique namespace identifiers and "separator characters". The scheme should be described, but left available for implementers to define. Date: Wed, 05 Nov 2003 09:36:45 -0500 From: James Kulp Organization: Mercury Computer Systems, Inc. User-Agent: Mozilla/5.0 (Macintosh; U; PPC Mac OS X Mach-O; en-US; rv:1.4) Gecko/20030624 X-Accept-Language: en,pdf To: deployment-ftf@omg.org Subject: Proposed solution to issue 6047: Need global unique identifier scheme compliant with MOF 2.0 Here is a belated followup to a telecon meeting a month ago or so, where Dave Fitkin elaborated this issue and we discussed the rough outline of a solution. Here is a less rough proposed solution, which, after discussion, can be turned into specific proposed document changes. Basic summary is: get more rigorous and specific about identity! More problem statement details: The data models currently have UUID attributes for all classes which have useful scenarios as standalone and reusable work products. These UUIDs are described generally in section 6.3 and are described as being URIs compliant with MOF 2.0. Elements contained by the work product classes (with UUIDs) generally have "name" attributes that are required to be unique within their containing class. The execution data model has "source" attributes to implement a traceability feature much requested in the OMG. These attributes are described whereever they apply as identifying the entity in the component data model information (from the RepositoryManager) that represented a particular choice when the planner processed that information. To further clarify this and avoid incompatibilties: Proposed solution: 0. Point out that the identities defined in the specification are URNs as defined in RFC 2396, namely that they are URIs whose purpose is identity, not access. Similarly, point out that the "location" attributes are URLs. (URNs and URLs are both URIs. A URI can be either or both). 1. Specify that named subelements have a virtual unique absolute identity (URN) created by assembling a MOF 2.0 compliant URI according to the rules of hierarchical URIs, with the "name" attributes of the subelements used as "path segments" to build the URNs, as defined in RFC 2396. Any reserved characters in the "name" attribute would be escaped to form the path segment. Define the "source" attributes generically as containing such URNs. 2. Specify that the UUID attributes of classes should be a URN that is an absolute URI in a scheme that supports hierarchies (hier_part in the grammar). 3. Specify that the installPackage or createPackage operations on the repositoryManager interface create such UUIDs when the incoming information has left it blank. This enforces the uniqueness here, allowing it to remain optional for upstream tools at their discretion, while ensuring that down stream infrastructure will always have them. Furthermore specify that the repositoryManager will create UUIDs for newly created PackageConfigurations. 4. Specify that the newly created PackageConfigurations created as a side effect of the installPackage, createPackage, or createConfiguration operations will assign a UUID to those packageConfigurations [and add the missing UUID to the PackageConfiguration class]. 5. Add the UUID attribute to the DeploymentPlan class, which is a work product, but which was inadvertently missing this attribute. X-Dreamscape-Track-Mars-A: 66-124-51-179.ded.pacbell.net [66.124.51.179] X-Dreamscape-Track-Mars-B: Mon, 2 Feb 2004 15:44:26 -0500 (EST) Date: Mon, 02 Feb 2004 15:26:46 -0500 From: James Kulp Organization: Mercury Computer Systems, Inc. User-Agent: Mozilla/5.0 (Macintosh; U; PPC Mac OS X Mach-O; en-US; rv:1.5.1) Gecko/20031120 X-Accept-Language: en,pdf To: Deployment FTF Subject: Detailed proposal for solution to 6047, as resolved in London , but augmented Although this was discussed and resolved in London, I forgot to do a final writeup and thus it didn't make the last ballot. Sorry about that. The bad news is it wasn't on the ballot. The good news is that it is now a more consistent and comprehensive solution to the whole UUID issue, and results in some simplication. Furthermore, I know we had a discussion about the "optionality" of UUIDs, but we have no minutes. If I remember: The "pro" side had the simple use case during the development cycle where you could just "recompile and rerun", with no meddling with metadata, and also explicitly disabling any caching in the system. Simple clients and tools could avoid the UUID issue altogether. The "con" side had the case of "its good practice, force everyone to do, it will be mandatory for deployment". I chose to keep it optional in this proposal for the standard, which means a compliant implementation will accept both, while any implementation can have a mode to force UUIDs to be present to reinforce that policy. The alternative is the opposite: for compliance to mean force the policy, and let implementations have a "relaxed" mode for convenience. I personally don't care, but we should re-settle this. Finally, there was another UUID aspect which, upon reflection, deserved to be cleaned up here since otherwise the solution cannot be comprehensive. That is the inconsistency and confusion between the identity treatment of PackageConfigurations and ComponentPackageDescriptions, and the inability to reference a PackageConfiguration when defining a subcomponent instance. Dealing with this actually simplifies the overall solution (and simplifies the RepositoryManager), and achieves true consistent treatment of UUIDs. Proposed solution to issue 6047, missing definition and consistent usage of UUIDs. More problem statement details: The data models currently have UUID attributes for all classes which have useful scenarios as standalone and reusable work products. These UUIDs are described generally in section 6.3 and are described as being URIs compliant with MOF 2.0. Elements contained by the work product classes (those with UUIDs) generally have "name" attributes that are required to be unique within their containing class. The execution data model has "source" attributes to implement a traceability feature much requested in the OMG. These attributes are described whereever they apply as identifying the entity in the component data model information (from the RepositoryManager) that represented a particular choice when the planner processed that information. It is not clear just how these name, UUID, and source attributes relate to each other and precisely what format they must have. The proposed changes below clarifies and makes consistent the definition, application and usage of UUIDs. Proposed solution: (based on the 03-12-02 convenience document) Summary of solution: Clarify and tighten the definitions of UUID, source, name, and location attributes, in general. Add UUID attribute to DeploymentPlan. Replace "name" attribute in PackageConfiguration with a UUID. Make PackageConfiguration a proper standalone work product with UUID that can indirectly reference packages in the same way that subcomponent instances in an assembly can. Enable indirect references as embodied by the ComponentPackageReference and used in two places, to reference by UUID or repository installation name or component type. Make it clear that the names used by the RepositoryManager are just used to find things in the repository and do not affect the identity or labels of the things in the repository. Make PackageConfiguration the "top level thing" in a CCM package archive, thus allowing for clarifying and simplifying the RepositoryManager as containing PackageConfigurations only. Make the necessary simplifications to the RepositoryManager, now that there is no difference between installing or creating "packages" and "package configurations". Operations are {install,create,delete}Package, findPackageBy{Name,*UUID}, getAll{Types,Names}, and findNamesByType. (* == new). {create,update}Configuration are removed. Changes in the model conventions section: In section 6.3, replace the old paragraph: UUID: A machine-readable identifier that uniquely identifies a .work product.. If UUIDs compare equal, then the elements in question are considered identical. For example, if two implementation artifacts have identical UUIDs, then the deployment system can assume that it needs to be loaded onto a node only once. UUID content is optional: a blank UUID (the empty string) is considered nonequal to any other UUID. Thus users are not required to generate proper UUIDs for internal purposes (e.g. during testing). If a UUID field is non-blank, then it must comply to the URI syntax [URI], in alignment with MOF 2.0 identifiers [MOF2]. with the new paragraph: UUID: A globally unique identifier (of type String) that is a URN as defined in RFC 2396, in which a URN is defined as a URI whose purpose is identity, not access (which is a URL). The value must be an "absolute URI" with a URI scheme that allows hierarchical URIs as defined in RFC 2396. If two entities having such an attribute have identical UUIDs, then the deployment system can assume they are functionally identical and interchangeable, with identical contents. This enables the deployment system to cache information based on this UUID attribute, and know that a previously cached/processed entity can be used if it had the same UUID value. The value of this attribute is optional (can be an empty string), but this is interpreted as meaning that the object is transient, the UUID value will be considered unequal to any other UUID value, and thus the object will never be considered the same as any other object, thus precluding any caching or any aliasing. This optionality is convenient in many development scenarios (e.g. recompile with no change in metadata) and provides certain advice to the implementation, but is generally unsuitable for true deployed, configuration-managed, production versions of such objects. Implementations of this specification may have options that insist on the existence of UUID values, but this is not necessary for compliance. Human readable URI schemes are recommended, but not mandatory. In section 6.3, replace the old paragraph: location: references an entity outside of the model. The location attribute is of type String, its value(s) must comply to the URI syntax. Multiple alternative locations to the same entity may be supplied (multiplicity 1..*); applications can then choose any of these locations to access the entity (e.g. choosing a local file URI over a http reference). with the new paragraph: location: references an entity outside of the model. The location attribute is of type String, its value(s) must comply to the URI syntax, as defined in RFC 2396. The value represents a URL, which is a URI whose purpose is access, not identity (which is a URN). Multiple alternative locations to the same entity may be supplied since the multiplicity 1..*; applications can then choose any of these equivalent locations to access the entity (e.g. choosing a local file URI over a http reference). The contents accessed are identical, although the actual locations (e.g. servers or file systems) may in fact be different. One of the values must use the http scheme/protocol, which is the only protocol that is required to be supported. In section 6.3, add a paragraph that standardizes how attributes with the name "source" are used: source: URNs that are both absolute and hierarchical URIs (according to RFC2396) identifying the hierarchical path of objects from which this object originated. These URNs are built using the UUID attributes as the absolute "root" and the "name" attributes as components underneath that "root" (separated by slashes). When a UUID attribute (rather than a name attribute) is encountered in the middle of the path, it, along with name attributes below it, is embedded and escaped as a single path component. Empty UUIDs are rendered with some appropriate scheme, and a repository installationName as the absolute part. In section 6.3, change the paragraph: name: Names are both human-readable and machine-readable. Names are mandatory, and they must be unique within their container or context. For example, in the case of a node, the node.s name must be unique within the domain. with the paragraph: name: Names are both human-readable and machine-readable. Names are mandatory, and they must be unique within their container or context. For example, in the case of a node, the node.s name must be unique within the domain. Furthermore, entities with "name" attributes are contained by entities that have either "name" attributes or "UUID" attributes, and thus there is a "virtual" URN for each entity with a "name" attribute formed by tracing the containment relationship until a "UUID" attribute exists and forming an absolute and hierarchical URN from the UUID and the "name" attributes as path components according to RFC 2396. Changes to apply UUIDs more consistently to the various "work product" classes: In 6.4.2.2 (attributes of PackageConfiguration): Change the paragraph: name: String Unique name for this PackageConfiguration. to UUID: String [0..1] An unique identifier for this package configuration Add paragraph to section 6.8.1.2, attributes of DeploymentPlan: UUID: String [0..1] An unique identifier for this deployment plan. Changes to use UUIDs consistently, and to properly implement traceability: Provide for PackageConfigurations to reference others the same way that subcomponent instances reference others, which allows PackageConfigurations to be uniquely identified work products by themselves. The new association is xor-d with the two existing ones. Change the descriptive paragraph to section 6.4.2.1 from: A PackageConfiguration describes one configuration of a component package. It either specializes another PackageConfiguration or is directly based on a ComponentPackageDescription. A PackageConfiguration has a name, a label and two sets of properties. Configuration properties are used to configure the application's properties; their names and types must match the component's external properties. Selection requirements are used to influence deployment decisions by matching them against implementation capabilities in the ComponentImplementationDescription. to: A PackageConfiguration describes one configuration of a component package. It either directly contains and specializes another PackageConfiguration, directly contains and configures another ComponentPackageDescription, or indirectly specializes another PackageConfiguration that is identified by a ComponentPackageReference. A PackageConfiguration has a UUID, a label, and two sets of properties. Configuration properties are used to configure the application's properties; their names and types must match the component's external properties. Selection requirements are used to influence deployment decisions by matching them against implementation capabilities in the ComponentImplementationDescription. A PackageConfiguration can be standalone work product which captures all the information necessary to plan for, and run, a component based application. It thus can be completely monolithic (containing all the metadata descriptions for a complete implementation hierarchy) or simply a request to run some previously installed component software in a particular way. Add association to PackageConfiguration (in text and diagram), in section 6.4.2.3: reference: ComponentPackageReference [0..1] Indirectly references another package configuration that this PackageConfiguration is configuring. Change description paragraph for ComponentPackageReference, section 6.4.8.1 from References an outside package that provides an implementation for this subcomponent instance. to Indirectly references a package to be found in a repository. The reference is accomplished by using a combination of the requiredUUID, requiredName, and requiredType attributes. All are optional although one must be present. All that are present must be satisfied. The requiredName refers to the name under which the package was installed into a repository. The three attributes satisfy a variety of reference patterns similar to those found in DLL or shared library systems. Change attributes to ComponentPackageReference, in section 6.4.8.2 from requiredType: String Identifies a required component interface by type. The implementation that is chosen to satisfy the reference must support this type. to requiredUUID: String[0..1] . the reference is to a installed PackageConfiguration with this specified identity. requiredName; String[0..1] . the reference is to an installed PackageConfiguration installed under the specified name. requiredType: String[0..1] . the reference is to an installed PackageConfiguration that ultimately references a ComponentPackageDescription that implements the specified type. Changes to simply the RepositoryManager consistent with clarified UUID usage: Change the description of the RepositoryManager from: A RepositoryManager manages component data. It maintains a collection of PackageConfiguration elements. Package installation results in a new ComponentPackageDescription represented by a PackageConfiguration with an empty set of properties. PackageConfigurations are identified by labels that are unique within the repository. The RepositoryManager can provide a list of all package configuration labels that support a given component interface's UID, and a list of all UIDs. PackageConfiguration elements can be created based on (specializing) existing package configurations or by installing a new package. After creation, package configurations can be updated. to A RepositoryManager manages component data. It maintains a collection of PackageConfiguration elements. Package installation results in a PackageConfiguration existing in the repository under an installer-assigned installationName. PackageConfigurations can be installed by value (with the caller supplying the actual data structure) or by location (with the caller supplying a URL). PackageConfigurations themselves have UUIDs and labels, assigned by the creator of the PackageConfiguration. Installation names are are unique within the repository. The RepositoryManager can provide a list of the installationNames of all PackageConfigurations or all that support a given component type. It can retrieve PackageConfigurations by installationName or UUID. PackageConfigurations in the repository can directly contain ComponentPackageDescriptions or have indirect references to other PackageConfigurations, either in the same repository or in other repositories in the planner's search path. PackageConfigurations in the repository can be replaced or removed. Change the description of the installPackage operation in 6.5.1.2 from: installPackage (name: String, label: String, location: String) Installs a package in the repository, assigning the given name and label to the new PackageConfiguration. Raises the NameExists exception if a configuration by this name already exists. Raises the PackageError exception if an internal error is detected in the package. to installPackage (installationName: String, location: String) Installs a package in the repository, under the given installationName. Raises the NameExists exception if a PackageConfiguration by this installationName already exists. Raises the PackageError exception if an internal error is detected in the package. Change the description of the createPackage operation in 6.5.1.2 from: createPackage (name: String, label: String, package: ComponentPackageDescription,baseLocation: String) Installs a ComponentPackageDescription in the repository, assigning a given name and label to the new PackageConfiguration. Relative URIs in the location or idlFile attributes are interpreted according to the baseLocation. Raises the NameExists exception if a configuration by this name already exists. Raises the PackageError exception if an internal error is detected in the package. to createPackage (installationName: String, package: PackageConfiguration,baseLocation: String, replace:Boolean) Installs a PackageConfiguration in the repository, assigning a given installationName. Relative URIs in the location or idlFile attributes are interpreted according to the baseLocation. If the replace argument is true, replace any existing PackageConfiguration with the same installationName, otherwise raise the NameExists exception if a configuration by this installaitonName already exists. Raises the PackageError exception if an internal error is detected in the package. Remove the createConfiguration, updateConfiguration operations. Rename the deleteConfiguration operation to deletePackage, replacing deleteConfiguration (name: String, deletePackage: Boolean) Deletes the PackageConfiguration that is referenced by name and all other PackageConfiguration elements that are based on it. If this is the last PackageConfiguration for a component package, and if the deletePackage parameter is set to true, then the package is also removed from the repsoitory. Raises the LastConfiguration exception if this is the last PackageConfiguration for a component package and the deletePackage parameter is false. Raises the NoSuchName exception if the name does not exist. with deletePackage (installationName: String) Deletes the PackageConfiguration that is referenced by name. If this is the last PackageConfiguration for a component package. Raises the NoSuchName exception if the name does not exist. Change the name of the findConfigurationbyName to findPackageByName Add the operation to retrieve packages by UUID: findPackageByUUID (UUID: String): PackageConfiguration Locates a PackageConfiguration by UUID. Raises the NoSuchName exception if the name does not exist. In section 9.5.3 (description of top level package in PSM for CCM for XML) changes from: The ToplevelPackageDescription is introduced to point to the ComponentPackageDescription element for the top-level component package in a package. to (with diagram update): The ToplevelPackageDescription is introduced to point to the PackageConfiguration element for the top-level component package in a package. Add the sentence to section 9.5.8 (xml file extensions) A Package Configuration Descriptor contains a PackageConfiguration document element; it has the ..pcd. file extension. Change the extension for TopLevelPackage Descriptors from "pcd" to "tpd". Date: Wed, 25 Feb 2004 09:00:52 -0500 From: James Kulp Organization: Mercury Computer Systems, Inc. User-Agent: Mozilla/5.0 (Macintosh; U; PPC Mac OS X Mach-O; en-US; rv:1.5.1) Gecko/20031120 X-Accept-Language: en,pdf To: Deployment FTF Subject: Detailed proposal for solution to 6047, with final fix from anaheim The email below is basically unchanged except for some improvements to the "source" attribute which were motivated by the re-resolution that occurred in Anaheim. The fix was to properly ensure that the traceability was possible without any interaction with the (hidden, private) operation of the planner. The embedded URLs for repository provides direct access to all the original metadata. ---------------------------------------------------------------------------------------------------- Although this was discussed and resolved in London, I forgot to do a final writeup and thus it didn't make the last ballot. Sorry about that. The bad news is it wasn't on the ballot. The good news is that it is now a more consistent and comprehensive solution to the whole UUID issue, and results in some simplication. Furthermore, I know we had a discussion about the "optionality" of UUIDs, but we have no minutes. If I remember: The "pro" side had the simple use case during the development cycle where you could just "recompile and rerun", with no meddling with metadata, and also explicitly disabling any caching in the system. Simple clients and tools could avoid the UUID issue altogether. The "con" side had the case of "its good practice, force everyone to do, it will be mandatory for deployment". I chose to keep it optional in this proposal for the standard, which means a compliant implementation will accept both, while any implementation can have a mode to force UUIDs to be present to reinforce that policy. The alternative is the opposite: for compliance to mean force the policy, and let implementations have a "relaxed" mode for convenience. I personally don't care, but we should re-settle this. Finally, there was another UUID aspect which, upon reflection, deserved to be cleaned up here since otherwise the solution cannot be comprehensive. That is the inconsistency and confusion between the identity treatment of PackageConfigurations and ComponentPackageDescriptions, and the inability to reference a PackageConfiguration when defining a subcomponent instance. Dealing with this actually simplifies the overall solution (and simplifies the RepositoryManager), and achieves true consistent treatment of UUIDs. Proposed solution to issue 6047, missing definition and consistent usage of UUIDs. More problem statement details: The data models currently have UUID attributes for all classes which have useful scenarios as standalone and reusable work products. These UUIDs are described generally in section 6.3 and are described as being URIs compliant with MOF 2.0. Elements contained by the work product classes (those with UUIDs) generally have "name" attributes that are required to be unique within their containing class. The execution data model has "source" attributes to implement a traceability feature much requested in the OMG. These attributes are described whereever they apply as identifying the entity in the component data model information (from the RepositoryManager) that represented a particular choice when the planner processed that information. It is not clear just how these name, UUID, and source attributes relate to each other and precisely what format they must have. The proposed changes below clarifies and makes consistent the definition, application and usage of UUIDs. Proposed solution: (based on the 03-12-02 convenience document) Summary of solution: Clarify and tighten the definitions of UUID, source, name, and location attributes, in general. Add UUID attribute to DeploymentPlan. Replace "name" attribute in PackageConfiguration with a UUID. Make PackageConfiguration a proper standalone work product with UUID that can indirectly reference packages in the same way that subcomponent instances in an assembly can. Enable indirect references as embodied by the ComponentPackageReference and used in two places, to reference by UUID or repository installation name or component type. Make it clear that the names used by the RepositoryManager are just used to find things in the repository and do not affect the identity or labels of the things in the repository. Make PackageConfiguration the "top level thing" in a CCM package archive, thus allowing for clarifying and simplifying the RepositoryManager as containing PackageConfigurations only. Make the necessary simplifications to the RepositoryManager, now that there is no difference between installing or creating "packages" and "package configurations". Operations are {install,create,delete}Package, findPackageBy{Name,*UUID}, getAll{Types,Names}, and findNamesByType. (* == new). {create,update}Configuration are removed. Changes in the model conventions section: In section 6.3, replace the old paragraph: UUID: A machine-readable identifier that uniquely identifies a .work product.. If UUIDs compare equal, then the elements in question are considered identical. For example, if two implementation artifacts have identical UUIDs, then the deployment system can assume that it needs to be loaded onto a node only once. UUID content is optional: a blank UUID (the empty string) is considered nonequal to any other UUID. Thus users are not required to generate proper UUIDs for internal purposes (e.g. during testing). If a UUID field is non-blank, then it must comply to the URI syntax [URI], in alignment with MOF 2.0 identifiers [MOF2]. with the new paragraph: UUID: A globally unique identifier (of type String) that is a URN as defined in RFC 2396, in which a URN is defined as a URI whose purpose is identity, not access (which is a URL). The value must be an "absolute URI" with a URI scheme that allows hierarchical URIs as defined in RFC 2396. If two entities having such an attribute have identical UUIDs, then the deployment system can assume they are functionally identical and interchangeable, with identical contents. This enables the deployment system to cache information based on this UUID attribute, and know that a previously cached/processed entity can be used if it had the same UUID value. The value of this attribute is optional (can be an empty string), but this is interpreted as meaning that the object is transient, the UUID value will be considered unequal to any other UUID value, and thus the object will never be considered the same as any other object, thus precluding any caching or any aliasing. This optionality is convenient in many development scenarios (e.g. recompile with no change in metadata) and provides certain advice to the implementation, but is generally unsuitable for true deployed, configuration-managed, production versions of such objects. Implementations of this specification may have options that insist on the existence of UUID values, but this is not necessary for compliance. Human readable URI schemes are recommended, but not mandatory. In section 6.3, replace the old paragraph: location: references an entity outside of the model. The location attribute is of type String, its value(s) must comply to the URI syntax. Multiple alternative locations to the same entity may be supplied (multiplicity 1..*); applications can then choose any of these locations to access the entity (e.g. choosing a local file URI over a http reference). with the new paragraph: location: references an entity outside of the model. The location attribute is of type String, its value(s) must comply to the URI syntax, as defined in RFC 2396. The value represents a URL, which is a URI whose purpose is access, not identity (which is a URN). Multiple alternative locations to the same entity may be supplied since the multiplicity 1..*; applications can then choose any of these equivalent locations to access the entity (e.g. choosing a local file URI over a http reference). The contents accessed are identical, although the actual locations (e.g. servers or file systems) may in fact be different. One of the values must use the http scheme/protocol, which is the only protocol that is required to be supported. In section 6.3, add a paragraph that standardizes how attributes with the name "source" are used: source: A string formatted as a relative URI (according to RFC2396) that identifies an element in the Component Data Model, along with the containing elements. Each top level PackageConfiguration (directly retrieved from a repository) is represented buy an empty segment followed by a segment containing the URL (appropriately escaped) of the repository followed by a segment containing the installationName of the PackageConfiguration. All other segments represent "name" attributes of contained model elements. This supports complete navigation to model elements that were chosen from multiple repositories used by the planner, without requiring any collaboration with the planner. In section 6.3, change the paragraph: name: Names are both human-readable and machine-readable. Names are mandatory, and they must be unique within their container or context. For example, in the case of a node, the node.s name must be unique within the domain. with the paragraph: name: Names are both human-readable and machine-readable. Names are mandatory, and they must be unique within their container or context. For example, in the case of a node, the node.s name must be unique within the domain. Furthermore, entities with "name" attributes are contained by entities that have either "name" attributes or "UUID" attributes, and thus there is a "virtual" URN for each entity with a "name" attribute formed by tracing the containment relationship upwards until a "UUID" attribute exists and forming an absolute and hierarchical URN from the UUID and the "name" attributes as path components according to RFC 2396. Changes to apply UUIDs more consistently to the various "work product" classes: In 6.4.2.2 (attributes of PackageConfiguration): Change the paragraph: name: String Unique name for this PackageConfiguration. to UUID: String [0..1] An unique identifier for this package configuration Add paragraph to section 6.8.1.2, attributes of DeploymentPlan: UUID: String [0..1] An unique identifier for this deployment plan. Changes to use UUIDs consistently, and to properly implement traceability: Provide for PackageConfigurations to reference others the same way that subcomponent instances reference others, which allows PackageConfigurations to be uniquely identified work products by themselves. The new association is xor-d with the two existing ones. Change the descriptive paragraph to section 6.4.2.1 from: A PackageConfiguration describes one configuration of a component package. It either specializes another PackageConfiguration or is directly based on a ComponentPackageDescription. A PackageConfiguration has a name, a label and two sets of properties. Configuration properties are used to configure the application's properties; their names and types must match the component's external properties. Selection requirements are used to influence deployment decisions by matching them against implementation capabilities in the ComponentImplementationDescription. to: A PackageConfiguration describes one configuration of a component package. It either directly contains and specializes another PackageConfiguration, directly contains and configures another ComponentPackageDescription, or indirectly specializes another PackageConfiguration that is identified by a ComponentPackageReference. A PackageConfiguration has a UUID, a label, and two sets of properties. Configuration properties are used to configure the application's properties; their names and types must match the component's external properties. Selection requirements are used to influence deployment decisions by matching them against implementation capabilities in the ComponentImplementationDescription. A PackageConfiguration can be standalone work product which captures all the information necessary to plan for, and run, a component based application. It thus can be completely monolithic (containing all the metadata descriptions for a complete implementation hierarchy) or simply a request to run some previously installed component software in a particular way. Add association to PackageConfiguration (in text and diagram), in section 6.4.2.3: reference: ComponentPackageReference [0..1] Indirectly references another package configuration that this PackageConfiguration is configuring. Change description paragraph for ComponentPackageReference, section 6.4.8.1 from References an outside package that provides an implementation for this subcomponent instance. to Indirectly references a package to be found in a repository. The reference is accomplished by using a combination of the requiredUUID, requiredName, and requiredType attributes. All are optional although one must be present. All that are present must be satisfied. The requiredName refers to the name under which the package was installed into a repository. The three attributes satisfy a variety of reference patterns similar to those found in DLL or shared library systems. Change attributes to ComponentPackageReference, in section 6.4.8.2 from requiredType: String Identifies a required component interface by type. The implementation that is chosen to satisfy the reference must support this type. to requiredUUID: String[0..1] . the reference is to a installed PackageConfiguration with this specified identity. requiredName; String[0..1] . the reference is to an installed PackageConfiguration installed under the specified name. requiredType: String[0..1] . the reference is to an installed PackageConfiguration that ultimately references a ComponentPackageDescription that implements the specified type. Changes to simply the RepositoryManager consistent with clarified UUID usage: Change the description of the RepositoryManager from: A RepositoryManager manages component data. It maintains a collection of PackageConfiguration elements. Package installation results in a new ComponentPackageDescription represented by a PackageConfiguration with an empty set of properties. PackageConfigurations are identified by labels that are unique within the repository. The RepositoryManager can provide a list of all package configuration labels that support a given component interface's UID, and a list of all UIDs. PackageConfiguration elements can be created based on (specializing) existing package configurations or by installing a new package. After creation, package configurations can be updated. to A RepositoryManager manages component data. It maintains a collection of PackageConfiguration elements. Package installation results in a PackageConfiguration existing in the repository under an installer-assigned installationName. PackageConfigurations can be installed by value (with the caller supplying the actual data structure) or by location (with the caller supplying a URL). PackageConfigurations themselves have UUIDs and labels, assigned by the creator of the PackageConfiguration. Installation names are are unique within the repository. The RepositoryManager can provide a list of the installationNames of all PackageConfigurations or all that support a given component type. It can retrieve PackageConfigurations by installationName or UUID. PackageConfigurations in the repository can directly contain ComponentPackageDescriptions or have indirect references to other PackageConfigurations, either in the same repository or in other repositories in the planner's search path. PackageConfigurations in the repository can be replaced or removed. Change the description of the installPackage operation in 6.5.1.2 from: installPackage (name: String, label: String, location: String) Installs a package in the repository, assigning the given name and label to the new PackageConfiguration. Raises the NameExists exception if a configuration by this name already exists. Raises the PackageError exception if an internal error is detected in the package. to installPackage (installationName: String, location: String) Installs a package in the repository, under the given installationName. Raises the NameExists exception if a PackageConfiguration by this installationName already exists. Raises the PackageError exception if an internal error is detected in the package. Change the description of the createPackage operation in 6.5.1.2 from: createPackage (name: String, label: String, package: ComponentPackageDescription,baseLocation: String) Installs a ComponentPackageDescription in the repository, assigning a given name and label to the new PackageConfiguration. Relative URIs in the location or idlFile attributes are interpreted according to the baseLocation. Raises the NameExists exception if a configuration by this name already exists. Raises the PackageError exception if an internal error is detected in the package. to createPackage (installationName: String, package: PackageConfiguration,baseLocation: String, replace:Boolean) Installs a PackageConfiguration in the repository, assigning a given installationName. Relative URIs in the location or idlFile attributes are interpreted according to the baseLocation. If the replace argument is true, replace any existing PackageConfiguration with the same installationName, otherwise raise the NameExists exception if a configuration by this installaitonName already exists. Raises the PackageError exception if an internal error is detected in the package. Remove the createConfiguration, updateConfiguration operations. Rename the deleteConfiguration operation to deletePackage, replacing deleteConfiguration (name: String, deletePackage: Boolean) Deletes the PackageConfiguration that is referenced by name and all other PackageConfiguration elements that are based on it. If this is the last PackageConfiguration for a component package, and if the deletePackage parameter is set to true, then the package is also removed from the repsoitory. Raises the LastConfiguration exception if this is the last PackageConfiguration for a component package and the deletePackage parameter is false. Raises the NoSuchName exception if the name does not exist. with deletePackage (installationName: String) Deletes the PackageConfiguration that is referenced by name. If this is the last PackageConfiguration for a component package. Raises the NoSuchName exception if the name does not exist. Change the name of the findConfigurationbyName to findPackageByName Add the operation to retrieve packages by UUID: findPackageByUUID (UUID: String): PackageConfiguration Locates a PackageConfiguration by UUID. Raises the NoSuchName exception if the name does not exist. In section 9.5.3 (description of top level package in PSM for CCM for XML) changes from: The ToplevelPackageDescription is introduced to point to the ComponentPackageDescription element for the top-level component package in a package. to (with diagram update): The ToplevelPackageDescription is introduced to point to the PackageConfiguration element for the top-level component package in a package. Add the sentence to section 9.5.8 (xml file extensions) A Package Configuration Descriptor contains a PackageConfiguration document element; it has the ..pcd. file extension. Change the extension for TopLevelPackage Descriptors from "pcd" to "tpd".