Issues for Mailing list of the Reusable Asset Specification Finalization Task Force

List of issues (green=resolved, yellow=pending Board vote, red=unresolved)

List options: All ; Open Issues only; or Closed Issues only

Issue 7759: Reintroduce metamodel for Classification Schemas
Issue 7760: Remove Descriptor Groups
Issue 7761: Allow Models to be referenced from Assets and avoid duplicating UML
Issue 7762: Incomplete metamodel for RAS Profile
Issue 7763: Constraint 13 should be a compliance point
Issue 7764: Provide standard means of identifying manifests
Issue 7765: Unnecessary requirement to reference the physical schema file
Issue 7766: Lack of clarity of 'globally unique' for ids
Issue 7767: Make DependencyType an element in its own right
Issue 7901: a RAS EJB Component profile
Issue 7907: RAS FTF issue --conformance clause
Issue 8211: RAS FTF: add chapter to describe RAS profile extension
Issue 8212: RAS FTF: add support for Activity Parameters
Issue 8281: Issue with RAS ptc/04-06-06 ID History in Defaultprofile
Issue 8282: Issue with RAS ptc/04-06-06 Element Order in profiles
Issue 8287: RAS FTF: remove the Java API Descriptions section
Issue 8288: RAS FTF: update the Http Request / Response Description section
Issue 8289: RAS FTF: order of id-history inconsistent
Issue 8290: RAS FTF: nesting DescriptorGroup and Descriptor
Issue 8520: replace string artifact reference with artifact reference
Issue 8521: string attribute for description with reference to Description class
Issue 8522: missing Asset id attribute
Issue 8523: webservice profile incorrect connection with component profile
Issue 8524: refine constraint to include .xsd file in .ras file
Issue 8525: add assetVersion attribute to RelatedAsset
Issue 8526: add text to spec/appendix describing translation of submitted Rose models
Issue 8563: create a chapter or section in RAS document describing profile extension
Issue 8564: add two people to 6.3 acknowledgements section in the RAS doc
Issue 8565: RAS FTF: manifest file must reference XML schema
Issue 8566: RAS FTF: improper use reference to id attributes for element relationships
Issue 8597: RAS FTF: RAS docs need version number updated

Issue 7759: Reintroduce metamodel for Classification Schemas (ras-ftf)

Though it is useful to have the flexibility of referring to external
schemas, it leaves no standard means of defining the schemas: RAS should
re-introduce the metamodel for Classification Schemas that was in RAS
1.x, allowing for the definition of Free-form or Enumeration
Descriptors. Additionally it should be possible to define the nodes for
an Enumeration Descriptor as 'exclusive' (allowing an asset to have only
one from the set), and there should be a proper containment mechanism
(so that when the schema is deleted all its nodes etc are also deleted).

Ought to consider inheriting DescriptorGroup from ClassificationSchema, and keep the link back from DescriptorGroup to ClassificationSchema so that where a descriptor group is grouping nodes from another formal schema, in fact this principle could be applied at the schema level. But for more flexibility a single descriptor group can be used to collect together classifications for a single object, regardless of where the nodes have been originally classified. This means that the link between DescriptorGroup and Descriptor can be broken in favor of the link between Descriptor and ClassificationSchema

These provide an unwarranted overhead to classifying objects both in
terms of storage and processing: for example rather than just adding a
Descriptor to an Asset's Classification, one has first to check if there
is an appropriate DescriptorGroup and add it or link to it. Similarly
when removing a Descriptor one needs to check if the DescriptorGroup is
now empty and then remove it. This is very tricky if one is performing
the update via XMI import.
Moreover there is redundancy and the possibility of inconsistency with
the DescriptorGroup referring to a Context and its contained Descriptors
also referencing a Context.


Proposed resolution: 
Delete DescriptorGroup.
Link Descriptor directly to Classification.
Move the 'reference' property from DescriptorGroup to Descriptor: this
adds a bit of overhead to each Descriptor but on the other hand provides
more power in allowing a proper definition of the specific Descriptor to
be referenced. This reference also allows the Descriptors to be grouped
in practice (e.g. for display purposes).

Similarly when removing a Descriptor one needs to check if the DescriptorGroup is now empty and then remove it. This is very tricky if one is performing the update via XMI import. Moreover there is redundancy and the possibility of inconsistency with the DescriptorGroup referring to a Context and its contained Descriptors also referencing a Context.
Proposed resolution: 
Delete DescriptorGroup and Link Descriptor directly to Classification.
Move the 'reference' property from DescriptorGroup to Descriptor: this adds a bit of overhead to each Descriptor but on the other hand provides more power in allowing a proper definition of the specific Descriptor to be referenced. This reference also allows the Descriptors to be grouped in practice (e.g. for display purposes).

