# Introduction

An architecture context is a method for customizing Papyrus for a given domain. It defines a regime for editing a Papyrus model semantically and notationally. The semantic editing is defined by a set of element type set configurations (from some domain), while the notational side is defined by a set of viewpoints consisting of a set of representation kinds (e.g., diagram kinds and table kinds) and other notational configurations.

An architecture context is composed within an architecture domain (a namespace) and satisfies a set of concerns that belong to a set of stakeholders, both of which are composed in (the same or another) architecture domain. An architecture domain can be specified by one or more architecture models. In the latter case, all of these models are dynamically merged at runtime.

An architecture context can either be an architecture description language or an architecture framework. In the former case, it can own its own set of representation kinds, while in the latter, it cannot. However, in both cases, a context can own a set of viewpoints that reference representation kinds owned by any description language.

Each model in Papyrus is created using a specific architecture context, although this context may later be switched, possibly resulting in the model details being changed. A model also specifies a subset of its context's viewpoints as enabled at creation time, although this set may later be switched as well. When a viewpoint is enabled on a model, a user can create representations, based on this viewpoint's referenced representation kinds, and see them in model explorer. When a viewpoint is disabled, its representations become invisible, unless another enabled viewpoint references their representation kinds.

# Architecture Context Preference Page

Papyrus is typically deployed with one or more architecture models that are registered through platform extensions. The architecture contexts contributed by these models can be seen in the Architecture Context Preference Page:

A user can choose to enable or disable those architecture contexts in the workbench by toggling their checkboxes, set one of them as a default context (using the Make Default button), or extend existing contexts or add to them at runtime by specifying other architecture models from the file system or the workspace (using the Other Architecture Models button):

# Architecture Context UI Elements

The enabling of architecture contexts in a workbench has some impacts on the following UI elements in Papyrus:

- The Select Architecture Context page of the New Papyrus Model wizard allows for selecting one of the enabled architecture contexts to create the model in. It also allows for enabling/disabling on the model the set of viewpoints that are provided by the context.

- The Initialization Information in the New Papyrus Model wizard has a Select a Representation Kind section that is populated with only the diagrams and tables that are available in the enabled viewpoints.

- The Switch Architecture Context... context menu action in the Model Explorer view allows for switching the model's architecture context and/or viewpoints. Similarly, the Switch Architecture Viewpoints context menu allows for quickly enabling/disabling a viewpoint.

- The Unsupported Diagrams/Tables filter in the Model Explorer view hides diagrams/tables whose kinds are not supported by the viewpoints currently enabled on the model.

- The New Diagram and New Table contextual menus for the model elements in the Model Explorer view provides only the diagrams and tables that are available in the enabled viewpoints and are applicable to the currently selected model element. For example, when a UML Activity is selected, the New Diagram context menu will not offer to create a Package diagram, or a class diagram. The same holds for the toolbar elements for the creation of diagrams and tables.

- The diagrams properties show the following information:

- Diagram Type or Table Kind is the qualified name of the representation kind. It gives an indication of which architecture context is providing it.
- The Owner attribute is the model element that syntactically contains the representation in the model explorer. It can be different from the root element.
- The Root element attribute is the model element that is the representation's root semantic element.

# Definition of New Architecture Models

Papyrus supports the definition of new architecture models that can subsequently be used by selecting them as other models in the Papyrus Architecture Context preference page, as presented above. Papyrus architecture models are defined in files with the *.architecture extension. They are really just Ecore models that can be edited with the specialized architecture model editor provided by Papyrus.

## Basic Concepts

The architecture metamodel in Papyrus is implemented as a realization and an extension to the ISO 42010 standard for architecture of systems. Hence many concepts present in the metamodel are derived from those presented in the ISO 42010 standard. However, the standard has been extended with Papyrus-specific concepts and properties.

