Event Handlers (Profile)

CanCreate

Used to implement a creation validation rule to prevent objects from being created in an invalid context. For example, in a BPM for ebXML, a process with a Business Transactions stereotype can only be created under a process with a Binary Collaboration stereotype. The script of the CanCreate event handler associated with the Business Transaction process stereotype is the following:

Function %CanCreate%(parent)
  if parent is Nothing or 
  parent.IsKindOf(PdBpm.Cls_Process) then
  %CanCreate% = False
  else
  %CanCreate% = True
  end if
End Function

If this event handler is set on a stereotype and returns True, then you can use the custom tool to create the stereotyped object. Otherwise the tool is not available, and the stereotype list excludes corresponding stereotype. If it is set on a metaclass and returns True, then you can create the object from the palette, from the Browser or in a list.

Note that, when you import or reverse engineer a model, the CanCreate functions are ignored since they could modify the model and make it diverge from the source.

Initialize

Used to instantiate objects with predefined templates. For example, in a BPM, a Business Transaction must be a composite process with a predefined sub-graph. The script of the Initialize event handler associated with the Business Transaction process stereotype contains all the functions needed to create the sub-graph. The following piece of script is a subset of the Initialize event handler for a Business Transaction.

...
' Search for an existing requesting activity 
     symbol
 Dim ReqSym  
 Set ReqSym = Nothing  
 If Not ReqBizAct is Nothing Then
  If ReqBizAct.Symbols.Count > 0 Then
   Set ReqSym = ReqBizAct.Symbols.Item(0)
  End If
 End If
 
 ' Create a requesting activity if not found
 If ReqBizAct is Nothing Then
   Set ReqBizAct =
      BizTrans.Processes.CreateNew 
   ReqBizAct.Stereotype =
     "RequestingBusinessActivity"
   ReqBizAct.Name = "Request"
 End If
...

If the Initialize event handler is set on a stereotype and returns True, the initialization script will be launched whenever the stereotype is assigned, either with a custom tool in the palette, or from the object property sheet. If it is set on a metaclass and returns True, the initialization script will be launched when you create a new object from the tool palette, from the Browser, in a list or in a property sheet.

If it is set on the model metaclass and returns True, the initialization script is launched when you assign a target (DBMS or object, process, or schema language) to the model at creation time, when you change the target of the model or when you assign an extended model definition to the model.

Validate

Used to validate changes to object properties and to implement cascade updates. It is triggered when change tabs or click OK or Apply in the object property sheet.

You can define an error message that will appear when the condition is not satisfied. To do so, fill the message variable and set the %Validate% variable to False.

In the following example, the validate event handler verifies that a comment is added to the definition of an object when the user validates the property sheet. A message is displayed to explain the problem.

Function %Validate%(obj, ByRef message)
 if obj.comment = "" then 
  %Validate% = False
  message = "Comment cannot be empty"
 else
  %Validate% = True
 end if
End Function

CanLinkKind

[link objects only] Used to restrict the kind and stereotype of the objects that can be linked together. It is triggered when you create a link with a palette tool or modify link ends in a property sheet.

This event handler has two input parameters: its source and destination extremities. You can also use the sourceStereotype and destinationStereotype parameters. These are optional and used to perform additional checks on stereotypes.

In the following example, the source of the extended link must be a start object:

Function %CanLinkKind%(sourceKind, 
  sourceStereotype, destinationKind,
  destinationStereotype)
 if sourceKind = cls_Start Then
 %CanLinkKind% = True
 end if
End Function