[API] Provide a better API

[echebbi]

Contributes to #123

Changes

• I've implemented most of the changes proposed by Decide of an API and use it #123 except the mechanism allowing to access runtime data
• cleaned up some parts of the code (dead code, redundancies, etc.)
• added JavaDoc where code was unclear
• removed the org.eclipse.emf.ecoretools.ale plug-in
• turned the org.eclipse.emf.ecoretools.ale.tests plug-in into a plug-in fragment to ease testing of internal classes
• moved some classes to other packages

How to review

This PR impacts a lot of files but that's mainly because I renamed some classes and moved others. There's actually almost no change in features: I mainly introduced new interfaces (IAleInterpreter) and enforced the use of others (IAleEnvironment). Both automatic and manual testing have failed to find bugs so I'm pretty confident in not having introduce important regressions.

To review important changes I would advise to:

• take a look at IAleEnvironment
• take a look at AbstractAleEnvironment
• take a look at AleInterpreter
• take a look at BehaviorsParser (ex AstBuilder) and AntlrAstToBehaviorsAstAdapter (ex ModelBuilder)
• check package hierarchy in org.eclipse.emf.ecoretools.ale.core

API

Lots of interfaces and classes are prefixed by Ale. It feels redundant and I can't decide whether it's worth it.

See also unit tests for examples.

Task 1: create a new ALE project

IWorkspace workspace = ResourcesPlugin.getWorkspace();
WorkspaceAleProject.Description desc = new WorkspaceAleProject.Description(
    isUsingAnExistingEcoreModel, ecoreModelFilePath, 
    ecorePackageName, 
    hasSiriusRepresentation, 
    hasJavaNature
);
Template project = new WorkspaceAleProject.Template(workspace, desc);
project.create(projectName, projectPath, new NullProgressMonitor());

Task 2: retrieve an existing ALE project

IProject    project    = ResourcesPlugin.getWorkspace().getRoot().getProject("fsm");
IAleProject aleProject = IAleProject.from(project);

Task 3: manipulate an ALE environment

/*
 * getEnvironment() returns the *applicable* environment, which may be
 * either stored as project preferences or declared in a .dsl file
 */
IAleEnvironment env = aleProject.getEnvironment();

// Or dynamically create a new environment
IAleEnvironment env = IAleEnvironment.fromPaths(
       asList("helloworld.ecore"), asList("helloworld.ale"));

// Persist given environment in the .dsl file
try (FileBasedAleEnvironment dsl = IAleEnvironment.fromFile(new File("helloworld.dsl"))) {
    dsl.save(env);
}

Task 4: manipulate ALE classes

IBehaviors    behaviors  = env.getBehaviors();
Set<EPackage> metamodels = env.getMetamodels();

The IBehaviors interface eases manipulation of dynamic ALE elements.

Task 5: execute an ALE program

IAleProject aleProject = IAleProject.from(project);
try (IAleEnvironment env = aleProject.getEnvironment()) {
    IAleInterpreter interpreter = env.getInterpreter();

    EObject      caller = environment.loadModel(createURI("HelloWorld.xmi")).get(0);
    Method       main   = environment.getBehaviors().getMainMethods().get(0);
    List<Object> args   = emptyList();

    IAleInterpreter   interpreter = environment.getInterpreter();
    IEvaluationResult result      = interpreter.eval(caller, main, args);
}

The environment itself is AutoCloseable and responsible for releasing resources (see AbstractAleEnvironement::close for the actual implementation).

[echebbi]

@dvojtise would you have the time to take a look at this PR before I squash & merge the commits? I'd appreciate a review.

[dvojtise]

Lots of interfaces and classes are prefixed by Ale. It feels redundant and I can't decide whether it's worth it.

I think that the prefix is short enough to keep it. Additionally, ALE is one of the meta-approach used in GEMOC, and we may have to mix approaches, in such situation, having clear class names will help (this is always a pain in java to have 2 classes from different packages that have the same name because java doesn't provide local rename mechanism such as other languages)

IMO, every class that might be used from outside (ie not internal) should keep the Ale prefix

[dvojtise]

Globally the proposed changes make sense and improve the API (only some class names that could be improved)

once accepted, I would appreciate a PR in https://github.com/eclipse/gemoc-studio-execution-ale/ to report these changes to the GEMOC ALE engine that heavily use this API (I quickly tried renaming, but I think it could also be simplified thanks to the API addition you provided)

[echebbi]

I think this PR can now be merged; @dvojtise are you OK with the changes?

[dvojtise]

yes, looks good to merge :-)