- A domain is the root of the architecture model. It can contains a collection of concerns, stakeholders, as well as contexts (which can be description languages and/or frameworks).
- A concern (from ISO 42010) represents in Papyrus a matter of interest to some stakeholder.
- A stakeholder (from ISO 42010) represents in Papyrus an archetype of users. It references a set of its concerns.
- A description language (from ISO 42010) represents in Papyrus a modeling language (e.g., UML, SysML). It has a unique id' that corresponds to that of an IClientContext'' from GMF. It references a metamodel, a set of profiles, a set of element type set configurations, a creation command (creates a model of this language), a conversion command (converts a model to this language), and and icon. It also has an optional extension prefix for its models. It can also contain a set of representation kinds (which can be either diagrams or tables) and a set of viewpoints.
- A framework (from ISO 42010) represents in Papyrus a modeling framework (e.g., DoDAF). It has a unique id' that corresponds to that of an IClientContext'' from GMF. It references a set of element type set configurations, a creation command (creates a model of this framework), a conversion command (converts a model to this framework), and an icon. It also has an optional extension prefix for its models. It can also contain a set of viewpoints.
- A viewpoint (from ISO 42010) in Papyrus references set of representation kinds, which can be diagrams or tables.
- A diagram in this context does not represent a single instance (for example the diagram named X in model Y), but the specification (or prototype) of future diagrams of this kind. For example the UML Class Diagram.
- A table is another kind of view in Papyrus that enables the presentation of models in a tabular format.

## Walkthrough

The definition of an architecture model in Papyrus starts with the selection of the Architecture Model option in the Eclipse New creation wizard under the Papyrus category and clicking Finish.

Step 1: Specify the Name and Description of the Architecture Domain (the root element).

Step 2: Right click on the domain to add one or more Concerns. In the properties view, specify the following for each concern: a Name and a Description.

Step 3: Right click on the domain to add one or more Stakeholders. In the properties view, specify the following for each stakeholder: a Name, a Description, and one or more references to Concerns.

Step 4: Right click on the domain to add one or more Architecture Description Languages. In the properties view, specify for each language: a Name, a Description, a unique Id (e.g., org.eclipse.uml2.UML), an Extension Prefix if desired (e.g., profile), an Icon using a platform plugin URI (e.g., platform:/plugin/project/icons/xxx.png), a Metamodel as a reference to an EPackage (load the Ecore model first), one or more Profiles as references to EPackages (load the Ecore models first), one or more Element Types as references to ElementTypeSetConfigurations (load the *.elementtypesetconfiguration models first), a creation command using a fully qualified of a Java class implementing the IModelCreationCommand interface, and an optional conversion command using a fully qualified of a Java class implementing the IModelConversionCommand interface.

Step 4A: Right click on the description language to add one or more representation kinds, i.e., Papyrus Diagram, Papyrus Table or Papyrus Sync Table (see details below).

Step 5: Right click on the domain to add one or more Architecture Framework. In the properties view, specify for each framework: a Name, a Description, a unique Id (e.g., org.eclipse.dodaf), an Extension Prefix if desired (e.g., profile), an Icon using a platform plugin URI (e.g., platform:/plugin/project/icons/xxx.png), and one or more Element Types as references to ElementTypeSetConfigurations (load the *.elementtypesetconfiguration models first).

Step 6: Right click on the description language (step 4) or framework (step 5) to add one or more Architecture Viewpoints. In the properties view, specify for each viewpoint: a Name, a Description, a unique Id (e.g., org.eclipse.uml.design), one ore more references to Concerns, and one or more references to Representation Kinds.

Step 7: Deploy the model. The new architecture file can be deployed in an Eclipse plugin and registered through an extension point. The extension point to use is `org.eclipse.papyrus.infra.architecture.models`. Alternatively, the model can be deployed using the Other Architecture Model button in the Architecture Contexts preference page.

Note: If the Architecture Model you are developing is considered an extension of another model that is available in the target platform, and you want to reference some of its dependencies (like elementtypeconfigurations and palleteconfiguration, etc.) you first need to load the plugin that contains the model in your workspace. Then, using the Architecture Model editor, load the other Architecture Model using the Load Resource->Browse Workspace context menu action). This will import it using its "platform:/resource" URI. On the other hand, if the extended architecture model is rather deployed in the current platform, then use the Loaded Resource->Browse Registered Architectures context menu action. This will load the model using its "platform:/plugin" URI. Once the extended model is loaded in the editor, you can invoke the context menu action Resolve All to load all its related resources.

## Papyrus Diagram Specification

Once a Papyrus Diagram is created, in the properties view, specify for it:

