View source for Documentation:Custom types and custom operations in OCL

You can use a native .NET type as an attribute type and call its exposed methods from [[Documentation:Learn OCL|OCL]] and EAL; this page is for developers who need a custom type to compare correctly in OCL.

== Use a native custom type for an attribute ==
A custom type is a native .NET type that you define and assign as the type of a model attribute. MDriven can use such a type as an attribute type and can expose methods on that type to OCL and EAL.

For example, the following <code>TestStruct</code> holds two integer values and implements <code>IComparable</code>:

<syntaxhighlight lang="csharp">
public struct TestStruct : IComparable
{
  public int Int1 { get; private set; }
  public int Int2 { get; private set; }

  public TestStruct(int int1, int int2) : this()
  {
    Int1 = int1;
    Int2 = int2;
  }

  public int CompareToX(object obj)
  {
    return CompareTo(obj);
  }

  public int CompareToX(TestStruct other)
  {
    return CompareTo(other);
  }

  public int CompareTo(TestStruct other)
  {
    return (Int1 + Int2).CompareTo(other.Int1 + other.Int2);
  }

  public int CompareTo(object obj)
  {
    return CompareTo((TestStruct)obj);
  }
}
</syntaxhighlight>

If <code>Class1</code> has an attribute named <code>Attribute2</code> of type <code>TestStruct</code>, an ordinary custom method such as <code>CompareToX</code> can be called in OCL:

<syntaxhighlight lang="text">
Class1.allInstances.Attribute2.CompareToX(
  Class1.allInstances->first.Attribute2)
</syntaxhighlight>

<code>Class1.allInstances.Attribute2</code> navigates the attribute from the instances of <code>Class1</code>. Collection navigation expands the values into one collection; see [[Documentation:Examples on collection operators|collection operator examples]] for this behavior.

== Compare custom values with the OCL equality operator ==
Do not call <code>CompareTo</code> directly in OCL. <code>CompareTo</code> is a recognized comparison operation, and MDriven maps it to the OCL equality operator, <code>=</code>.

Use this expression instead:

<syntaxhighlight lang="text">
Class1.allInstances.Attribute2 =
  (Class1.allInstances->first.Attribute2)
</syntaxhighlight>

This explains why the direct call below produces an undefined-operation error:

<syntaxhighlight lang="text">
Class1.allInstances.Attribute2.CompareTo(
  Class1.allInstances->first.Attribute2)
</syntaxhighlight>

The error does not mean that the type cannot be used in OCL. It means that <code>CompareTo</code> has special equality semantics rather than being available as a normal OCL method call. Use another method name, such as <code>CompareToX</code>, when you need to invoke a custom comparison method explicitly.

== Implement equality for the custom type ==
For attribute-type equality, MDriven uses <code>IComparable.CompareTo</code> when the type implements <code>IComparable</code>. Two values are equal when <code>CompareTo</code> returns <code>0</code>. If the type does not implement <code>IComparable</code>, equality falls back to <code>object.Equals</code>.

Implement <code>Equals</code> consistently with <code>CompareTo</code>. Override <code>GetHashCode</code> as well. For the preceding example, add:

<syntaxhighlight lang="csharp">
public override bool Equals(object obj)
{
  return CompareTo(obj) == 0;
}

public override int GetHashCode()
{
  return Int1 ^ Int2;
}
</syntaxhighlight>

In this example, comparison is based on <code>Int1 + Int2</code>. Therefore, <code>new TestStruct(1, 2)</code> and <code>new TestStruct(2, 1)</code> compare as equal because both sums are <code>3</code>. Your <code>Equals</code> implementation must use the same definition of equality as <code>CompareTo</code>; otherwise, OCL comparisons and .NET equality can produce conflicting results.

== Persisting a custom attribute type ==
Using a native type in memory is separate from storing it in a database. If you persist a custom attribute type, you must provide persistence mapping for that type. The relevant mechanisms are <code>AbstractSingleColumnAttribute</code>, <code>ISingleColumnAttribute</code> mapping, and <code>IDefaultReverseMapping</code>.

Plan the stored representation before you make the attribute persistent. For example, a two-value structure may require a defined single-column representation and a corresponding reverse mapping back to the custom type.

== OCL and EAL usage ==
OCL is a query language and expressions must not have side effects. Use it for constraints, derivations, ViewModel expressions, and other queries. EAL uses OCL-like syntax where an action needs to change data. See [[Documentation:Learn OCL|Learn OCL]] for where these languages are used.

== Troubleshooting ==
{| class="wikitable"
! Symptom
! Cause
! What to do
|-
| <code>Undefined operation: CompareTo</code>
| <code>CompareTo</code> is mapped to OCL <code>=</code>.
| Replace the method call with an equality expression, such as <code>value1 = value2</code>.
|-
| A method with another name, such as <code>CompareToX</code>, works
| Methods on the native type can be exposed to OCL; the special behavior is specific to <code>CompareTo</code>.
| Keep the custom method name when you need an explicit method call.
|-
| Equality does not match the intended business comparison
| <code>CompareTo</code> and <code>Equals</code> use different rules, or neither rule represents the intended equality.
| Define one equality rule and implement <code>CompareTo</code>, <code>Equals</code>, and <code>GetHashCode</code> consistently.
|-
| A custom attribute works in memory but cannot be stored
| No persistence mapping has been supplied for the native type.
| Implement the required custom-type persistence mapping.
|}

== See also ==
* [[Documentation:Learn OCL]]
* [[Documentation:OCL]]
* [[Documentation:OCLOperators]]
* [[Documentation:Examples on collection operators]]
* [[Documentation:Data types]]

[[Category:Advanced-Friendly]]
[[Category:OCL (Object Constraint Language)]]
[[Category:Priority 70]]
[[Category:Writing OCL Expressions and Constraints]]