Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "VIATRA2/UseCases/InvokeNativeCode"

(New page: =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...)
 
m (format updates)
 
Line 13: Line 13:
 
** '''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'''.  
 
** '''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.
 
** '''returns''' the type of the parameters to be returned.
<code lang="java">
+
 
 
  import org.eclipse.viatra2.natives.NativeFunctionParameter.ParameterType;
 
  import org.eclipse.viatra2.natives.NativeFunctionParameter.ParameterType;
 
  @VIATRANativeFunction(
 
  @VIATRANativeFunction(
Line 31: Line 31:
 
   /* ... */
 
   /* ... */
 
  }
 
  }
</code>
 
  
 
* 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 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.
Line 39: Line 38:
 
* 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.
 
* 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.
 
* 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.
<code>
+
 
let U = ref("UML.metamodel.Class"), A = undef in update A = clean(U);
+
let U = ref("UML.metamodel.Class"), A = undef in update A = clean(U);
</code>
+
 
  
 
[[Image:VIATRA2_UseCases_InvokeNativeCode_NativeASMfunctionsModelspaceView.png| Active native ASM rules in the gigantoman model space]]
 
[[Image:VIATRA2_UseCases_InvokeNativeCode_NativeASMfunctionsModelspaceView.png| Active native ASM rules in the gigantoman model space]]
Line 55: Line 54:
 
** 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.  
 
** 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.  
  
<code lang="java">
+
 
 
  public class TestNativeASMRule implements INativeASMRule {
 
  public class TestNativeASMRule implements INativeASMRule {
  
Line 99: Line 98:
 
   }
 
   }
 
  }
 
  }
</code>
 
  
 
** 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.
 
** 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.
<code>
+
 
 
machine testmachine
 
machine testmachine
 
...
 
...
Line 110: Line 108:
 
  rule testnativeasm(in Input) = print("Hello Viatra World ");
 
  rule testnativeasm(in Input) = print("Hello Viatra World ");
 
...
 
...
 
</code>
 

Latest revision as of 12:59, 19 March 2010

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 org.eclipse.viatra2.core2.nativefunction (extension point, provided by the viatra2 core) and register a class that implements the ASMNativeFunction interface.
  • Step2: Annotate the class file with the @VIATRANativefunction 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 @NativeFunctionParameter 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: enum ParameterType {MODEL_ELEMENT,STRING,INTEGER,DOUBLE,BOOLEAN,NATIVE};
  • NATIVE 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);


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 org.eclipse.viatra2.gtasm.interpreter.nativeasmrule extension point provided by the interpreter (INativeAMSRule 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 @native 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 testnativeasm rule in the testmachine 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 ");

...

Copyright © Eclipse Foundation, Inc. All Rights Reserved.