DTO - STARIONGROUP/COMET-SDK-Community-Edition GitHub Wiki

Introduction

A Data Transfer Object or DTO is an object that carries data between processes. DTO's are used to transfer data between the end-user applications such as the COMET-IME and the CDP4-COMET Web Services. Each class defined in the CDP4-COMET Data-Model is implemented, by means of code-generation and hand-coding, as a DTO and a POCO. The CDP4-COMET Data-Model only defines properties and no methods. All DTO's are code-generated as partial classes in the AutoGenDto solution folder. Hand-coded logic is coded in class files with the same namespace and name in the Dto solution folder.

Thing

In the CDP4-COMET Data Model there is one abstract super class from which all classes in the domain model derive. This is the Thing class. A Thing DTO has a property called ClassKind, which is an assertion of the ClassKind of this Thing, denoting its actual class. The ClassKind enumeration is part of the CDP4-COMET Data Model and is used include type information for serialization as well as for the specification of Permissions.

The CDP4-COMET Data Model contains more concepts to facilitate Concurrent Design than are prescribed by [ECSS E TM 10 25A Annex A]]. These extensions also derive from the Thing class and are processed by the CDP4-COMET Web Services. The CDP4-COMET extensions to [[ECSS E TM 10 25A Annex A]] are decorated with the [CDPVersion C# Attribute.

Containment

ECSS-E-TM-10-25A-Annex-A specifies an abstract super class called TopContainer. The following definition applies to the TopContainer class:

Representation of a top container. A concrete subclass of TopContainer must be instantiated as a singleton in a dataset. This singleton instance is the top containing object of all objects in the composite tree of objects in the dataset, and therefore also the natural first entry point for navigating to all data contained in the dataset through composite structure.

The containment tree is expressed in the CDP4-COMET Data Model by means of composite aggregation. Classes that are contained by another class in the CDP4-COMET Data Model are decorated by the Container C# attribute. The Container attribute has 2 properties:

  • the ClassType that specifies the Type of the container,
  • the PropertyName that specifies the name of the property that contains the decorated class. A class in the CDP4-COMET Data Model will always only be contained by 1 other class in the CDP4-COMET Data Model.

Read more about containment here.

Constructor

Each CDP4-COMET DTO contains 2 constructors:

  1. A Parameter-less constructor that includes initialization logic for IEnumerable<T> properties.
  2. A constructor that takes as arguments the unique identifier and the revision number of the class. This constructor also initializes the IEnumerable<T> properties.

Data Model Properties

Properties defined by the CDP4-COMET Data Model are all decorated in the DTO's with the UmlInformation C# annotation providing meta-data regarding that property as well as the DataMember attribute. Derived properties are provided in the DTO's for completeness only, the getters and setters should not be called, an InvalidOperationException exception will be thrown. Derived properties are also decorated with the XmlIgonore C# attribute so that XML serialization frameworks of .NET ignore these properties.

Helper methods and Properties

The DTO's expose helper properties and helper methods to assist in using the DTO's in the COMET-SDK framework. These methods and properties are described below.

Containment and Routes

  1. IterationContainerId: The unique identifier of the Iteration that contains this Thing. If this is null or the empty Guid then the Thing is not contained by an Iteration, but by the SiteDirectory or an EngineeringModel
  2. ContainerLevelKind:
  3. ContainerLists: A convenience property that contains a collection of properties that represent a containment relationship.
  4. Contains: a method that is used to check if a DTO is contained by another DTO.
  5. Route: The route property represents the containment path of a DTO. It is similar to a URI, the containment starts at either the SiteDirectory or an EngineeringModel. A containment property and unique identifier are separated by a forward slash /. e.g. SiteDirectory/{iid}/person/{iid}/emailAddress.
  6. AddContainer: A method that is used to create the containment Route of a DTO. The ClassKind and unique identifier of each container is added. The immidiate container of the subject DTO is added first, the SiteDirectory or EngineeringModel is added to the list last.
  7. GetTopContainerRoute: Returns either the SiteDirectory route, or Iteration route of a DTO.

POCO

  1. InstantiatePoco: used to instantiate a POCO on the basis of a DTO. All the value properties of the POCO are set to the value properties of the DTO.
  2. RegisterSourceThing: When a POCO is transformed into a DTO the RegisterSourceThing function is used to register the source POCO with the DTO.
  3. QuerySourceThing: returns the POCO that was registered with the DTO using the RegisterSourceThing function.

DeepClone

The DeeplCone<T> method creates and returns a clone of a [DTO]] where all properties that are defined as part of the [CDP4-COMET Data Model are copied.

ResolveCopy and ResolveCopyReference

The ResolveCopy and ResolveCopyReference helper methods are convenience methods used by the CDP4-COMET Web Services. These should not be used by API developers. These methods are planned to be removed from the COMET-SDK and moved to the CDP4-COMET Web Services project.