It's not at all clear how to use RAS to reference UML (or other) models
which might represent the design of a component, or might be reusable
assets in their own right - despite the fact that the Model may be in
the same repository as the RAS Asset definition!
The description of Artifact (in Section 2.4.10.1 of the RFC) clearly
implies that an Artifact must be (or refer to) a file: while it would be
possible to export a Model as a XMI file and reference it, this
dramatically reduces the possibility of proper management, editing and
impact analysis of the modeling elements, and should only be required
for physical interchange purposes. In fact requiring models to be
instantiated in XMI files ironically works against the reuse of the
model elements (e.g. common classes reused in the design of multiple
components).
The RAS Profile mechanism seems to require the construction of new
RAS-specific metamodels and does not seem readily to allow the re-use of
existing metamodels, models and tools such as UML.
For example, a more sensible approach for support of John Cheesman's
Component book would be to use a UML Profile (as indeed he does in the
book!) and allow the top level package to be linked to the Asset.
Similarly the UML Diagram Interchange standard already has a metamodel
for Diagrams (linked to model elements) so why create another
representation here?


Proposed resolution:
Allow artifacts to reference arbitrary model elements (this can be
achieved through an association to Reflective::Object which is the
implicit superclass of every class in a MOF 2 metamodel).
Allow a RAS Profile to refer to a Package (representing a metamodel or
UML Profile) rather than having to create its own metamodel.

Proposed resolution: Allow artifacts to reference arbitrary model elements (this can be achieved through an association to Reflective::Object which is the implicit superclass of every class in a MOF 2 metamodel). Allow a RAS Profile to refer to a Package (representing a metamodel or UML Profile) rather than having to create its own metamodel.

The metamodel for RAS Profile omits most of the aspects included in the
specification of the specific profiles contained in the specification:
for example the Profile from which it is derived, the list of classes
and attributes (required or optional) and constraints.

Constraint 13 in section 2.4.14 of RFC "Tool vendors must provide
processing for at least one primary artifact type." should be a
compliance point not a constraint on the metamodel.

The statement in 2.3 1 of RFC "it is up to any tool or the user to
determine which files in the package are manifest files and which are
artifacts of the asset." is unacceptable for interchange purposes

P20 of RFC states "The actual filename may vary for the profile file,
but the XML instance documents must reference the schema file." (and
refers to xsi:schemaLocation) This is out of step with common practice
for XML: surely the only thing required is the URI of the Schema via
xmlns.

Para 2 of 2.4.6 in RFC states that "the id attribute is expected to
contain a globally unique identifier": the meaning and scope of
'globally' should be clarified.
In particular, since later in the section when discussing the 'version'
attribute it is implied that 2 versions of the 'same' asset may have the
same id.
References to use of XMI for generating id are certainly not correct
since xmi:ids are unique only within the scope if a single XMI file, and
may differ for the same element in different files.

At the moment dependencyType is just a string associated with
ArtifactDependency (in 2.4.10.1 of RFC): this provides no control or
impact analysis or consistency. DependencyKind (better name for
consistency with other specifications) should be an element in its own
right, and it should be possible to associate it with a Profile (e.g..
the Component Profile will introduce new types of Dependency). 

Create a primitive type called DependencyKind, as shown below.
 

The Japan EJB Consortium would like to add a RAS EJB Component profile as an example extension in the Appendix of the RAS "final" report. 

In the conformance clause, for each conformance point provide cross reference to normative clauses that must be implemented in order to satisfy the conformance point

We propose that we vote to defer this issue

Need to add a chapter to the specification document which describes techniques for doing extensions to RAS profiles. There are two major sections to this chapter to consider initially; first, describe how to create Rose models to extend the RAS profile using the MOF modeling conventions and second, describe the creation of the genmodel/ecore EMF files from which the RAS XSD file and Java API are produced. 

Default Profile Change Request: Activity Parameters


Table of Contents
1.        Introduction        4 

2.        References        4 

3.        Design Requirements        4 

4.        Design Constraints        4 

5.        Issues        4 

5.1        Specifying parameters for an Activity is very difficult        4 
5.1.1        Description        4 

6.        Considered Approaches        4 

