Data Type Model

A data type model comprises the hierarchy of all Records–user-defined data types with an inner data-type structure–with their relationships and inheritance in a Model.

Records resemble OOP classes:

• The structure of a Record is defined by Record Fields with every Field defining its data type, be it a built-in data type or a Record.
• Records can inherit from each other.
• Behavior of Records is defined in methods in methods definition files.
• Records can be defined as and implement Interfaces.

Since a record holds your business data, you want to make sure that the data is valid: You can do so by defining constraints for your record.

Note: Further information on Records, Relationships, and related elements and mechanisms is available in BPMN Modeling Language Guide. The instantiation of Records, accessing a Record instance Fields, and related mechanism are documented in the Expression Language Guide.

Creating a Record

To create a Record, do the following:

1. Open a data type definition file for editing or create one:
   • To create a data type definition file, right-click a Module and go to New > Data Type Definition.
   • To open an existing definition file, double-click the definition in the GO-BPMN Explorer.
2. Right-click into the canvas and in the context menu, select Record.
3. Select the inserted Record and define its basic properties on the Detail tab of the Properties view:
   • Name: name unique within the Module
   • Supertype: supertype Record of the Record
   • Public: record is accessible from importing modules
   • Interfaces: comma-separate list of realized interfaces
   • Shared: shared record has its data persisted and hence is not dependent on the existence of its model instance
   • Abstract: An abstract record cannot be instantiated, but can be used as a supertype record of another Record.

   • Read-only: if true, all Fields of the Record are read-only: The Record instance is initialized on model instantiation and can be deleted during runtime; however, neither the Record instance nor instances of its subtype can be modified during runtime.

     Read-only records can only be targets of data relationships, but not their sources. This prevents a possible inconsistency of data.

   • System: if true, the record is read-only for the user

     A model instance cannot create instances of a system Record or calculate its Field values. However, it can be instantiated from your Application with the createRecord() on your context, possibly from a custom task or function implementation.

   • Final: if true, the Record cannot be a supertype
   • Monitoring: displays an icon to indicate that the Record is involved in Monitoring

   • Deprecated: flag to denote a deprecated Record

     If the attribute is true, the validation displays an information message that the Record is deprecated.

   • Label: a String that is assigned to the record

     Labels typically hold a human-readable name of the record, relationship end or enumeration, for example, for a Record NaturalPerson, you could define the label natural person. To display the type of a NaturalPerson record in a form, you could use the getLabel() function, for example, myPerson.getType().getLabel(). You can use the Label also for API calls.

4. Optionally, define XML Mapping.

Now you can insert fields into the record and define relationships and their properties if applicable.

Creating a Record Field

To create a record field, do the following:

1. On the canvas, select the record and press the Insert key to add a new field.

2. Select the field and define its properties in the Properties view.

   • Name: name unique within the Record

   • Type: data type of the record field

     Either enter the type directly, for example, Set<Map<Integer, String>> or click the Define button to use the wizard.

     Important: It is not recommended to use fields of complex data types. Also note that fields of collections with shared records in shared records are not supported: serialization of such fields will result in a DatabaseError exception. Use Relationships to associate a record with another record or a collection of records.

   • Visibility:
     • public: marked with +; field is accessible from anywhere
     • protected: marked with #; accessible only from within the given data type hierarchy (can be used by any subtypes)
     • private: marked with -; accessible only from the record and its methods (define methods to access from outside)
       

       Field with its properties

   • Label: a String that is used to represents the Record Field

     Labels typically hold a human-readable name of a Record Field, for example, for an Enumeration literal Weekday.MONDAY, you could define label Monday. To get the label value for the enumeration literal, you will use the Weekday.MONDAY.getLabel().

   • Read-only: if true, the field is read-only (instantiated on model instance instantiation; not modifiable after that)

   • Deprecated: flag that denotes a deprecated Record field

     If the attribute is true, the validation displays an information message that the Field is deprecated.

   • Used for equals: if true, the field value is used as a comparison criterion. You can find further details in Using Fields in Record Comparisons
   

Defining a Method of a Record

To define methods of a Record, do the following:

1. Open or create a method definition file for the Record:
   • To create a new method definition, right-click the Record and select New Methods Definition.
   • To open an existing definition, double-click the methods files in the GO-BPMN Explorer.
2. Add or edit the methods following the method syntax.

Method definitions: constructor and methods with different visibility

