Subgraph operations

This page discusses three common operations that handle some subgraph of the whole Simantics database. They all have very similar issues:

• Export/import
  • What is exported?
  • How are references from the exported part to the unexported part handled?
• Copy/paste
  • What is copied?
  • How are references from the copied part to the uncopied part handled?
• Removal
  • What is removed?
  • How are references between the removed and the unremoved resources handled?

Moreover in many cases copy/paste should behave similarly to export/import and immediate removal of an imported object should usually restore the database to the state before import.

Baseline behavior

First, it should be made clear, that in some cases there are more than one reasonable behaviour for the operations. For example, consider an applications where graphical and semantic objects are separated and the same semantic object can be represented by multiple graphical objects. When the user removes a graphical object, it is possible to remove also the corresponding semantic object, but it is also sensible to remove only the graphical object. Sometimes the desired behaviour can be asked from the user.

This means that the "correct" behaviour of each operation cannot be based purely on the shape of the data but it should be customizable in each case separately. However, the customization cannot be based solely on the type of the resource selected when the operation is requested. For example, a removal of a library has a very simple behavior: its children should also be removed. However the children of the library may each require different removal customization.

In order to collect all requirements for the customizable export/import, copy/paste and removal operations, we first define the baseline behaviour for the operations. The idea is that we can then collect all current cases where the operations should behave differently from the baseline and this helps for choosing the right customization hooks.

Every operation targets some resource C. In some cases there can be more than one target, but definitions should be easily generalizable for that case.

A resource is external to C if there is a PartOf-path leading from the resource to the root library such that the path does not include C. In other words, the set of resources external to C are the resources that are reachable by ConsistsOf from root library without going through C.

A resource is in the context of C if it reachable from C by statements without going through any external resources.

Now, we can define baseline behaviors:

• Export writes all resources in the context of C as internal resources to the transferable graph, together with all their statements excluding PartOf-statements from C. Resources external to C are referred by URI. C is marked the root of TG.
• Import creates all internal resources in TG file as new resources and adds all the statements in TG. The references to external resources are resolved by URI and if the resource does not exist a dummy resource is created. The root of the TG is attached by ConsistsOf to the target of the import operation.
• Copy/paste behaves just like export/import.
• Removal unlinks all the resource in the context of C from the external resources.

Exceptions to baseline behavior

Export/import

Requirements

• Developing import contributors a deveploper wants to list URIs of externals and possible change some of them while importing. This features enables e.g. moving of data of diagrams although different type declarations are used. Also, other kind of usage is possible. This requirement relates to a resolving of URIs feature.
• Developing export contributors a developer wants to know all external URIs. Thus, the developer can be aware of data which is not included into exported data.

Design guidelines (derived from baseline behaviour and aids in export/import operations)

• Define a symbol of a component type in the context of the component type
• Define a diagram of a composite in the context of the composite

Copy/paste

• All diagram elements
  • Template-diagram templatization tags must be removed (MOD.IsTemplatized)
  • Generate fresh names for all copied elements within the target diagram's context
  • Include element in the target diagram's ordered set
  • Add database metadata comment for element copy

In addition, follow these rules for specific element types:

• Diagram reference elements
  • Assertion: Copying must ensure that MOD.HasParentComponent correctly refers to the copied parent component
  • Offset all copied element positions based on the paste specification
• Diagram connections
  • Move connection to front of the target diagram's ordered set to push it behind all other elements
  • Offset each route line in the connection by the offset specified in the paste specification based on the route line direction (horizontal/vertical)
• Diagram flags
  • Offset all copied element positions based on the paste specification
  • If flag is disconnected after copy, remove its L0.HasLabel.
  • If flag and its counterpart were both copied and the flag pair is diagam-local, FlagLabelingScheme must be used to set the same L0.HasLabel for both flags.
• Diagram monitors
  • If the component the monitors refers to (DIA.HasMonitorComponent) a component that was not included in the copy, the monitor element position must be recalculated to be:
    • original monitored element world position + offset from paste specification
• Other diagram elements
  • Offset all copied element positions based on the paste specification

Removal

• Component types (and other types)
  • If the type has instances the operation must be cancelled or all the instances must be removed
• Connection points, properties (and other relations)
  • If the relation is used somewhere the operation must be cancelled or the corresponding statement must be removed.
• Components
  • If component is created by mapping from a diagram the corresponding diagram elements should also be removed