6.1        Preferred Approach - Add class ActivityParameter to the metamodel        4 
6.1.1        Description        4 
6.1.2        Pros        5 
6.1.3        Cons        5 
6.2        Alternate Approach 1 – Include the Parameters in an Activity attribute        5 
6.2.1        Description        5 
6.2.2        Pros        5 
6.2.3        Cons        5 
6.3        Alternate Approach 2 – Expand the class VariabilityPointBinding        5 
6.3.1        Description        5 
6.3.2        Pros        6 
6.3.3        Cons        6 

7.        Design Artifacts        6 

7.1        Figure 1        6 
7.2        Figure 2        7 
7.3        Figure 3        7 
7.4        Example 1        8 

8.        Future Considerations        9 

9.        Draft Reviews Threads        9 


 



1.        Introduction 

This document describes the issues the RAS Aurora Program development team has experienced while trying to write tooling to effectively exploit the activity element in the RAS default profile.  It also contains a proposal to help alleviate these issues. 

2.        References 
·        Reusable Asset Specification(04-06-06.pdf) 

3.        Design Requirements 
·        Provide a mechanism to easily associate parameters with an activity 
·        Concretely define the relationship between activities and their parameters at the metamodel level 
4.        Design Constraints 
·        Require only minor changes to the current default profile metamodel 
5.        Issues 

5.1        Specifying parameters for an Activity is very difficult 
5.1.1        Description 

It’s quite common to include asset or artifact activities in a RAS manifest that are interrogated by clients during some part of the asset’s lifecycle.   Often the activity requires additional pieces of information that’s used by the client to help execute the activity in one manner or another during processing.  For example, IBM’s Eclipse based RAS implementation provides an activity to build a deployable project that’s processed during asset packaging.  The RAS manifest author has the option to build that project with or without source and package the binaries in different formats.  In today’s default profile metamodel, there doesn’t appear to be a clear, simple way to specify the options.  Ideally the metamodel should provide a way to express the parameters for an activity in an unambiguous way.  Below are a few approaches we considered including a preferred approach to resolving this issue.  We are open to other suggestions as well. 

6.        Considered Approaches 
6.1        Preferred Approach - Add class ActivityParameter to the metamodel 

6.1.1        Description 
Our preferred approach is to add a new class called ActivityParameter to the metamodel for the default profile that extends the class Descriptor.  This new class would contain one attribute named defaultValue that would provide the ability to specify for the parameter exactly what the name implies…a default value.  The name and value attributes inherited from the Descriptor class would provide the mechanism for defining the parameters and their values.  See Figure 1 and Example 1. 

6.1.2        Pros 

·        Concretely defines the relationship between activities and their parameters in a clear, straight forward manner.   
·        Client will not have to interrogate the attributes of other elements to try to determine if they are the parameters for activity. 
·        The parameters will not have to be included in one of the attributes of the activity. 

6.1.3        Cons 

·        New class and relationships must be added to the metamodel 

6.2        Alternate Approach 1 – Include the Parameters in an Activity attribute 

6.2.1        Description 
Include the parameters as part of one of the existing activity attributes.  Use special characters to denote the parameters and their values so that they can be specified and accessed by clients. 

6.2.2        Pros 

·        Requires no changes to the current default profile metamodel 

6.2.3        Cons 

·        No clear relationship between the activity and the parameters 
·        Adds confusing extraneous information to activity attributes that doesn’t apply to the attribute. 
·        Clients must know which attribute contains the parameters and how to specify/access them 



6.3        Alternate Approach 2 – Expand the class VariabilityPointBinding 

6.3.1        Description 
Add a new attribute to the class VariabilityPointBinding.  This will provide a way to associate the parameters with the activity using an existing metamodel relationship.  See Figure 2 or Figure 3..   

6.3.2        Pros 

·        Requires no new classes to be added to the metamodel 
·        Provides a mechanism to associate parameters to an activity through an existing relationship. 

6.3.3        Cons 

·        No clear relationship between the activity and the parameters.  The binding rules will have to be interrogated to find a particular binding rule and then process it. 
·        Using the VariabilityPointBinding class for this purpose doesn’t really seem like what the intended purpose is according to the RAS spec.  It’s tied to a VariabilityPoint which doesn’t necessarily apply. 
·        A new attribute must be added to the VariabilityPointBinding class. 


7.        Design Artifacts 

7.1        Figure 1 
 

7.2        Figure 2 

 

7.3        Figure 3 

 
7.4        Example 1 

An example expansion of the XML in a RAS manifest for an activity with parameters for the preferred solution: 

<artifactActivity artifact="//@solution/@artifact.0"> 
<activity task="Build Deployable Project" role="com.ibm.xtools.ras.export" taskType="com.ibm.xtools.ras.BuildDeployableProject"> 
  <activityParameter name="includeSource" value="true" defaultValue="false" /> 
  </activity> 