Defining a Subtype of a Record

To define a Record's supertype, open its Properties view and on the Detail tab enter the name of the supertype Record. Alternatively, select the Inheritance connector in the palette and draw the connection on the canvas.

For more information on the inheritance mechanism, refer to the GO-BPMN Modeling Language Guide.

Hierarchy of Records with multiple subtypes

Creating a Relationship Between Records

A relationship establishes a logical connection between records.

Record relationships are symmetrical: they are set on both navigation ends of the relationship. Therefore it is not necessary to make one of the record the owner of the relationship.

Information on the mechanisms, related elements, comparing of records and record properties is available in the GO-BPMN Modeling Language Guide.

Important: It is not recommended to create a relationships from a shared record to a common record since the target non-shared record is stored as BLOB. This can cause problems when refactoring and database migration; for example, when moving the record to another module since this changes the fully qualified name.

To create a relationship between two records, do the following:

1. In the Data Type Editor, click the quicklinker icon and pull the link toward the target Record.
   

   Creating Record Relationship
   The navigation ends represent the Target and Source ends. Which is which depends from the way you dragged the relationship line: the record you started from is considered the source. Information on the relationship direction is at the top of its Properties view.
2. Select the relationship and open its Properties view:
   1. Define its general properties on the Detail tabs.
   2. Define the properties of the navigation ends on the Target and Source tabs:
      • Name: name of the Relationship end used to navigate through to the target record
      • Visibility: visibility of the navigation
        • public: accessible from anywhere including importing modules
        • protected: accessible only from within the data type hierarchy (can be used by any subtypes)
        • private: accessible only from the record and its methods (define methods to access from outside)
      • Multiplicity: cardinality of the relationship end
      • Composition: establishes a "fixed" relationship direction of records
      • Used for equals: when comparing instances of the records, the given relationship is included

      • Label: a String that is assigned to the record

        Labels typically hold a human-readable name of the record, relationship end or enumeration; for example, for a Record NaturalPerson, you could define the label natural person. To display the type of a NaturalPerson record in a form, you could use the getLabel() function, for example, myPerson.getType().getLabel(). You can use the Label also for API calls.

   3. Define database-related properties of the relationship ends on the Target DB Mapping and Source DB Mapping tabs.
      • Lazy: whether loading of the related records is lazy or eager (refer to Fetching)
      • Exclude from optimistic lock: if selected the version of the entity in the database remains unchanged when the relationship changes; hence, the entity will be changed by all commits without collision. If not selected, and the relationship end entity is changed by multiple users at once, the system returns a "Conflict on entity" error.
   4. On relationships with one or two shared records, define the additional properties.

Setting Fetching

While values of shared Records are fetched anew in every transaction of a model instance, when you fetch a shared Record that is related to other records, the related Records can be fetched immediately or when explicitly requested. This is determined by the fetching strategy on the data relationship ends:

• Eager: related shared records are fetched immediately when the source record is accessed.
• Lazy: related records are fetched only when explicitly accessed via their data relationship (source.relationshipname)
  • For to-many relationships, you need to define the batch size. This defines for how many of the parent records all the related records are fetched.

Lazy fetching configuration

Using Records from Other Definitions

To display an element from another data type definition file, possibly from a definition file in an imported Module, use the Record Import element, which is available in the palette of the editor.

XML Mapping in a Data Type Model

XML mapping of a data model is used on export to XML when creating webservices, and by the convertToXML() and parseXML() functions, which make use of xml mapping properties defined on the pertinent records, record fields, and relationships.

• To define the XML mapping of a record, open the XML Mapping tab in its Properties view and define the relevant properties:
  • XSD type: XSD type of the record
  • Node name: name of the record node in the namespace
  • Namespace: XML namespace used for the record node
  • Use xsi:nil flag: make the record schema nillable so if the instance is null its XML instance node is generated with the xsi:nil="true" attribute.
  • Order of fields: the order of XML nodes generated for the record fields

• To define the XML mapping of a record field or a relationship end, open the XML Mapping on a field and Source/Target XML Mapping on a relationship Properties view and define the relevant properties:

  • XML Transient: exclude the field from the XML
  • XSD type: XSD type of the field
  • Node name: name of the record node in the namespace
  • Namespace: XML namespace use for the record node
  • Use xsi:nil flag: make the field schema nillable so when the field is null, its XML instance node is generated with the xsi:nil="true" attribute.
  • Attribute: the field is the attribute of the record element
  • Optional: the field is left out when null
  • Use as content: the field value is used as the record node content

  This setting is ignored if the Attribute property is selected.

