Integrating Kermeta and java code has never been that easy !

K3 action language is built as an extension to Xtend that in turn is able to fully reuse existing java bytecode. Java code can be used from Xtend/K3 and vice versa.

As all other versions of Kermeta, K3 Action Language leverages the open-class mechanism. It allows to "re-open" existing meta-classes of a metamodel to insert new features such as attributes, references, or operations. Please note that return types of aspects methods cannot be inferred: they must be explicitly written!

package mypackage

import fr.inria.diverse.k3.al.annotationprocessor.Aspect

import mypackage.OtherClass
import static extension mypackage.OtherClassAspect.*

@Aspect(className=OtherClass)
class OtherClassAspect {
	var int foo = 1

    def void display (){
         prinln("I am OtherClassAspect")
         // The keyword _self must be used to refer to attributes and operations of the class and aspect.
         _self.foo = 2
         _self.callingOnOperationOfOtherClass()
    }
}

This mechanism serves as the basis for the definition of aspects on metamodels elements, enabling aspect-oriented modeling that helps to model complex software artifacts composed of intertwined and cross-cutting concerns.

Typical use of such construct are the Visitor and Interpreter design patterns which are implemented in a more elegant and readable way with Aspect Oriented languages than with with classical Object Oriented languages.

Figure 1.1. Object Oriented visitor versus Aspect Oriented visitor

This annotation set allows to do some design by contract programming.

Known limitation : there is no way to prevent the contracts from doing some side effects on the model.

Defining an aspect on a class is done by adding the annotation Aspect on the class corresponding to the aspect. The annotation parameter className will indicates which is the base class that will be augmented.

package blogsite.aspects

import fr.inria.diverse.k3.al.annotationprocessor.Aspect 

import blogsite.Blog

@Aspect(className=Blog) 
class BlogAspect {
    def void display (){
         prinln("I am BlogAspect")
    }
}

In an aspect you can use the attributes and operations of both the augmented class and the aspect itself.

In aspects, the keyword "this" must not be used. Use the keyword "_self" instead.

@Aspect(className=Blog)
class BlogAspect {
    int blogVersion = 1 

    def void changeTitle (String  newTitle, int newVersion){
         // The keyword _self must be used to refer to attributes and operations of the class and aspect.
         _self.blogVersion = newVersion 
         _self.title =  newTitle 
    }
}

@Aspect(className=typeof(OtherClass))

To use the aspect, you need to import the correct classes and indicates to xTend thant some additionnal features can come from the aspect.

This is done using the special import import static extension which enable the use of the additions declared in the aspect.

package blogsite.demo

import blogsite.Blog
import blogsite.aspects.BlogAspect

import static extension blogsite.aspects.BlogAspect.* 

class Main {
    def static void main(){
      val Blog b1 = new Blog
      b1.display() 
    }
}

@Aspect(className=Blog)
class BlogAspect2 {
    int title = 1 
}

import static extension blogsite.aspects.BlogAspect2.*

class Main {
    def static void main(){
      val Blog b1 = new Blog
      println( b1.title) 
      println( BlogAspect2.title(b1) 
    }
}

An Aspect class can inherit fields and methods from another class. The simple inheritance is acheived using the extends keyword from Xtend.

package blogsite.aspects

import fr.inria.diverse.k3.al.annotationprocessor.Aspect
import fr.inria.diverse.k3.al.annotationprocessor.OverrideAspectMethod

import blogsite.HasAuthor
import blogsite.Post

import static extension blogsite.HasAuthor.*
import static extension blogsite.PostAspect.*

@Aspect(className=HasAuthor)
class HasAuthorAspect {

    def String display (){
        returns _self.author
    }
}

@Aspect(className=Post)
class PostAspect extends HasAuthorAspect{ 

    @OverrideAspectMethod 
    def String display (){
        returns _self.title + " by " + _self.author
    }
}

A call to a super operation can be done by writing super_ followed by the name of the operation. Do not forget to use _self to handle elements of the class or aspect.

The previous example could have been written like this:

package blogsite.aspects

import fr.inria.diverse.k3.al.annotationprocessor.Aspect
import fr.inria.diverse.k3.al.annotationprocessor.OverrideAspectMethod

import blogsite.HasAuthor
import blogsite.Post

import static extension blogsite.HasAuthor.*
import static extension blogsite.PostAspect.*

@Aspect(className=Post)
class PostAspect extends HasAuthorAspect{