</artifactActivity> 



Thanks,
Grant

-----------------------------------------------------------
Grant Larsen
STSM
IBM Rational software
   Voice:    (303) 932-7368 
   Mobile:  (303) 601-1257
   Fax:        (303) 932-6963
   Notes:    Grant J Larsen/Denver/IBM
   E-mail:   gjlarsen@us.ibm.com 



 RAS FTF add support for Activi.gif 
 RAS FTF add support for Activi1.gif 
 RAS FTF add support for Activi2.gif

Default Profile Issue:


The RAS specification states that for profile histories the new profile’s
ID is prepended to the previous ID/history.  It appears that this is
backwards in the default profile.  Either the RAS specification or the
Defaultprofile needs to be corrected.

Associated Profiles:


In all of the profiles, the association order and property order shown in
the annotations does not match the order shown in each element.  For
example, in the Defaultprofile, the Asset Element order shown is
classification, solution, usage, related asset, profile and description
while the order listed in the annotation is profile, description,
classification, solution, usage and related asset.

The Java API Description section (5.2) should be removed from the RAS document. The Http Request / Response Description should be preserved and should represent the interface to the RAS repository

The Http Request / Response Description section should be updated with services interfaces that have been discovered/refined from tooling efforts since the original RAS submission.

There are several places in the RFC document which alters the order of the concatenated ids for the profiles in the id-history attribute. 

The document needs to be consistent; the order is: 

grandfather profile_id::father profile_id::child profile_id 

It goes from least derived on the left to most derived on the right. 

The current structure of DescriptorGroup and Descriptor provides for only one level in the scheme for classifying assets. The DescriptorGroup and Descriptor classes should be updated to allow nesting of these classes. This allows for simple classification schemes to be represented in the asset manifest files. 

Convert every place that used a string reference representing an artifact to be an actual reference to the Artifact class/element in the Solution class/element. 

Pros: 
Providing the ability to include a lot more information about that artifact than simply how to locate it using the reference.  You now have an actual Artifact element that can be interrogated for information. 
Allows us to apply the Visitor pattern to our Java implementation making it incredibly easy and flexible for a client to visit the artifacts in the asset independent of where they are located or how they are structured. Third parties can also tie into this so that we visit all their artifacts in custom profiles as well. 

Cons: 
This opens up the possibility of additional broken references if someone deletes the artifact that a given element was referring to. 

Classes/Elements affected: 
ArtifactActivity 
DescriptorGroup 
Profile 
RelatedAsset 
RelatedProfile 
Usage 
VariabilityPoint 

Discussion:
Provide the ability to include more information about the Artifact than simply how to locate it using the reference. You now have an actual Artifact element that can be interrogated for information.
Allows us to apply the Visitor pattern to our Java implementation making it incredibly easy and flexible for a client to visit the artifacts in the asset independent of where they are located or how they are structured. Third parties can also tie into this so that we visit all their artifacts in custom profiles as well.
Classes/Elements affected:
Activity
DescriptorGroup
Profile
RelatedAsset
RelatedProfile
Usage
VariabilityPoint
The image below shows the proposed model for each of the items in the list above.
 

Convert every place in all profiles that used a string attribute representing a description to be a reference to a Description class/element. 

Elements affected: 
Condition 
InterfaceSpec(Component profile) 
Operation 
RelatedAsset 
VariabilityPoint 

Discussion:
Create associations from the affected classes to the Descriptor class. Remove any "description" attributes.
Elements affected:
Default Profile
Descriptor
Reference
ReferenceKind
RelatedAsset
VariabilityPoint
Default Component Profile
Condition
InterfaceSpec
Operation

Default Profile Classes
 
Default Component Profile Classes
 
Resolution:

The RAS2.1_defaultprofile_target_MOFXMIXMLSchema.mdl doesn't have an id attribute for the Asset element.   The text of the spec clearly indicates that it should exist... 

"This Asset instance defines the identity of the reusable software asset (see Asset Identity section). This Asset instance contains two required attributes; name and id. For the XMI XML schema the id does not appear in the model as it relies on the XMI generator to produce it." 

We think what happened is that when all the other old id attributes were removed when preparing the MOF/XMI version of RAS...this one was also accidentally removed. This needs to be added back into the model. 

Elements affected: 
Asset 

Section 7.7.5 of the spec related to the RAS webservice profile indicates that there is still a relationship between RAS component and RAS webservice profiles. 

