Transaction Update File

From wiki.eclass.eu
Jump to: navigation, search

Contents

[edit] Transaction Update File (TUF)

Transaction update files contain lists of structurally simple atomic updates that represent individual changes to the class/property/value/unit tupel.

Transaction update files:

· Are one among several files (RUF, TUF, SDF, CUF) to enable eCl@ss users to update their product data to a new release in a semi-automatic way. All of these files can be found here.

· Provide an upgrade path for transaction data and views and local mapping information

· Include only information that cannot be obtained by direct comparison of subsequent structure data releases.

· Provide all information needed to convert transaction data and views from one release to the next release. Allow for transitivity by applying transaction update files for all intermediate releases.

Transaction update files are designed to allow implementation of a simple straight forward algorithm for update of such class/property/value/unit tuples.

Contained in the transaction update file are combinations of predecessor-successor pairs of paths. There will be a high number of transaction updates, mainly concentrating on the objects property, value and unit.

The transaction update file contains all information that is needed to update a transactional or catalogue file (e.g. a BMEcat File) that was created based on a certain release to the next release, given that both dictionaries are available.

A path can be imagined as the way one would traverse when starting from the application class over reference properties of blocks to reach a certain property in the context of this application class and block structure. Therefore in case of basic model paths are all very short (containing the application class and the property), but in case of advanced model they can become long when a property is addressed that is situated in a deeply nested block structure.

If only the previous release is accessible, Structure Difference File (SDF) may be used before applying Transaction Update Files.

XML Schema is here:

C6.png
Figure 1 - Transaction Update File Overview (eCl@ssXML-1.0)


[edit] Structure of the file

The transaction update file wraps in a TUF element an unbounded sequence of TUF_ENTRY elements. Each TUF_ENTRY contains one of the five commands:

·         equiv_path

·         delete_path

·         propose_value

·         delete_value

·         select_branch


These commands are explained in detail the remainder of this chapter.


[edit] equiv_path

Purpose: Transport how a certain property’s context has changed between source and target release.

The equiv_path contains a sequence of up to five elements:


1.     source_path: mandatory; of PROPERTYPATH_Type

a.     can have up to three optional attributes (cc, ac, aspect having IRDI as values) that give the class context of the property path

b.    contains a sequence of property elements which give the path of the property. Note that this path is only longer than 1 in case of advanced classes, i.e. where a block structure is traversed. Each property element has three elements:

                                          i.    a mandatory ref (the IRDI of the property)

                                         ii.    an optional ordinal_number (integer index of a traversed pattern of cardinality)

                                        iii.    a target_class_ref (IRDI of the selected specialization of a traversed pattern of polymorphism)

2.     target_path: mandatory; structurally of the same PROPERTYPATH_Type as source_path

3.     value_mapping: optional; contains a sequence of source_value and target_value which are both references to an ontoML value group.

4.     unit_mapping: optional; contains a sequence of source_unit and target_unit which are both identified by their IRDI.

5.     incompatible_change: optional; boolean that tells whether or not a change can be performed automatically (when omitted it obviously can)

 


Note:

Deletions in eCl@ss 7.0 were implemented such that:

·         a new property was introduced in target class

·         an equiv_path command was issued from the to be deleted property to the newly created one

·         the to be “deleted” property was set to deprecated

Thereby it was not triggered that the code of the old application class be updated as it would have had to be in case a real replace (including a real deletion of property) had been performed.

 

[edit] Examples

Please note: Some example refer to eCl@ssXML-1.0, some refer to eCl@ssXML-2.0, syntactically they are equal, only namespaces are different.


Example 1 (eCl@ssXML-1.0):

<tuf:equiv_path> 
      <tuf:source_path aspect="0173-1#01-SGX034#004" ac="0173-1#01-ABY226#005" cc="0173-1#01-BAE982#005">
        <cmn:property ref="0173-1#02-AAE670#001" /> 
      </tuf:source_path> 
      <tuf:target_path aspect="0173-1#01-SGX034#005" ac="0173-1#01-ABY226#006" cc="0173-1#01-BAE982#006">
        <cmn:property ref="0173-1#02-AAQ326#001" /> 
      </tuf:target_path>
