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

Introduction

A Plain Old CLR Object or POCO is an object that is a constituent of a de-referenced object graph. POCO's are used in end-user applications such as the CDP4-COMET-IME where the full object graph is used to represent information to the end-user and to implement business logic of end-user applications. Each class defined in the COMET Data Model is implemented, by means of code-generation and hand-coding, as a POCO and a DTO. All POCO's are code-generated as partial classes in the AutoGenPoco solution folder. Hand-coded logic is coded in class files with the same namespace and name in the Poco solution folder.

In the CDP4-COMET-SDK DTO instances are converted to POCO instances where properties of the DTOs that represent relationships, implemented as unique identifiers, are transformed into actual pointers to other POCO instances that match those unique identifiers. POCO instances are stored in the Cache for easy access, and to compute updates to these objects by means of comparing the cached object and a temporary POCO that is updated by means of GUI interaction.

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 POCO 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 COMET Data Model and is used include type information for serialization as well as for the specification of Permissions.

The [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.

Each Thing has a reference to the Cache that contains that Thing and to the URI of the data-source that it originated from.

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 [COMET Data Model]] by means of composite aggregation. Classes that are contained by another class in the [[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.

Composite aggregation is implemented by means of the ContainerList and OrderedItemList datatypes.

Read more about containment here.

Constructor

Each CDP4-COMET POCO contains 2 constructors:

  1. A Parameter-less constructor that includes initialization logic for properties that are of type ContainerList<T> and OrderedItemList<T>.

  2. A constructor that takes as arguments the unique identifier, the Cache and the URI of that data-source that the POCO originated from. This constructor also initializes the ContainerList<T> and OrderedItemList<T> properties.

The revision number property only exposes a public getter. The revision property is set when the Assembler constructs the POCO's on the basis of DTO instances that are coming from a data-source. Only a data-source should set the revision number.

Person and Participant Acces Right Kind

Each POCO exposes two constants related to the [COMET Data Model]] [permission handling. ECSS-E-TM-10-25A Annex A has a highly configurable permission scheme. For each type in the data model it is possible to set whether a particular Role has either Read, Read-Write, or no permissions for that type. The two constants state what the Default Person and Default Participant access rights are.

public const PersonAccessRightKind DefaultPersonAccess = PersonAccessRightKind.NOT_APPLICABLE;

public const ParticipantAccessRightKind DefaultParticipantAccess = ParticipantAccessRightKind.NOT_APPLICABLE;

Data Model Properties

Properties defined by the [COMET Data Model]] are all decorated in the POCO's with the [UmlInformation C# annotation providing meta-data regarding that property.

Derived properties

In case a property is a derived property it should only be used in a Get operation and not with a Set operation. In case the setter is called on such a property an InvalidOperationException is thrown. The getter of a derived property is implemented in the hand-coded partial class in a method of the same name, but prefixed with the word Get.

An example is the POCO called PrefixedUnit which exposes a property called ConversionFactor

[UmlInformation(aggregation: AggregationKind.None, isDerived: true, isOrdered: false, isNullable: false, isPersistent: false)]
public override string ConversionFactor
{
    get { return this.GetDerivedConversionFactor(); }
    set { throw new InvalidOperationException("Forbidden Set value for the derived property PrefixedUnit.ConversionFactor"); }
}

The GetDerivedConversionFactor method is implemented in the hand-coded PrefixedUnit class as follows:

protected string GetDerivedConversionFactor()
{
    return this.Prefix == null ? string.Empty : this.Prefix.ConversionFactor;
}

Helper methods and Properties

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

Containment and Routes

The following properties and methods expose functionality to work with the [CDP4-COMET Data Model features of the CDP4-COMET Data Model.

  1. Route: Gets the containement route of the current Thing.
  2. Container: Gets or sets the Container of the current Thing.
  3. TopContainer: Gets TopContainer of the current thing, this is either a SiteDirectory or an EngineeringModel.
  4. ContainerLists: A list of lists, the lists that are in the ContainerLists property represent the aggregate composition relationships of the current Thing.
  5. IsContainedBy: Queries the current Thing to check whether it is in the containment tree of the provided Thing
  6. GetContainerOfType: Returns the containing Thing of the specified type. If this Thing is not contained by another Thing of the specified type a null is returned.
  7. GetContainerOfType: Returns the containing Thing of the specified type. If this Thing is not contained by another Thing of the specified type a null is returned.
  8. GetContainerInformation: Gets a Tuple<Type, string> that represents the container information of the current Thing. It returs the Type of the container and the name of the property that represents the aggregate composition property that contains the current Thing.
  9. QueryContainedThingsDeep: Queries all the contained Thing of the current Thing along the complete containment hierarchy and returns them as a flat list. The current Thing is included in the result as well.

Validation

  1. ValidatePoco: Validates the current Thing, it verifies whether the specified cardinalities of the properties are correct, and wheter the value properties have the correct values. Any errors that may result from the validation are stored in the ValidationErrors property.
  2. ValidationErrors: A list of string that contains validation errors that are the result of the ValidatePoco method.

Cache

  1. Cache: Gets the Cache that contains the current Thing.
  2. CacheId: Gets the key with which the current Thing is stored in the Cache. The key is a combination of the unique identifier of the current Thing and the Iteration that it may be contained by.
  3. HasSentinelInstances: Gets a value indicating whether any of the properties of the current Thing are set to Sentinel Things. In order to make sure that properties do not return null when they should not according to the COMET Data Model, all properties are set to placeholder or Sentinel Things by the Assembler. During the assembling process these properties are updated with the proper references to existing Things.
  4. IsCached: Asserts whether the Thing is stored in the Cache.

Cloning

  1. Clone: Creates and returns a copy of this Thing. Things that are in the Cache should not be updated by an API developer. The Assembler has the responsibility to update Things based on DTO instances that are returned by a data-source. When a Thing should be updated, a clone of the Thing shall be created, this Clone is updated. The Session class is used to Write the Clone to the data-source which is responsible for executing the requested change. The result of this write method is a DTO that carries the result of the write method. This DTO is used to update the original Thingin the Cache.