"Only the new elements for this profile are outlined here. For information on other elements refer to this profile's ancestry, namely the Default Component profile and the Default profile." 

This is no longer true...but more importantly however...is the fact that the current webservice profile ID still includes the component's profile ID in it's parent chain. The text in the spec needs to be updated remove association and the id history for the webservice profile needs to be updated to remove the connection to the component profile. 

We propose to update the Profile.id-history attribute as follows. 

Current webservice profile id-history: 
F1C842AD-CE85-4261-ACA7-178C457018A1::31E5BFBF-B16E-4253-8037-98D70D07F35F::1025A790-78D4-4f57-94CE-E65B23275FCD::710CA9C5-CA9C-4be2-BB1A-D23677C62A4C 

Revised webservice profile id-history, after removing the Component profile id from the id-history: 
F1C842AD-CE85-4261-ACA7-178C457018A1::31E5BFBF-B16E-4253-8037-98D70D07F35F:: 710CA9C5-CA9C-4be2-BB1A-D23677C62A4C 

In section 8.1 Mapping RAS to .ras files, it indicates that the RAS asset should include the .xsd file for the profile... 

"Each .ras file includes the following types of files: 
• one XML Schema file (e.g., RASProfile.xsd ) 
• one manifest file (e.g., rasset.xml) 
• one or more artifact files (e.g., source code, models, test scripts, and so on)" 

We no longer include the .xsd file(s) in our packaged assets like XDE did.  If we do...it will be potentially more than one based on the profile being used.  We either need to start including this in today's RAS implementation or remove this from the spec.  I'm also pretty sure our .rmd files would not always validate in all circumstances against the minimum constraints the spec indicates the .xsd would enforce.  Not positive on this yet though...need to investigate some more. 

Proposal: 
In section 8.1, change text to: 
zero or more XML Schema files (e.g., RASProfile.xsd ) 

Resolution:
In section 8.1, change text to:
zero or more XML Schema files (e.g., RASProfile.xsd )

Currently the RelatedAsset class/element only contains the id of the related asset.  This is fine if the related asset relationship type is aggregation because the related asset has a reference to the actual artifact that represents the asset.  We need to support loosely coupled asset relationships where you don't have a direct reference to the related asset but instead some rules of where to search for it.  In this scenario, we need more information to uniquely identify the asset.  Specifically...we need the version of the related asset.  We'd like to add an assetVersion attribute to the RelatedAsset element to match the assetId attribute that already exists.  We think this provide us the information we would need for this loose coupling. 

On items such as “value” attributes on classes there is not a direct translation from the Rose model thru the EMF translators. There is no way to map the text element in the XML form to the Rose model elements. We need to describe the manual steps to create the XML schema from the Rose model.

The RAS document needs to be updated with a section describing profile extension in a non-vendor specific manner. Vendor-specific extensions should not be included in the RAS document. 

Per the voting in the affirmative on issue 8211 this issue is being submitted. 

Discussion:
Section 7.4.8 contains a summary of profiles and the semantics for extending them. This section should remain agnostic of any specific vendor's implementation and should not be included in the RAS document. As such this section should be updated to reflect changes caused by other issues and address grammatical issues.

Please add these two people that have contributed significantly to the RAS since the original submission, namely Neil Boyette (IBM), Don Weinand (IBM).

On page 49 of the RAS document it states 

Constraint 1: The manifest file must validate against the XML Schema associated with the profile and must be referenced by the manifest file. 

We propose that this should be changed to: 

Constraint 1: The manifest file must validate against the XML Schema associated with the profile. 

The original RAS XML schema used id attributes as a way to create associations amongst elements. However, the MOF/XMI version of XML schema removes this requirement and allows for associations amongst elements. Several constraints in section 7.4.14 are affected by this. 
Constraint 4: The context-id attribute in the <artifact-context>, <descriptor>, <artifact-dependency>, <variability-point>, <context-ref> and <artifact-activity> element must specify an id from a context element found in the same manifest document. 
Constraint 5: The artifact-id attribute in the <artifact-activity>, and <artifact-dependency> elements must specify an id from an <artifact> element found in the same manifest document. 
Constraint 6: The variability-point-id attribute of the <variability-point-binding> element must specify an id from a <variability-point> element found in the same manifest document. 
Constraint 11: The artifact-id attribute on an <artifact-dependency> element and <artifact-activity> element must use an id from an <artifact> element in the same document. 

We propose to update the text for these constraints to say that element "X" should reference another element, "Y", in the same document. 

The RAS documents need to be updated to reflect version 2.2 for the final specification