View source for VIATRA2/UseCases/InvokeNativeCode

=Invoking Native java code =

The VIATRA2 framework support two ways to invoke native Java code, namely: native ASM rule and function invocation.

== Native ASM function ==

For creating a native ASM function you should follow these steps:

* Step1: Create an extension to the <code>org.eclipse.viatra2.core2.nativefunction</code> (extension point, provided by the ''viatra2 core'') and register a class that implements the <code>ASMNativeFunction</code> interface.
* Step2: Annotate the class file with the <code>@VIATRANativefunction</code> annotation. An example annotation is shown below.
** '''name''' the name of the ASM rule that will be used in the VTCL code
** '''remark''' comment on the native ASM function 
** '''params''' A list containing <code>@NativeFunctionParameter</code> annotations. Each annotation has four parameters: (i) '''name''' the name of the parameter, (ii) '''remarks''' description of the parameter, '''type'''  type of the parameter and finally '''isVarArgs'''. 
** '''returns''' the type of the parameters to be returned.

 import org.eclipse.viatra2.natives.NativeFunctionParameter.ParameterType;
 @VIATRANativeFunction(
    	name="clean",
    	remark="Deletes model elements faster than the \"delete()\" rule (recursive).",
        params={
       @NativeFunctionParameter(
           name = "entities", 
           type = { ParameterType.MODEL_ELEMENT }, 
           isVarArg = true,
                description="model element references to top-level entities to be deleted."
                 )	
        }, returns = { ParameterType.BOOLEAN }
        )
 public class CleanFunction implements ASMNativeFunction 
 {
   /* ... */
 }

* Types and return types are arrays because one might have to support multiple types (accept STRING, INTEGER, etc.). The return type might vary depending on the type of objects passed.
* Types include: <code> enum ParameterType {MODEL_ELEMENT,STRING,INTEGER,DOUBLE,BOOLEAN,NATIVE}; </code>  
* <code>NATIVE</code> type means that it will not be processed by the interpreter and can contain any kind of java.lang.Object. It can be used to pass parameters between native ASM functions and rules within VTCL code.

* Step3:  You can check all active native ASM functions in the VIATRA2 Model Space view under the '''native functions''' element separately  for each open model spaces. All information described in the Annotations is also available in the Properties view.
* Step4:  Native ASM functions can be called whenever a simple ASM function can be used. The following simple VTCL code snippet invokes the '''clean''' function on the U variable (which holds the Class entity of the UML metamodel) and deletes it.

 let U = ref("UML.metamodel.Class"), A = undef in update A = clean(U);


[[Image:VIATRA2_UseCases_InvokeNativeCode_NativeASMfunctionsModelspaceView.png| Active native ASM rules in the gigantoman model space]]


== Native ASM Rule ==

VIATRA2 supports native ASM rules that can be invoked within a VTCL program. They can be created by following:

* Step 1: You have to implement the <code>org.eclipse.viatra2.gtasm.interpreter.nativeasmrule</code> extension point provided by the interpreter (<code>INativeAMSRule</code> interface)
* Step 2: The ID String parameter of the implemented class needs to be equal with the FQN of the ASM rule to be changed with the native representation.
* Step 3: Annotate the ASM rule with the <code>@native</code> annotation in order to execute its native representation ( don't foget that the FQN of the ASM rule must be equal with the ID of its native representation)
** A sample native ASM rule implementation is shown below. It replaces the <code>testnativeasm</code> rule in the <code>testmachine</code> machine. It can be invoked with any number of parameters (this is important as it is not necessary to follow the signature of the defining ASM rule!) and writes out the variables' name-value pairs. 


 public class TestNativeASMRule implements INativeASMRule {

 /**
  * The textual description of the ASM rule.
  */
  public String getDescription() {
    return "A test native ASM rule";
  }

  /**
  * The unique ID of the native ASM rule. Has to be the FQN of the ASM rule that it will replace
  */
  public String getID() {
    return "testmachine.testnativeasm";
  }

 /**
  * The name of the native ASM rule.
  */
  @Override
  public String getName() {
    return "testnativeasm";
  }

  /** This function will be called by the GTASM interpreter instead of the ASM rule invocation.
  * @param msp The model space of the invocation context
  * @param params The variable to term mapping table. All return parameters will have to added to the map
  * @return true if the execution succeeded false in all other case which will indicate the same behaviour as in case of the ASM rule failure
  * @throws ViatraTransformationException
  */
  public Boolean invoke(IModelSpace msp, Map<Variable, Object> params)
      throws ViatraTransformationException {
    System.out.println("Hello Native ASM World! The input parameters and their values are:");
    if(params.size() == 0)
      System.out.println("None");
    else
      for(Entry<Variable,Object> entry: params.entrySet())
        {
        System.out.println("Variable "+entry.getKey().getName()+" = "+entry.getValue().toString());
        }
    return true;
  }
 }

** You can invoke the example native ASM rule with the following code snippet. You just have to simply use the '''@native''' annotation before the ASM rule's definition and the interpreter will invoke the native representation instead the one described in the VTCL file.

machine testmachine
...
 rule main() = ... call testnativeams("Test Data"); ...
 
 @native
 rule testnativeasm(in Input) = print("Hello Viatra World ");
...