</tuf:equiv_path>

In the above example the property AAE670 in the default aspect SGX034 was replaced by the property AAQ326. The context of the property path is the CC BAE982 with the AC ABY226.


Example 2 (eCl@ssXML-2.0): Property Replace The property AAC963 (Rated Voltage, deleted) that was assigned to the BASIC Application Class of SourceClass 22410101 was replaced by Property BAH005 (Rated Voltage):

TUFPropertyReplaceCDP.jpg

The corresponding TUF entry is:

TUFPropertyReplaceXML.jpg


Example 3 (eCl@ssXML-2.0): Join Class

The successor path for property AAO735 (Rated Voltage, deleted) that was assigned to the BASIC Application Class (ABZ689) of SourceClass 40210203 (BAC917) is now the Basic Application Class (AEL649) of TargetClass 34140202, after the Join of the SourceClass into the TargetClass. The TUF entry is:

TUFJoinClassXML.jpg

[edit] delete_path

Purpose: Delete a path which is no longer valid, i.e. property has no successor in target structure and valuation shall be destroyed

The delete_path contains one mandatory element, the source_path which is of the same of PROPERTYPATH_Type as the source_path in the equiv_path command.


Example (eCl@ssXML-1.0):

    <tuf:delete_path>
 
      <tuf:source_path ac="0173-1#01-ABY226#005" cc="0173-1#01-BAE982#005">
 
        <cmn:property ref="0173-1#02-BAJ012#006" />
 
      </tuf:source_path>
 
    </tuf:delete_path>

In the above example the valuation of the undesired property BAJ012 is destroyed in the context of AC ABY226 classified as CC BAE982.

[edit] propose_value

Purpose: introduce a value for a property. May be needed for initialization of pattern of cardinality

Propose_value contains a sequence of two mandatory elements, the target_path of the property for which the value is proposed (which is of the same of PROPERTYPATH_Type as the source_path in the equiv_path command) and the proposed_value (a reference to an ontoML value group)

Note: does not occur in eCl@ss 7.0

Example (eCl@ssXML-1.0):

<propose_value> 
                <target_path cc="0173-123#01-AAA123#002" ac="0173-123#01-BAA123#002"> 
                                <cmn:property ref="0173-123#01-AAA123#002" /> 
                </target_path> 
                <proposed_value> 
                                <val:string_value>just a test</val:string_value> 
                </proposed_value> 
</propose_value>

[edit] delete_value

Purpose: delete a value (needed for corrections)

Propose_value contains a sequence of two mandatory elements, the source_path of the property for which the value is deleted (which is of the same of PROPERTYPATH_Type as the source_path in the equiv_path command) and the value_to_delete (a reference to an ontoML value group)

Note: does not occur in eCl@ss 7.0

Example (eCl@ssXML-1.0):

<delete_value> 
            <source_path cc="0173-123#01-AAA123#001" ac="0173-123#01-BAA123#001"> 
                        <cmn:property ref="0173-123#02-AAA123#001" /> 
            </source_path> 
            <value_to_delete> 
                        <val:string_value>remove this</val:string_value> 
            </value_to_delete> 
</delete_value>

[edit] select_branch

Purpose: Unfold pattern of cardinality and/or polymorphism in a predefined way

In case of complex changes it may be necessary in order to allow for automatic conversion of valuations to prepare a certain unfolding of structure to obtain the needed target paths for equiv_path commands.

select_branch contains a target_path which is of the same of PROPERTYPATH_Type as the source_path in the equiv_path command. It is to be expected that one of the attributes ordinal_number or target_class_ref is set.


Note: does not occur in eCl@ss 7.0

Example (eCl@ssXML-1.0):

<select_branch> 
                <target_path cc="0173-123#01-AAA123#002" ac="0173-123#01-BAA123#002"> 
                                <cmn:property ref="0173-123#02-AAA123#002" ordinal_number="1"/> 
                </target_path> 
</select_branch>
Personal tools