Issue 6392: 6.4.14 MonolithicImplementationDescription (deployment-ftf) Source: Raytheon (Mr. Gerald Lee Bickle, Gerald.L.Bickle(at)raytheon.com) Nature: Uncategorized Issue Severity: Summary: Deployment & Configuration Technical Issue 6.4.14 MonolithicImplementationDescription The deployRequirement relationship is too broad. A component implementation needs to able to specify resources required (used by) a component and a resource deployed on requirement. Also in the ComponentAssemblyDescription you need to be able to reference these (both types) resources so a component in the assembly can connect to these resources. These are concepts in the SCA that are not in the D & C specification. Resolution: Revised Text: Actions taken: October 29, 2003: received issue Discussion: End of Annotations:===== ubject: D & C Issues To: issues@omg.org Cc: deployment-ftf@omg.org, swradio@omg.org X-Mailer: Lotus Notes Release 5.0.8 June 18, 2001 From: Gerald_L_Bickle@raytheon.com Date: Wed, 29 Oct 2003 07:53:20 -0500 X-MIMETrack: Serialize by Router on NotesServer3/HDC(Release 5.0.12 |February 13, 2003) at 10/29/2003 07:53:39 AM Deployment & Configuration Technical Issue 6.4.14 MonolithicImplementationDescription The deployRequirement relationship is too broad. A component implementation needs to able to specify resources required (used by) a component and a resource deployed on requirement. Also in the ComponentAssemblyDescription you need to be able to reference these (both types) resources so a component in the assembly can connect to these resources. These are concepts in the SCA that are not in the D & C specification. Jerry Bickle Senior Principal Software Engineer Network Centric Systems 1010 Production Rd Fort Wayne, IN 46808-4711 260-429-6280 Date: Sun, 04 Jan 2004 16:14:06 -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: Proposed solution to issue 6392 (resources) - finally... Problem: Although the planner is choosing and/or allocating resources to meet the requirements of monolithic implementations and connections, the deployment plan does not contain this information and thus it is not available where it is needed: at the NodeManager and the implementation itself. Commentary/Use cases: For example, when there are several node resources that could satisfy a deployment requirement (of a MonolithicImplementation), there is no way to indicate which resource was in fact allocated, or which part of a (capacity-type) resource was allocated. The node needs this information not only to maintain resource consistency, but also to communicate this allocation to the actual implementation (or its container). Since the implementation specified the requirements, it must be told which resource allocation was made for which requirement. This could also be thought of as a synchronization issue between the NodeManager's view of resources and the TargetManager's view of resources, in the case where the NodeManager actually did keep track of local resource usage. There is already a method by which the NodeManager can inform the TargetManager of changes in resources (via the updateDomain operation). However, there is no communication in the other direction other than the (offline metadata) requirements of a MonolithicImplementation that are in the plan now. Thus we tell the node "what was requested" as opposed to "what was granted". Essentially, the "defect" is that the plan contains the requirements needed rather than the resources allocated, even though the planner has made the allocation decisions. Also, when the relationship between the implementation instance and the resource it required involves patterns of port delegation or callbacks, there is no information in the plan, as provided to the node or container, to implement these relationships. The SCA was an important source of such use cases. Solution: General description Although this solution is not simple, reviewers should be assured that a number of alternative solutions were investigated in search of the simplest solution that solved the problem. This one was the least complex, while preserving the important distinction between the world of functional description, composability, reusability and replaceability, vs. the world of concrete implementations and their resource requirements. Also, this solution is biased in favor of simpler implementations by assigning functionality to containers. Unfortunately, seeing all these implications takes some time. In this proposed solution, requirements are fixed to have identity scoped to the entity having the requirements. This identity allows resources granted/allocated to be 1) associated with stated requirements and 2) communicated to the node, implementations and instances. Extra information is added to requirements to indicate how the implementation instances will actually use the resources granted to them. The instances and connections in the deployment plan are fixed to indicate which resources, offered by whom, were selected to satisfy which requirements. Actual component instances on a node are told which resources were selected to satisfy the requirements expressed by the metadata of the implementation of that instance. E.g., if an implementation needs an audio channel, then an instance created from that implementation is informed of the audio channel chosen. The "value" of a resource is the result of allocation, which may be a selection among alternatives, or an actual capacity value. It may be any data type, including object and component references. This "resource value" is provided in the Execution Data Model as detailed below. Although the mechanisms used to associate resources with instances, when the "value" of the resource happens to be an object reference, is somewhat analogous to "connections", the solution proposed here does not use that concept. Rather it prefers to keep "resource usage by implementations" distinct from "connections between ports defined in assemblies". This preserves the "purely functional" nature of assemblies and connections. An alternative solution which tried to reuse "connection" concepts for using resources, was investigated and rejected as doing more harm through complexity than good through re-use. Fixes to the Component Data Model (Requirement class): 1. A "name" attribute is be added to the Requirement class (in 6.10.7) to uniquely identify requirements of an implementation. This will enable the plan to contain, and thus the node (and implementation) to know, which resources were chosen by the planner to satisfy each requirement. Since "name" attributes of a class are already defined as being unique within the containing class, the actual text in 6.10.7.2 for the added attribute can simply be: -- new document text -- name:String - the name of this requirement, used in the deployment plan to link resources to the requirements they are intended to satisfy. -- end new document text -- 2. A new class, derived from Requirement, called ImplementationRequirement, contains additional information needed by the requirements associated with MonolithicImplementationDescriptions. This class description should be added to section 6.4. One of the attributes uses a new enumeration which should also be added to section 6.4. -- new document text -- Description: The ImplementationRequirement class specializes the Requirement class with additional attributes which are needed to express how the implementation instance will actually use the resource. This information is ultimately needed by the container to "hook up" the implementation to the resources granted to it. Attributes: resourcePort:String[0..1] - when the resource granted to satisfy this requirement is itself a component, and thus the resource value is a component reference, and the component instance needs to use a particular port of the granted resource, this attribute specifies the name of the port of the resource component. componentPort:String[0..1] - when the resource itself actually acts as a component port of the implementation (essentially delegating the port to the resource), this attribute specified the name of the port of the component. OCL: it must be a port of the interface being implemented. resourceUsage:ResourceUsageKind - how the resource granted to satisfy this requirement will be used by the container and/or instance. See the definition of ResourceUsageKind for semantics. OCL: - if InstanceUsesResource, componentPort must be empty - if ResourceUsesInstance, componentPort must be empty and resourcePort must be non-empty. - if PortUsesResource, componentPort must be non-empty - if ResourceUsesPort, componentPort must be non-empty and resourcePort must be non-empty. Description: ResourceUsageKind enumeration indicates how the resource chosen to satisfy an implementation requirement is used by the node manager and component instance. It answers the question: how will the resource value chosen to satisfy this requirement be used by the instance requiring it? Semantics: The choices are: InstanceUsesResource - the resource value is given to the instance when it is created. If the resourcePort attribute is non-empty, it indicates that the resource value must be a component reference, and that the port reference obtained from that component reference, using that attribute, should be given to the instance as the value of the resource. ResourceUsesInstance - the instance provides a reference for use by the resource (callback from resource to instance). The resource value is a component reference. Thus the resourcePort attribute indicates which "uses" port of the resource should use the reference provided by the instance. The instance constructor provides a reference associated with the requirement, to provide to the resource to enable the "callback". PortUsesResource - the resource value is used as one of the (provided) ports of the component instance (rather than by the instance itself). The componentPort attribute indicates which of the instance's component ports is being provided by (delegated to) the resource. The resourcePort attribute, if present, indicates that the resource value is a component that provides the reference at one of its ports. Otherwise the resource value is used directly as the instance's provided port reference. ResourceUsesPort - the resource value uses the component port indicated by the componentPort attribute, rather than the instance itself implementing that port. Thus the implementation is delegating the "uses" port to the resource. The resource value is a component reference and the specified port of the resource uses the component port. None - the resource is not directly used by the instance (i.e. it is needed prior to loading or instantiation, like the "deployed on" relationship in the SCA). --end new document text 3. The type of the deployRequirement association from MonolithicImplementationDecription to the Requirement class is changed from "Requirement" to the new "ImplementationRequirement". Fixes to the Execution Data Model: 1. Artifacts, instances, and connections all have requirements and thus must have associated resources in the plan. A base class is defined which describes a resource allocated by the planner for the deployment of all three. This base class is then specialized for two cases. The base class is ResourceDeploymentDescription (a description of a deployed resource). The derived classes have the prefixes Instance, and Connection respectively. Add a section 6.8.9 to specify these three new execution data model classes: -- new document text -- Description: ResourceDeploymentDescription contains information about how a requirement of a monolithic implementation instance, artifact or connection was satisfied by indicating the requirement, the resource, and how the resource will be used to satisfy the requirement. Attributes: requirementName:String - the name of the requirement being satisfied. This is not a model association with the Requirement class because that information does not necessarily need to be in the plan. This attribute will enable the node, container and/or implementation instance to know which resource was used to satify each of its specified requirements. resourceName: String - the name of the target domain entity's resource chosen to satisfy the requirement. resourceValue: Any - the aspect of the resource actually allocated, if any, of the appropriate type of the resource's SatisfierKind attribute. For Quantity, it is the ordinal allocated. For Allocation, it is the capacity, for Selection, it is the matched string. For others it is the value of the matched property. Description: InstanceResourceDeploymentDescription specializes ResourceDeploymentDescription to describe resources allocated for instances. Associated with and contained by an InstanceDeploymentDescription. Attributes: resourceUsage: ResourceUsageKind - how the resource will be used to satisfy the requirement (copied from the original requirement) Description: ConnectionResourceDeploymentDescription specializes ResourceDeploymentDescription to describe resources allocated for connections. Associated with and contained by a PlanConnectionDescription. Attributes: targetName: String - the name of the target domain entity from which the resource was allocated (e.g. node, interconnect, bridge, etc.), to provide scope for the requirementName. This attribute is required because connections may traverse multiple bridges and interconnects. --end new document text -- 2. Add a containing association in the existing InstanceDeploymentDescription class, ArtifactDeploymentDescription class, and PlanConnectionDescription class to contain 0 or more ResourceDeploymentDescriptions. In InstanceDeploymentDescription: (note the two associations are needed because the name scopes for the requirements are different). -- new document text -- deployedResource: InstanceResourceDeploymentDescription[*] - The resources chosen to satisfy the requirements of the implementaiton as specified in the MonolithicImplementationDescription, which were satisfied by the node's private (not shared) resources. deployedSharedResource: InstanceResourceDeploymentDescription[*] - The resources chosen to satisfy the requirements of the implementaiton as specified in the MonolithicImplementationDescription, which were satisfied by the node's shared resources. --end new document text -- In PlanConnectionDescription: -- new document text -- deployedResource: ConnectionResourceDeploymentDescription[*] - The resources chosen to satisfy the requirements of the connection as specified in the AssemblyConnectionDescription. --end new document text -- In ArtifactDeploymentDescription: -- new document text -- deployedResource: ResourceDeploymentDescription[*] - The resources chosen to satisfy the requirements of the implementaiton as specified in the ImplementationArtifactDescription. --end new document text -- 3. Since artifacts may require and use resources themselves (separate from the per-instance requirements in the MonolithicImplementationDescription), the ArtifactDeploymentDescription, and the MonolithicDeploymentDescription classes can only be shared across nodes when there are no such requirements. In 6.8.3.1, change: --old text deployed more than once --end old text to: --new text deployed more than once, either on the same node, or using only artifacts with no node-specific resource requirements, --end new text In 6.8.2.1, change: --old text use the same artifact more than once --end old text to: --newtext use the same artifact more than once, either on the same node, or if the artifacts has no node-specific resource requirements, --end new text Other issues excluded from this resolution which will be raised separately, but are mentioned here for context only. A. Remove the association of the Requirement class from the MonolithicDeploymentDescription and ArtifactDeploymentDescription and PlanConnectionDescription classes since they are not now needed and just add clutter? B. Clarify and define that the function returned by the "entry point" of the implementation artifact conforms to this local (pseudo) IDL to provide portability of implementations. This may in fact be documented as an example that shows how all the information is used if we can't agree to fix portability. Possible interface (widen window to view this indented html properly): // Base class used by all artifacts whether "primary" or not. local interface ImplementationArtifact { void initialize(// from ImplementationArtifactDescription: execParams in Strings execParams, // from ArtificatDeploymentDescription: deployedResources in ResourceDeploymentDescriptions artifactResources // from plan ); } // Class implemented by brimary artifacts (constructors). local interface PrimaryImplementationArtifact : ImplementationArtifact { Object create(// from ComponentInterfaceDescription: specificType in String interfaceName, // from MonolithicImplementationDescription: execParams in Strings execParams, // from various in Properties configProperties, // from InstanceDeploymentDescription: deployedResources in InstanceResourceDeploymentDescriptions instanceResources // for each resource with kind ResourceUsesInstance out Objects providedReferences ); void destroy(in Object); ); 260-429-5060 Fax