Difference between revisions of "MoDisco/Components/Java/Documentation/0.9"

Revision as of 08:17, 27 July 2011

Java Metamodel

The Java metamodel : it is the reflection of the Java language, as defined in version 3 of "Java Language Specification" from Sun Microsystems ("JLS3" corresponds to JDK 5).

The Java metamodel contains 126 metaclasses. To better understand it, this page will introduce its main features (metaclasses and links).

You could also browse the model definition, java.ecore available in sources (see source repository).

A good tip is also to see the javadoc associated to the metamodel implemented by the Eclipse team in the JDT (Java Development Tool) project. This metamodel and Java are very similar.

Main metaclasses

ASTNode

Every metaclass (apart from the Model metaclass) inherits from ASTNode. As its name indicates, ASTNode represents a graph node. ASTNode has a reference to the Comment metaclass because almost every java element can be associated to a comment (block or line comment and Javadoc). More details in the "Comment" section.

ASTNode metaclass

Model, Package, AbstractTypeDeclaration

The root element of each Java model is an instance of the "Model" metaclass. It is a translation of the concept of java application, so it contains package declarations (instances of the Package metaclass). And package declarations contain type declarations (instances compatible with the AbstractTypeDeclaration metaclass), and so on...

Model, Package & type declaration superclass

NamedElement & notion of Proxy

A lot of java elements are "named", and this name could be considered as an identifier : methods, packages, types, variables, fields, ... So all the corresponding metaclasses inherit from the NamedElement metaclass.

Another goal of this metaclass is to indicate whether an element is part of the current Java application or not (element from an external library of from the JDK). So, external elements are tagged as proxy through a dedicated attribute and can be easily filtered. For example, instruction "System.out.println" has been decomposed into three named elements (one class, one variable and one method) the definitions of which are not part of the current Java application. So attribute "proxy" of these elements has been initialized to true.

NamedElement and its hierarchy

TypeAccess, PackageAccess, SingleVariableAccess, UnresolvedItemAccess

To represent links between Java elements, metaclasses TypeAccess, PackageAccess, SingleVariableAccess and UnresolvedItemAccess were introduced. Each allows to navigate directly to a NamedElement (proxy or not) in the graph.

TypeAccess

PackageAccess

SingleVariableAccess

MethodInvocation

BodyDeclaration

A type declaration has different kinds of contents : fields, methods, static block, initialization block or other type declarations. All of these elements are of type BodyDeclaration metaclass.

BodyDeclaration and its hierarchy

Expressions

++i

Expression and its hierarchy

Statements

if, while, for, do, ...

Statement and its hierarchy

Zoom on comments