    @OverrideAspectMethod
    def String display (){
        returns _self.title + " by " + _self.super_display() 
    }
}

Even if Java allows only one inheritance via extends. When using EMF, it is legal to inherit from several class. The underlying framework will take care to implement a pattern using Interfaces.

Our aspects must also be able to deal with that situation.

The @Aspect annotation can then take a with attribute to indicate this inheritance.

If the following ecore model and its java implementation, there is a multi-inheritance from Child class to 3 ParentX classes.

Figure 3.2. Metamodel used as base for the multi inheritance example

then, in order to correctly reflect these inheritances in the aspects, we will define the following.

// [..]

import static extension multiparents.Parent1.*
import static extension multiparents.Parent2.*
import static extension multiparents.Parent3.*
import static extension multiparents.Child.*

@Aspect(className=Parent1) 
class Parent1Aspect {
   def void someParent1Method(){
      // [..]
   }
}
@Aspect(className=Parent2)
class Parent2Aspect {
   def void someParent2Method(){
      // [..]
   }
}
@Aspect(className=Parent3)
class Parent3Aspect {
   def void someParent3Method(){
      // [..]
   }
}

@Aspect(className=Child, with=#[ParentAspect2, ParentAspect3] ) 
class ChildAspect extends Parent1Aspect{ 
   def void someMethod(){
      _self.someParent1Method()
      _self.someParent2Method()
      _self.someParent3Method()
   }
}

Figure 3.3. Multi inheritance example with aspects

The Modeling environment can also be set to use EMF/Ecore when checking the Use EMF option. In this case it will add the dependencies to the correct jars dependeing on the dependency management Eclipse plugin with Ecore/EMF.

When set to Plug-in the project uses the Eclipse Plugin nature for defining the dependencies. So all the K3 jar and xTend jar will be referenced in the manifest.mf of the project.

When set to Standalone In that mode, all the depencies are copied in a lib folder. This includes K3 jar, but also xTend jar. It is based on the eclipse standard java compiler for defining dependencies. This mode can be useful as a base for small project with few dependencies

When set to Maven In that mode, the project will be a maven project and dependencies will be resolved using maven.

when clicking on next in the first page your can acces to the templates

These templates allows to create typical project structures for various needs.

One of the most useful is the Use Ecore Basic aspect which asks the user for an initial Ecore model (and its project). With this ecore model, it will automatically create an aspect class for each metaclasses in the ecore. It takes care of replicating the inheritance tree in the aspects classes.

Let’s consider the following K3 code that adds a String attribute to the java.io.File class:

import static extension k3project.SampleXMLFileAspect.*

@Aspect(className=java.io.File )
class SampleXMLFileAspect {
	public String contentType = ""
}
//[..]
    val f = new File("toto.txt")
    f.contentType = "txt"

It will be compiled in 3 Java classes : SampleXMLFileAspect, SampleXMLFileAspectFileAspectContext and SampleXMLFileAspectFileAspectProperties.

SampleXMLFileAspect is the public interface that declares all public static methods that are make available with the import static extension. A technical part is kept in private.

SampleXMLFileAspectFileAspectProperties is the companion object that is associated to the base object.

SampleXMLFileAspectFileAspectContext implements the map that allows to get the companion object SampleXMLFileAspectFileAspectProperties via the _self keyword.

public class SampleXMLFileAspectFileAspectProperties {
  public String contentType = "";
}

public class SampleXMLFileAspect {

  public static String contentType(final File _self) { 
    k3project.SampleXMLFileAspectFileAspectProperties _self_ = k3project.SampleXMLFileAspectFileAspectContext.getSelf(_self);
    Object result = null;
    result =_privk3_contentType(_self_, _self);
    return (java.lang.String)result;
  }

  public static void contentType(final File _self, final String contentType) { 
    k3project.SampleXMLFileAspectFileAspectProperties _self_ = k3project.SampleXMLFileAspectFileAspectContext.getSelf(_self);
    _privk3_contentType(_self_, _self,contentType);
  }
    protected static String _privk3_contentType(final SampleXMLFileAspectFileAspectProperties _self_, final File _self) {
    try { 
    	for (java.lang.reflect.Method m : _self.getClass().getMethods()) {
    		if (m.getName().equals("getContentType") &&
    			m.getParameterTypes().length == 0) {
    				Object ret = m.invoke(_self);
    				if (ret != null) {
    					return (java.lang.String) ret;
    				}
    		}
    	}
    } catch (Exception e) {
    	// Chut !
    }
    return _self_.contentType;
  }

  protected static void _privk3_contentType(final SampleXMLFileAspectFileAspectProperties _self_, final File _self, final String contentType) { 
    _self_.contentType = contentType; try {
    	for (java.lang.reflect.Method m : _self.getClass().getMethods()) {
    		if (m.getName().equals("setContentType")
    				&& m.getParameterTypes().length == 1) {
    			m.invoke(_self, contentType);
    		}
    	}
    } catch (Exception e) {
    	// Chut !
    }
  }
}

public class SampleXMLFileAspectFileAspectContext {
  public final static SampleXMLFileAspectFileAspectContext INSTANCE = new SampleXMLFileAspectFileAspectContext();

  public static SampleXMLFileAspectFileAspectProperties getSelf(final File _self) {
    		if (!INSTANCE.map.containsKey(_self))
    			INSTANCE.map.put(_self, new k3project.SampleXMLFileAspectFileAspectProperties());
    		return INSTANCE.map.get(_self);
  }
  private Map<File, ModuleAspectFileAspectProperties > map =
  	new java.util.WeakHashMap<java.io.File, k3project.ModuleAspectFileAspectProperties > ();

  public Map<File, ModuleAspectFileAspectProperties> getMap() {
    return map;
  }

}