Creating a Record Composition

Compositions establish a "fixed" data relationship between records in a direction, where the target record represents a part of the other record. The part cannot exist by itself and must hence always define its source value. It represents a "has-a" relationship.

To define a relationship end as a composition end, select the composition attribute of the data relationship end in its tab of the Properties view. For further information on composition, refer to the GO-BPMN Modeling Language Guide

Composition setting

Creating an Interface

An Interface is defined as a special type of Record with no Fields or Associations. Records that implement the Interface are connected to it with a Realization connector.

To create an Interface and its implementations, do the following:

1. Create the Interface Record:

   1. Create or open a Record that represents the Interface.
   2. In the Properties view of the Record, select the Interface checkbox.
   3. Create the methods file with the Interface methods: Right-click the Interface and click New Methods File.

      Nameable {

     public String getName();
     public void setName(String name);
   }
   

2. To create a Record that implements the Interface, do the following:
   1. Create the Record and connect it with its Interface with the Realization connector.
   2. Right-click the Record and select New Methods Definition.
   3. Implement the Interface methods for the Record.

Note: You can get to the methods file from the Interface Record by pressing Ctrl and double-clicking the method in the Record diagram elements (to display the methods in your Record, right-click the Record, go to Compartments and select Methods).

Interface with an implementation

Comparing Records

A Record instance is resolved into an object identity: when you compare records, the system compares the object identities, not the Record field values. If you want to compare Records based on the values of some Fields, you will need to define, which Fields should be used.

Defining Fields for Record Comparisons

Consider two instances r1 and r2 of a Record, which has a String field.

def Record2 r1 := new Record2(property -> "string");
def Record2 r2 := new Record2(property -> "string");
r1 == r2

The code returns false by default since it checks whether r1 and r2 are the same record instances, which they are not.

On the other hand, if you compare fields of a basic data type, the system compares the field values to check if the records equal: Hence r1.property == r2.property returns true.

To compare one or multiple properties when comparing record instances instead of the record identities, set the relevant record fields to Used for equals. If you set the flag on the Record String property,r1 == r2 would compare the strings and return true.

If a record has multiple properties with the Used for equals flag, all properties must be evaluated as equal for the record comparison to return true.

Note that the flag is inherited by fields of child records. For records with relationships to other records, you need to set the Used for equals flag on the navigation to allow inheritance of the equals flags.

Important: The Used for equals flag applies only to non-shared records.

Comparing Records with Fields on Related Records

To use a Field of a related Record when comparing instance of a Record, select the Used for equals flag on the Relationship end.

Presentation of Record Diagrams

Displaying and Hiding Record Compartments

To display or hide additional compartments in Record views, such as, their methods,inherited methods, Fields and inherited Fields, right-click the Record view in the Diagram, go to Compartments and select or unselect the compartments.

You can then click the method compartment to open its declaration.

Available Record compartments

Viewing Record Hierarchy

You can view the record hierarchy of the entire workspace in a tree structure in the Record Hierarchy view. The view provides an overview of all data types and their inheritance relationships.

The view is not displayed by default: to display it, go to to Window > Show View, or call the view from the context menu of a data type (either in the GO-BPMN Explorer or the Data Type Editor). Alternatively, right-click a Record view in a diagram and select Open Type Hierarchy.

Displaying a data type in the Record Hierarchy view (using the context menu) with the Record Hierarchy view on the left

When you select a Record in the tree, its fields are displayed in the lower section. From the context menu of a Record, you can do the following:

• Open the Data Type Editor with the data type focused
• Show the Data Type in the GO-BPMN Explorer or Properties view
• Show Full Type Names for all displayed Data Types
• Focus On the selected Data Type to show only the particular Data Type and its hierarchy

Importing Data Types from an XSD File

To import the data type definitions from an XSD file as Records, do the following:

1. In the GO-BPMN Explorer view, right-click the GO-BPMN module.
2. Click Generate Data Types from Xsd.

3. In the Generate Types from Xsd dialog box, select the Xsd file from the file system.

   Some mechanisms of the XSD file, such as, reducing the set of the permitted values or allowing a choice of values for several types, are not supported.