There are three kinds of comments : line comments (//), block comments (/* */) and javadoc comments (/** */). Every comment contains text fragments, but we can have more information on javadoc comments (Javadoc metaclass): they can also contain javadoc tags that are identified and collected through instances of the TagElement metaclass.

Comment and its hierarchy

Zoom on annotations

Official usage of annotations has been introduced in version 5 of the JDK. To handle them, annotation declarations are managed as type declarations (AnnotationTypeDeclaration metaclass) with specific attributes (AnnotationTypeMemberDeclaration metaclass). And annotation usages are translated into instances of the Annotation metaclass, which reference corresponding annotation declarations. And parameters are translated into instances of the MemberValuePair metaclass. Some statements also have a list of annotations.

Annotation

Zoom on generics

Version 5 of the JDK also introduced the concept of "generics". Generic types of method declarations are translated into instances of TypeDeclaration of AbstractMethodDeclaration metaclass with arguments as instances of the TypeParameter metaclass. Uses of these generics are translated into instances of the ParameterizedType metaclass which reference concrete elements (type and type arguments).

A specific case of type argument is the "wildcard" (for example "<? extends X>"). There is a specific metaclass to handle it : WildCardType.

Generics

Associated Discoverers

The main discoverer available for this metamodel : Java Discoverer

Java Discoverer

The goal of the Java Discoverer plug-in is to allow practical extractions of Java models from Java projects.

Description

This plug-in aims at analyzing Java source code compliant with version 3 of "Java Language Specification" from Sun Microsystems and providing a model describing the information found, conforming to the Java metamodel.

A Java model contains the full abstract syntax tree of the Java program: each statement such as attribute definition, method invocation or loop is described. In addition, links between elements are resolved (by resolved link we mean for instance a link between a method invocation and the declaration of this method, or between the usage of a variable and its declaration). The model can thus be seen as an abstract syntax graph (ASG).

User manual

The plug-in provides the user with a contextual menu to easily create models.

By right-clicking on a Java Project in the Eclipse Package Explorer view, you can quickly create the Java model of your application (see next Figure).

Menus in Eclipse to create model from source code

A discovery parameters dialog opens to let you specify the parameters of the discovery:

Discovery parameters dialog

• Set SERIALIZE_TARGET to true if you want to save the model to a file
• You can define TARGET_URI to the location of a file in your workspace. If it is not defined and SERIALIZE_TARGET is true, a model file will be created in the project.
  Beware: the file will be overwritten if it already exists!
• You can filter the classes to analyze using regular expressions, by setting INCLUDED_ELEMENTS_REGEX and/or EXCLUDED_ELEMENTS_REGEX
• You can specify additional dependencies (projects or libraries) that you want to analyze and add to the model, by selecting them in the dialog that opens when you click the ELEMENTS_TO_ANALYZE parameter:

Choosing the elements to analyze

Once launched, a progress dialog will appear as soon as the operation begins. Depending on the size of your application, the reverse engineering process might take some time to complete:

Progress dialog

At the end of the process, the newly created model file is added to the root of your project if you set SERIALIZE_TARGET to true:

Java model in the package explorer

And the model is opened in the default model browser if you selected Open model in editor after discovery:

Java model viewed with the MoDisco model browser

The Java XMI files (with a filename ending in "_java.xmi" by convention) can be opened in any model browser:

"Open With" on a Java model

Discoverer API

First, add the following plug-in dependencies to your project (Require-Bundle in your Manifest.MF):

• org.eclipse.gmt.modisco.java
• org.eclipse.modisco.java.discoverer
• org.eclipse.modisco.infra.discovery.core

There are several Java discoverer classes that do the same discovery but on different inputs:

• DiscoverJavaModelFromJavaProject : from an IJavaProject (defined in jdt.core)
• DiscoverJavaModelFromProject : from an IProject
• DiscoverJavaModelFromClassFile : from an IClassFile (defined in jdt.core)
• DiscoverJavaModelFromLibrary : from an IPackageFragmentRoot (for jars; defined in jdt.core)

You can easily discover a Java model programmatically. For example, to discover a Java model from a Java project:

DiscoverJavaModelFromJavaProject discoverer = new DiscoverJavaModelFromJavaProject();
javaDiscoverer.discoverElement(javaProject, monitor);
Resource javaResource = javaDiscoverer.getTargetModel();

To have a monitor to pass to the discoverElement method, you can either call the discoverer in an Eclipse Job, or pass a new NullProgressMonitor if you don't need progress reporting.

Once you have the Java Resource, you can use the standard EMF API to read model elements. For example, to get the root:

Model javaModel = (Model) javaResource.getContents().get(0);

To print the list of Java classes in the model:

EList<ClassFile> classFiles = javaModel.getClassFiles();
for (ClassFile classFile : classFiles) {
    System.out.println(classFile.getName());
}

Discoverer Benchmark

Installing the benchmark

The Java discoverer benchmark is not included in the MoDisco SDK feature on the Eclipse Indigo update site. You must install it from the MoDisco update site:

• http://download.eclipse.org/modeling/mdt/modisco/updates/release/
• Install the feature named MoDisco Java discoverer benchmark feature

Launching the benchmark

• create a file named javabenchconfig.txt, containing the name of each Java project to benchmark (each on a separate line)
• right-click on this file, and select Discovery > Discoverers > Java Benchmark > Benchmark Java Discover Time...

launching the benchmark

• In the parameters dialog, set the number of iterations (parameter ITERATIONS), set SERIALIZE_TARGET to true, and then click OK

• This should create a model named javabench.xmi in your project (or the location of your choice set in TARGET_URI)
• Right-click on this javabench.xmi model file, and select Discovery > Discoverers > Java Benchmark > Generate HTML Report :

generating the html report

• Click OK in the parameters dialog
• This should create two files:
  • javaDiscoveryBenchmark.html : the benchmark report in HTML, that you can view with any Web browser
  • executionTimeByProjectSize.png : a graph referenced by the HTML report, showing the discovery time as function of project size

Benchmark results

Plug-in org.eclipse.modisco.java.discoverer.benchmark implements a benchmark for the Java

Here is an abridged version of the full report generated by org.eclipse.modisco.java.discoverer.benchmark.

Execution time by project size

System Information

Results Overview

Java Generation

The goal of the Java Generation plug-in is to allow Java code generation from a Java model. Such a generation will fulfill some of the requirements for Legacy refactoring & migration.

Description

This plug-in proposes Acceleo MTL modules for generating Java files conforming to Java models. Templates are contained in two modules :

• Structures modules : top level templates for generating classes/method/field declarations
• Statements modules

Java models are obtained with Java Discoverer component.

Considering a Java legacy, a minimal migration/refactoring chain will involve :

• A Java model discovery step
• A M2M transformation step
• A Java generation code step with the current component

User manual

A prerequisite is a Java model. Please refer to the Java Discoverer user manual.

To launch a Java generation:

• Add org.eclipse.gmt.modisco.java.generation in your plugin dependencies and use the GenerateJavaExtended main method with input model and target folder as parameters. The code should look like this :

GenerateJavaExtended javaGenerator = new GenerateJavaExtended(URI.createFileURI("C:/.../my.javaxmi"),
    new File("C:/.../myOutputFolder"), new ArrayList<Object>());
javaGenerator.doGenerate(null);

Or

• Checkout org.eclipse.gmt.modisco.java.generation into the workspace from Eclipse SVN repository, and then Create an Accelo launch configuration pointing to GenerateJavaExtended java class, and specify the input model and target folder. Use "Acceleo plugin Application" runner in launch configuration. If an error "could not load class GenerateJavaExtended" occurs, it may be caused by an already installed 'org.eclipsxe.gmt.modisco.java.generation' plugin, thus you may use "Java Application" runner (however, with this second runner, Java code formating step, launched at the end of the generation, will not work if the classpath is not completed with the required related java libraries.

Java model to KDM model transformation

The goal of the "Java to KDM transformation" discoverer is to get a KDM model from a Java model. It is useful when the only available information on a java source code is contained in a Java model. Even without the source code it is then possible to get a KDM representation.

User Manual

A prerequisite is a Java model. Please refer to the Java Discoverer user manual.

Discovering a KDM code model from a Java model

Once launched, a progress dialog will appear as soon as the operation begins. Depending on the size of your java model, the transformation might take some time to complete:

Progress bar during java model transformation

At the end of the process, the newly created model files are added to the root of your project:

KDM model

And the model is automatically opened in the default model browser if you selected "Open model in editor after discovery":

KDM model in the MoDisco Model Browser

KDM Discoverer API

This discoverer can also be called programmatically (see the Java Discoverer API). Use either:

• DiscoverKDMModelFromJavaModel
• DiscoverKDMModelFromJavaProject
• DiscoverKDMModelFromProject

from plug-in org.eclipse.modisco.java.discoverer

Install

You can install the Java discoverer and associated metamodel from the MoDisco update site.

Source Repository

All the source code is stored in the Eclipse public source repository:

• Java metamodel : https://dev.eclipse.org/svnroot/modeling/org.eclipse.mdt.modisco/plugins/trunk/org.eclipse.gmt.modisco.java/
• Java discoverer : https://dev.eclipse.org/svnroot/modeling/org.eclipse.mdt.modisco/plugins/trunk/org.eclipse.modisco.java.discoverer/
• KDM to UML discoverer : https://dev.eclipse.org/svnroot/modeling/org.eclipse.mdt.modisco/plugins/trunk/org.eclipse.modisco.kdm.uml2converter/