- A Name (required) that is the user-visible name of the diagram. It will appear in the creation menus and property panel.
- An Icon (required), as an URI of the form `platform:/plugin/...`.
- An Implementation ID (required) which selects the physical (hard-coded) diagram in Papyrus that will be used as a base. The possible values for this property are summarized in the following table.
- An optional Parent that specifies a parent viewpoint-defined diagram to inherit from. Essentially, the inheriting diagram will defer to its parent�s rules (see below) when its own are not sufficient to take a decision.
- An optional Custom Style as an URI of the form `platform:/plugin/...`. It must point to a CSS file that will then be automatically applied to the diagram.
- An optional Palette as an URI. It must point a palette definition in XML that will be automatically applied to the diagram.
- Other attributes are inherited from the ISO 42010 implementation and are currently not used in Papyrus.

Implementation ID | Description
--- | ---
PapyrusUMLActivityDiagram | UML Activity Diagram
PapyrusUMLClassDiagram | UML Class Diagram
PapyrusUMLCommunicationDiagram | UML Communication Diagram
PapyrusUMLComponentDiagram | UML Component Diagram
CompositeStructure | UML Composite Diagram
PapyrusUMLDeploymentDiagram | UML Deployment Diagram
PapyrusUMLProfileDiagram | UML Profile Diagram
PapyrusUMLSequenceDiagram | UML Sequence Diagram
PapyrusUMLStateMachineDiagram | UML State Machine Diagram
PapyrusUMLTimingDiagram | UML Timing Diagram
UseCase | UML Use Case Diagram
PapyrusUMLInteractionOverviewDiagram | UML Interaction Overview Diagram
BlockDefinition | SysML Block Definition Diagram
InternalBlock | SysML Internal Block Diagram
Parametric | SysML Parametric Diagram
RequirementDiagram | SysML Requirements Diagram

Once a diagram has been created it is possible to constraint it using rules. There are four kinds of rules:

- Model rules constrain the type of the (root) model elements that can be visualized through this view. Hence model rules control what model elements can be selected for the Root element property of the diagrams, as shown in the capture below.
- Owning rules constrain the type of the model elements that can own the diagram itself. In practice this materializes as the type of model elements under which the diagrams can appear in the model explorer. Owning rules control what model elements can be selected for the Owner property of the diagrams, as shown in the capture below.
- Child rules constrain the type of the model elements that can be dropped within this diagram.
- Palette rules constrain the display of the diagram's palette elements.

Each rule has a Permit property that specify whether the rule authorizes or forbids the action it represents. Otherwise, the properties of the rules are as follow:

- Model Rules
  - Element (required) represents the type of the model elements to apply the rule on.
  - Multiplicity (required, default is -1) represents the maximum number of this kind of diagram that can be created for the referenced model element. -1 represents an unbounded number.
  - Stereotypes represents the set of stereotypes that must be applied in the model element for the rule to match. The stereotypes can be picked from the classifiers of the Profiles defined in the parent diagram.
- Owning Rules
  - Element (required) represents the type of the model elements to apply the rule on.
  - Multiplicity (required, default is -1) represents the maximum number of this kind of diagram that can be created for the referenced model element. -1 represents an unbounded number.
  - Stereotypes represents the set of stereotypes that must be applied in the model element for the rule to match. The stereotypes can be picked from the classifiers of the Profiles defined in the parent diagram.
- Child Rules
  - Element (required) represents the type of the model elements begin dropped.
  - Stereotypes represents the set of stereotypes that must be applied in the model element for the rule to match. The stereotypes can be picked from the classifiers of the Profiles defined in the parent diagram.
  - Origin (required) represents the type of the model elements that are the target of the drop. It is usually one of the type defined in the Model Rules.
  - Additionally, Child Rules can be completed with children called Path Elements using the New Child contextual menu. Path Elements defines a path of properties that must be used from the Origin to insert the new Element in the model.
- Palette Rules
  - Element (required) represents a pattern to match for the identifier of a palette element.
    - If the value ends with '*', it will match any palette element with the prefix specified before the '*'.
    - If the value is '*', it will match any palette element.

The minimal required rules for a diagram specification to work are:

- A model rule that allows the diagram to be created for a model element. For example, a model rule with Element set to UML Package, Multiplicity to -1 and Permit to true; meaning this diagram can be created for UML Packages and an unlimited number of diagrams can be created for each UML Package.
- An owning rule that allows the diagram to be owned by a model element (appear under an element in the model explorer). For example, an owning rule with Element set to UML Package, Multiplicity set to -1 and Permit to true; meaning an unlimited number of diagrams of this kind can be placed under each UML Package element in the model explorer.
- A child rule that allows the dropping of any element in the diagram, expressed with the Permit attribute set to true and other attributes left empty.