Issue 6877: UML2 super/notation/Keywords (uml2-superstructure-ftf) Source: Adaptive (Mr. Pete Rivett, pete.rivett(at)adaptive.com) Nature: Uncategorized Issue Severity: Summary: This is a general issue that is quite pervasive. I think it is important enough to be considered by the FTF. The specification is littered with keywords which are used on diagrams to indicate various things. What the specification sorely needs is an Appendix that gathers them all together. And cross-references each with where it is defined and the compliance level it is associated with. Also what it needs is a general description of the semantics of keywords, how they differ from 'Standard Stereotypes' and associated constraints - e.g. it should not be allowed to declare a Stereotype with a name which, when decapitalized, is the same as a keyword (since they'd be indistinguishable). Arguably keywords would be depicted with a distinct notation from stereotypes (based on language design principles and to help users interpret diagrams where they see words in guillemets and don't know whether to look it up in the list of keywords or stereotypes) but that is probably too major a change to make at this stage. However the notation should be clarified to cover the following cases: A) if the same element requires a keyword and has a stereotype applied are they shown in 2 separate <<xxx>> expressions or in one, separated by a comma? B) if a stereotype is applied to a class normally indicated by a keyword, does that keyword still need to be provided? Resolution: see above Revised Text: Actions taken: January 8, 2004: received issue March 8, 2005: closed issue Discussion: The following changes are proposed to resolve this issue: 1. On page 585, insert a new appendix (Appendix B: UML Keywords) in the list of appendices 2. Create a new appendix (Appendix B), between the current appendices A and B that explains what keywords are and provides a list and a brief description of each as follows: Appendix B. UML Keywords UML keywords are reserved words that are an integral part of the UML notation and normally appear as text annotations attached to a UML graphic element or as part of a text line in a UML diagram. These words have special significance in the context in which they are defined and, therefore, cannot be used to name user-defined model elements where such naming would result in ambiguous interpretation of the model. For example, the keyword “trace” is a system-defined stereotype of Abstraction (see Appendix C) and, therefore, cannot be used to define any user-defined stereotype. In UML, keywords are used for four different purposes: ?? To distinguish a particular UML concept (metaclass) from others shring the same general graphical form. For instance, the «interface» keyword in the header box of a classifier rectangle is used to distinguish an Interface from other kinds of Classifiers. ?? To distinguish a particular kind of relationship between UML concepts (metaassociation) from other relationships sharing the same general graphical form. For example, dashed lines between elements are used for a number of different relationships, including Dependencies, relationships between UseCases and an extending UseCases, and so on. ?? To specify the value of some modifier attached to a UML concept (meta-attribute value). Thus, the keyword «singleExecution» appearing within an Activity signifies that the “isSingleExecution” attribute of that Activity is true. ?? To indicate a Standard Stereotype (see Appendix C). For example, the «modelLibrary» keyword attached to a package identifies that the package contains a set of model elements intended to be shared by multiple models. Keywords are always enclosed in guillemets («keyword») which serve as visual cues to more readily distinguish when a keyword is being used. (Note that guillemets are a special kind of quotation marks and should not to be confused with or replaced by duplicated “greater than” (>>) or “less than” (<<) symbols, except in situations where the available character set may not include guillemets.) In additio n to identifying keywords, guillemets are also used to distinguish the usage of stereotypes defined in user profiles. This means that: a) Not all words appearing between guillemets are necessarily keywords (i.e., reserved words) and, b) Words appearing in guillemets do not necessarily represent stereotypes. If multiple keywords and/or stereotype names apply to the same model element, they all appear between the same pair of guillemets, separated by commas: “«” <label> [“,” <label>]* “»” where <label> ::= <keyword> | <stereotype-label> Keywords are context sensitive and, in a few cases, the same keyword is used for different purposes in different contexts. For instance, the «create» keyword can appear next to an operation name to indicate that it as a constructor operation, and it can also be used to label a Usage dependency between two Classes to indicate that one Class creates instances of the other. This means that it is possible in principle to use a keyword for a user-defined stereotype (provided that it is used in a context that does not conflict with the keyword context). However, such practices are discouraged since they are likely to lead to confusion. The keywords currently defined as part of standard UML are specified in Table XXX below, sorted in alphabetical order. The following is the interpretation of the individual columns in this table: ?? Keyword provides the exact spelling of the keyword (without the guillemets) ?? Language Unit identifies the language unit in which the keyword is defined (and, implicitly, the chapter in which the keyword is described) ?? Metamodel Element specifies the element of the UML metamodel (either a metaclass or a metaclass feature) that the keyword denotes ?? Semantics gives a brief description of the semantics of the keyword (see further explanations below); more detailed explanations are provided in the Notation sections of the corresponding metaclass description. The following formats are used 1. If the entry contains the name of a UML metaclass, this indicates that the keyword is simply used to identify the corresponding metaclass. 2. If the entry is a constraint (usually but not necessarily an OCL expression), it specifies a constraint that applies to metamodel elements that are tagged with that keyword. 3. If the entry is in the form“standard stereotype:L<x>”, where <x> = 1, 2, or 3, it means that the keyword represents a stereotype that is defined at compliance level. In those cases, the more detailed description of the semantics can be found in Appendix C. ?? Notation Placement indicates where the keyword appears (see further explanations below). The following conventions are used to specify the notation placement: 1. “box header” means that the keyword appears in the name compartment of a classifier rectangle 2. “list box header” means that the keyword is used as a header on a list box appearing as part of a classifier specification 3. “dashed line label” means that the keyword is used to as a label on some dashed line, such as a Dependency. 4. “in- line label” means that the keyword appears as part of a text line (usually at the front), such as an attribute definition 5. “between braces” means that the keyword appears between “curly” brackets (similar to the constraint notation) and is used to select the value of some property of a metaclass . Table XXX. UML keywords Keyword Language Unit Metamodel Element Semantics Notation Placement abstraction Classes Abstraction Abstraction box header access Classes PackageImport not (visibility = #public) dashed line label activity Activities Activity Activity box header actor Use Cases Actor Actor box header apply Profiles ProfileApplication Package::appliedProfile ->collect(ap | ap.importedProfile) dashed line label artifact Deployments Artifact Artifact box header artifacts Deployments Component list box header attribute Activities ActivityPartition ::represents ActivityPartition ::represents->forAll(r | r.oclIsKindOf(Property)) swimlane header auxiliary Classes Classifier standard stereotype:L1 box header buildcomponent Components Component standard stereotype:L3 box header call Classes Usage standard stereotype:L1 dashed line label centralBuffer Activities CentralBufferNode CentralBufferNode box header class Activities ActivityPartition ::represents Activitypartition ::represents->forAll(r | r.oclIsKindOf(Class)) swimlane header component Components Component Component box header create Classes Usage standard stereotype:L1 dashed line label create Classes BehavioralFeature standard stereotype:L1 (constructor) in-line label on operation create CompositeStructures Dependency Applies only to dependencies between an InstanceSpec and Parameter of an operation, indicating a return parameter of an Operation that is a constructor dashed line label datastore Activities DataStoreNode DataStoreNode box header datatype Classes DataType DataType box header delegate Components Connector Connector::kind = #delegation connector label deploy Deployments Connector delegation connector dashed line label deployment spec Deployments DeploymentSpecification Deploy mentSpecification box header derive Classes Abstraction standard stereotype:L1 dashed line label destroy Classes BehavioralFeature standard stereotype:L1 in-line label on operation device Deployments Device Device box header document Deployments Artifact standard stereotype:L2 box header element access Classes ElementImport not (visibility = #public) dashed line label element import Classes ElementImport visibility = #public dashed line label entity Components Component standard stereotype:L2 (business concept) box header enumeration Classes Enumeration Enumeration box header executable Deployments Artifact standard stereotype:L2 box header executionEnviron ment Deployments ExecutionEnvironment ExecutionEnvironment box header extend Use Cases Extend Extend dashed line label extended State Machines Region Region::extendedRegion ->notEmpty() between braces extended State Machines StateMachine StateMachine ::redefinedBehavior -> notEmpty() between braces external Activities ActivityPartition ActivityPartition ::isExternal = true swimlane header file Deployments Artifact standard stereotype:L2 box header focus Classes Class standard stereotype:L1 box header framework Classes Package standard stereotype:L1 box header from Common Behaviors Trigger to show port name in expression implement Components Component standard stereotype:L1 box header implementationCl ass Classes Class standard stereotype:L1 box header import Classes PackageImport visibility = #public dashed line label include Use Cases Include Include dashed line label information Auxiliary::Informatio nFlows InformationItem InformationItem box header instantiate Classes Dependency Dependency dashed line label instantiate Classes Usage standard stereotype:L1 dashed line label interface Classes Interface Interface box header library Deployments Artifact standard stereotype:L2 box header localPostconditio n Actions Constraint Action::localPostcondition box header localPrecondition Actions Constraint Action::localPrecondition box header manifest Deployments Manifestation Manifestation dashed line label merge Classes PackageMerge PackageMerge dashed line label metaclass Profiles Classifier metaclass being stereotyped box header metamodel Auxiliary::Models Model standard stereotype:L3 box header model Auxiliary::Models Model Model box header modelLibrary Classes Package standard stereotype:L1 box header multicast Activities ObjectFlow ObjectFlow::isMulticast flow label multireceive Activities ObjectFlow ObjectFlow ::isMultireceive flow label occurrence Composite Structures Collaboration (Behavior::context) from a Collaboration to the owning BehavioredClassifier, indicating that the collaboration represents the use of a classifier dashed line label postcondition Activities Constraint Behavior::postcondition box header precondition Activities Constraint Behavior::precondition box header primitive Classes PrimitiveType PrimitiveType box header process Components Component standard stereotype:L2 box header profile Profiles Profile Profile box header provided interfaces Components Component Component::provided list box header realization Classes Classifier standard stereotype:L2 box header realizations Components Component Component ::realizations->collect(r | r.realizingClassifier) list box header refine Classes Abstraction standard stereotype:L1 dashed line label representation Auxiliary::Informatio nFlows Classifier InformationFlow ::conveyed dashed line label represents Composite Structures Collaboration (Behavior::context) from a Collaboration to the owning BehavioredClassifier; collab. Is USED in the classifier dashed line label required interfaces Components Component Component::required list box header responsibility Classes Usage standard stereotype:L1 dashed line label script Deployments Artifact standard stereotype:L1 box header selection Activities Behavior ObjectFlow::selection box header selection Activities Behavior ObjectNode::selection box header send Classes Usage standard stereotype:L1 dashed line label service Components Component standard stereotype:L2 box header signal Common Behaviors Signal Signal box header singleExecution Activities Activity Activity ::isSingleExecution = true inside box source Deployments Artifact standard stereotype:L2 box header specification Components Classifier standard stereotype:L2 box header statemachine State Machines BehavioredClassifier:: ownedBehavior BehavioredClassifier ::ownedBehavior. oclIsKindOf( StateMachine) box header stereotype Profiles Stereotype Stereotype box header structured Activities StructuredActivityNode StructuredActivityNode box header substitute Classes Substitution Substitution dashed line label subsystem Components Component standard stereotype:L2 box header systemModel Auxiliary::Models Model standard stereotype:L3 box header trace Classes Abstraction standard stereotype:L1 dashed line label transformation Activities Behavior ObjectFlow ::transformation box header type Classes Class standard stereotype:L1 box header use Classes Usage Usage dashed line label utility Classes Class standard stereotype:L1 box header End of Annotations:===== ubject: UML2 super/notation/Keywords Date: Thu, 8 Jan 2004 08:01:55 -0500 X-MS-Has-Attach: X-MS-TNEF-Correlator: Thread-Topic: UML2 super/notation/Keywords Thread-Index: AcPV5xRU3hwwKlJNR5+Nlts0u1qfpw== From: "Pete Rivett" To: X-MIME-Autoconverted: from quoted-printable to 8bit by amethyst.omg.org id i08Cs3v6009674 This is a general issue that is quite pervasive. I think it is important enough to be considered by the FTF. The specification is littered with keywords which are used on diagrams to indicate various things. What the specification sorely needs is an Appendix that gathers them all together. And cross-references each with where it is defined and the compliance level it is associated with. Also what it needs is a general description of the semantics of keywords, how they differ from 'Standard Stereotypes' and associated constraints - e.g. it should not be allowed to declare a Stereotype with a name which, when decapitalized, is the same as a keyword (since they'd be indistinguishable). Arguably keywords would be depicted with a distinct notation from stereotypes (based on language design principles and to help users interpret diagrams where they see words in guillemets and don't know whether to look it up in the list of keywords or stereotypes) but that is probably too major a change to make at this stage. However the notation should be clarified to cover the following cases: A) if the same element requires a keyword and has a stereotype applied are they shown in 2 separate <> expressions or in one, separated by a comma? B) if a stereotype is applied to a class normally indicated by a keyword, does that keyword still need to be provided? Pete Rivett (mailto:pete.rivett@adaptive.com) Consulting Architect, Adaptive Inc. Dean Park House, 8-10 Dean Park Crescent, Bournemouth, BH1 1HL, UK Tel: +44 (0)1202 449419 Fax: +44 (0)1202 449448 To: uml2-superstructure-ftf@omg.org Cc: mu2i-ftf@omg.org Subject: Standard Profile resolution X-Mailer: Lotus Notes Release 6.0.1CF1 March 04, 2003 From: Branislav Selic Date: Wed, 22 Sep 2004 08:29:10 -0400 X-MIMETrack: Serialize by Router on D25ML01/25/M/IBM(Release 6.0.2CF2|July 23, 2003) at 09/22/2004 08:29:13, Serialize complete at 09/22/2004 08:29:13 Issue 6877, raised by Pete, complains about how the so-called "standard UML profile" is defined in the spec currently. Specifically, it says: is there actually a Profile object (or objects) that contains these stereotypes? Can users consider this Profile already applied to any UML model or does it have to be explicitly done or is this a variation point? My proposal for dealing with these issues is summarized below -- please complain if you do not approve: Because there are presently three groups of stereotypes, corresponding to the L1, L2, and L3 compliance levels, I suggest that we have 3 separate "standard profiles", one for each compliance level. There is nothing "automatic" about how these profiles are used. This means that users who want to use these profiles, they have to be declared explicitly in the "appliedProfiles" list of the user model. This is the same as for any other profile that is applied to a model The profile definition is not a part of the UML metamodel, since, by definition, profile definitions occur at M1. However, I don't think we need to actually include a model of each standard profile with the spec. I feel that the added value of such a model over the current textual description is minimal and will only add bulk with diagrams that repeat graphically what the current appendix already says in more detail (NB: I do plan to add some minor touch ups to the current definitions as suggested in the issue). If there are no major grievances with the above approach, I will publish a draft resolution tomorrow. Thanks...Bran Subject: RE: Standard Profile resolution Date: Fri, 24 Sep 2004 08:24:02 -0400 X-MS-Has-Attach: X-MS-TNEF-Correlator: Thread-Topic: Standard Profile resolution Thread-Index: AcSgoXkQgw0At1ygTMOXuO58zQb3cgBja86g From: "Pete Rivett" To: "Branislav Selic" , Cc: X-Virus-Scanned: by amavisd-new at sentraliant.com I agree with the proposal and agree that the Profiles are not part of the metamodel but think that we should create separate XMI file(s) containing the Profile definitions (as UML models at M1 level) - otherwise there's no definitive version and each tool vendor will end up creating it themselves - possibly with inconsistencies. These XMI files do not need to contain the diagrams (they will be UML XMI without Diagram Interchange XMI). Pete Pete Rivett (mailto:pete.rivett@adaptive.com) Chief Scientist, Adaptive Inc. Dean Park House, 8-10 Dean Park Crescent, Bournemouth, BH1 1HL, UK Tel: +44 (0)1202 449419 Fax: +44 (0)1202 449448 http://www.adaptive.com -------------------------------------------------------------------------------- From: Branislav Selic [mailto:bselic@ca.ibm.com] Sent: Wednesday, September 22, 2004 1:29 PM To: uml2-superstructure-ftf@omg.org Cc: mu2i-ftf@omg.org Subject: Standard Profile resolution Issue 6877, raised by Pete, complains about how the so-called "standard UML profile" is defined in the spec currently. Specifically, it says: is there actually a Profile object (or objects) that contains these stereotypes? Can users consider this Profile already applied to any UML model or does it have to be explicitly done or is this a variation point? My proposal for dealing with these issues is summarized below -- please complain if you do not approve: Because there are presently three groups of stereotypes, corresponding to the L1, L2, and L3 compliance levels, I suggest that we have 3 separate "standard profiles", one for each compliance level. There is nothing "automatic" about how these profiles are used. This means that users who want to use these profiles, they have to be declared explicitly in the "appliedProfiles" list of the user model. This is the same as for any other profile that is applied to a model The profile definition is not a part of the UML metamodel, since, by definition, profile definitions occur at M1. However, I don't think we need to actually include a model of each standard profile with the spec. I feel that the added value of such a model over the current textual description is minimal and will only add bulk with diagrams that repeat graphically what the current appendix already says in more detail (NB: I do plan to add some minor touch ups to the current definitions as suggested in the issue). If there are no major grievances with the above approach, I will publish a draft resolution tomorrow. Subject: RE: New Appendix for UML keywords Date: Wed, 22 Sep 2004 10:50:16 -0400 X-MS-Has-Attach: X-MS-TNEF-Correlator: Thread-Topic: New Appendix for UML keywords Thread-Index: AcSf4OQowI++/O6dSNKoeG1xazqVOQAzkSqA From: "Pete Rivett" To: "Branislav Selic" , Cc: , X-Virus-Scanned: by amavisd-new at sentraliant.com Great work: I think this fills a void. Some detailed comments: - We need to be clearer what the effect of a word being 'reserved' is : where can such words not be used (e.g. as the name of a stereotype)? - I don't think we should treat the 'Standard stereotypes' as reserved words: they are just stereotypes as any other. This begs other questions I have raised before e.g. are these Stereotypes part of Standard Profile(s) (I think they must be since Stereotype.profile is mandatory), how do they fit with compliance points and is it possible to explicitly apply and unapply the Standard Profile(s) to models? - The notation section at bottom of 1st page does not make clear the options when both keywords and stereotypes are applied to the same element - are there 2 lists or may stereotypes and keyword be randomly intermixed in the same list? - It might be nice (but not essential) in the table to refer to the diagram type where the notation is applicable Pete Rivett (mailto:pete.rivett@adaptive.com) Chief Scientist, Adaptive Inc. Dean Park House, 8-10 Dean Park Crescent, Bournemouth, BH1 1HL, UK Tel: +44 (0)1202 449419 Fax: +44 (0)1202 449448 http://www.adaptive.com -------------------------------------------------------------------------------- From: Branislav Selic [mailto:bselic@ca.ibm.com] Sent: Tuesday, September 21, 2004 2:31 PM To: uml2-superstructure-ftf@omg.org Cc: mu2i-ftf@omg.org; uml2di-ftf@omg.org Subject: New Appendix for UML keywords Attached, please find a proposal that is part of the resolution to issue 6877. It contains a proposed new appendix that describes the purpose of UML keywords and contains a table of all such keywords along with brief descriptions of their meaning. There are a few things that still need to be adjusted in the table itself as well as some additional fixes that are part of the same resolution (such as some minor edits to the Standard Stereotype appendix C). However, I think it is best if I send it out in this not fully polished form to get feedback from the FTF. Note that this is not the place to argue over individual keywords and their suitability -- this is just about the appendix that collects all that stuff, good or bad, in one place for convenience. So, I am mostly looking for feedback on the format of the appendix. I would appreciate feedback over the next few days. I am pretty sure that someone will suggest that the table should include hyperlink references to the pages in the document where a keyword is defined. This is, of course, a very useful thing to provide and I may do that for the final version of the resolution. However, bear in mind that this is a lot of work (there are close to 100 keywords), and I will only do this if I have time. Thanks, Bran To: uml2-superstructure-ftf@omg.org Cc: mu2i-ftf@omg.org, uml2di-ftf@omg.org Subject: New Appendix for UML keywords X-Mailer: Lotus Notes Release 6.0.1CF1 March 04, 2003 From: Branislav Selic Date: Tue, 21 Sep 2004 09:30:47 -0400 X-MIMETrack: Serialize by Router on D25ML01/25/M/IBM(Release 6.0.2CF2|July 23, 2003) at 09/21/2004 09:31:05 Attached, please find a proposal that is part of the resolution to issue 6877. It contains a proposed new appendix that describes the purpose of UML keywords and contains a table of all such keywords along with brief descriptions of their meaning. There are a few things that still need to be adjusted in the table itself as well as some additional fixes that are part of the same resolution (such as some minor edits to the Standard Stereotype appendix C). However, I think it is best if I send it out in this not fully polished form to get feedback from the FTF. Note that this is not the place to argue over individual keywords and their suitability -- this is just about the appendix that collects all that stuff, good or bad, in one place for convenience. So, I am mostly looking for feedback on the format of the appendix. I would appreciate feedback over the next few days. I am pretty sure that someone will suggest that the table should include hyperlink references to the pages in the document where a keyword is defined. This is, of course, a very useful thing to provide and I may do that for the final version of the resolution. However, bear in mind that this is a lot of work (there are close to 100 keywords), and I will only do this if I have time. Thanks, Bran Keyword.Appendix.doc http://www.adaptive.com