4. What are coding conventions?
“coding conventions are a set of guidelines for a specific programming
language that recommend programming style, practices and methods for
each aspect of a piece program written in this language.” wikipedia
Introduction
4
6. walkmod is a tool to...
• automatize the practice of code conventions in development teams (i.e
license usage).
• automatize the resolution of problems detected by code quality tools
(i.e PMD, sonar, findbugs).
• automatize the development and repetitive tasks i.e: creating basic CRUD
services for the entire model.
• automatize global code changes: i.e refactorings.
Introduction
6
8. requirements
• walkmod is a Java tool, so you need the java virtual machine (jdk) 1.6 or
higher in order to proceed.
Please, make sure that JAVA_HOME is set to the location of your JDK and
that $JAVA_HOME/bin is in your $PATH environment variable.
quick start
8
9. installation
• download walkmod-{version}.zip from walkmod.com.
• unzip the folder.The created folder is called$walkmod_home.
• update your environment variable $PATH with your$walkmod_home/
bin directory.
• run walkmod --version to verify that it is correctly installed.
quick start
9
10. walkmod.xml
• Create a walkmod.xml file in the root directory of your java project.
• Edit the file and put the following content.
quick start
<!DOCTYPE walkmod PUBLIC "-//WALKMOD//DTD" "http://www.walkmod.com/dtd/walkmod-1.0.dtd">
<walkmod>
<chain name="example-chain">
<reader path="${source directory}" />
<transformation type="walkmod:commons:import-cleaner" />
<writer path="${target directory}"/>
</chain>
</walkmod>
10
11. configure a project
• Replace ${source directory} from where read your java packages. i.e
src/main/java.
• Replace${target directory} from where write the new code. i.e src/
main/java. if ${source directory} = ${target directory}, your code
will be automatically replaced.
• imports-cleaner will remove unused imports of your project.
• writer will rewrite your code with a default eclipse formatting.Yo can
configure it.
quick start
11
12. run
Open your prompt and go to your project directory.
> cd {project directory}
Then, type:
> walkmod apply
And voila! your code has applied all declared conventions
(transformations) into your source code according a configuration file
called walkmod.xml
quick start
12
14. workflowhow it works
•All conventions are applied
with blocks of
transformations for each
source file.
•Transformations may
update the same sources or
creating/updating another
ones.
14
15. overview
• reader: reads the sources. i.e retrieves all files from a directory
recursively.
• walker: executes a chain of transformations for each source.
• transformation: updates or creates sources for the following
transformation.Transformations are connected like a pipe through a
shared context.
• writer: writes the sources. i.e using the eclipse formatter.
how it works
15
16. reader
• Reads the sources. By default, reads the folder src/main/java.
• Works with multiple include/exclude rules.
• Creates a resource object, whose content is iterated from the walker.
• Works for sources of any programming language.The resource object
could be a source folder, a parsed json file, etc..
• Is extensible. You only need to implement the reader and resource
interfaces.
how it works
16
17. reader configuration
<reader path="src/main/java" >
</reader>
how it works
type="walkmod:commons:file-reader"
<param name="my1stparam">my1stvalue</param>
<param name="my2ndparam">my2ndvalue</param>
<include wildcard="com/my_company/**" ></include>
<exclude wildcard="com/my_company/utils/**"></exclude>
the exclude and
include rules [optional]
the reader bean
[default]
the custom
params
[optional]
17
18. walker
• Executes a chain of transformations for each object allocated in a
resource. i.e all java source files of an specific folder.
• merges the output produced by transformations with existent
resources.
• invokes the writer with the final (and merged) output.
• analyzes and reports which changes have been produced by the chain
of transformations in each object.
• Is extensible. You only need to implement the walker interface.
how it works
18
19. walker configuration
<walker root-namespace="" >
<transformations>
<transformation >
</transformation>
</transformations>
</walker>
how it works
type="walkmod:commons:java-walker"
<param name="myparam">myvalue</param>
type="walkmod:commons:license-generator"
<param name="licenseFile">src/main/license-header.txt</param>
<transformation type=”walkmod:commons:import-cleaner” />
the walker
bean [default]
at least one
transformation must
be specified
the custom
params
[optional]
19
20. transformations
• modifies or creates objects that will be written.
• There are three ways to design a transformation. Using:
templates,
scripts,
or visitors.
how it works
20
22. why templates?
• Using templates is a well known practice in code generation, specially
in the backend of web applications (Velocity, JSP, freemarker..).
• Templates should be used to add code in source files.
• groovy is the default template engine.
• A set of interfaces must be implemented to work with your favorite
template engine.
how it works
22
23. template configuration
<!DOCTYPE walkmod PUBLIC "-//WALKMOD//DTD" "http://www.walkmod.com/dtd/walkmod-1.0.dtd">
<walkmod>
...
<transformation type="walkmod:commons:template" >
<param name="templates">
[ “src/main/groovy/dao.groovy”,
“src/main/groovy/web-services.groovy” ]
</param>
</transformation>
...
</walkmod>
<param name="templateEngine">walkmod:commons:groovy</param>
how it works
the template
engine[default]
the list of applied
templates
23
24. script transformations
import org.walkmod.lang.ast.body.ModifierSet;
import java.lang.reflect.Modifier;
import org.walkmod.lang.ast.body.FieldDeclaration;
for(type in node.types){
def fields = type.members.findAll({it instanceof FieldDeclaration});
for (field in fields){
int modifiers = ModifierSet.addModifier(field.modifiers, Modifier.PRIVATE);
modifiers = ModifierSet.removeModifier(modifiers, Modifier.PROTECTED);
modifiers = ModifierSet.removeModifier(modifiers, Modifier.PUBLIC);
field.setModifiers(modifiers);
}
}
how it works
groovy script to force private fields
24
25. why scripts?
• Scripts allow the design of inline transformations.
• Scripts should be used to apply simple modifications in source files.
• Support for multiple languages.Those which implement the standard
Java scripting interface. i.e. groovy, javascript, python..
how it works
25
26. script configuration
how it works
...
<transformation type="walkmod:commons:scripting" >
<param name="language">
groovy
</param>
<param name="location">
src/main/groovy/my-script.groovy
</param>
</transformation>
...
the location of the
applied script
the default
scripting
language
26
27. visitor transformations
public class HelloVisitor extends VoidVisitor<VisitorContext>{
...
@Overwrite
public void visit(MethodDeclaration md, VisitorContext ctx){
//TODO
}
@Overwrite
public void visit(FieldDeclaration fd, VisitorContext ctx){
//TODO
}
...
}
how it works
27
28. why visitors?
• Visitors are developed and compiled in java.They allow the creation of
complex and efficient transformations.
• To include transformations as plugins to be shared inside the
community.
• Visitors should be used to apply complex modifications in source files.
how it works
28
29. visitor configuration
how it works
<!DOCTYPE walkmod PUBLIC "-//WALKMOD//DTD" "http://www.walkmod.com/dtd/walkmod-1.0.dtd">
<walkmod>
<plugins>
<plugin groupId="mygroupId" artifactId="myartifactId" version="versionNumber">
</plugin>
</plugins>
...
<transformation type="mygroupId:myartifactId:my-visitor" >
<param name="param1">
value1
</param>
<param name="paramN">
valueN
</param>
</transformation>
...
</walkmod>
the bean name of
the visitor
the visitor
setteable values
29
30. writer
• writes each object allocated in a resource. i.e all java source files of a
specific folder.
• Has include/exclude rules.
• Is extensible. You only need to implement the writer interface.
• There are useful writer implementations, such as the storage of the
contents of a toString() object method or the eclipse formatter.
how it works
30
31. <writer path="src/main/java" >
</writer>
type="walkmod:commons:eclipse-formatter"
<param name="my1stparam">my1stvalue</param>
<param name="my2ndparam">my2ndvalue</param>
<include wildcard="com/my_company/**"/>
<exclude wildcard="com/my_company/utils/**" />
writer configuration
how it works
exclude and include
rules [optional]
writer bean
[default]
custom
params
[optional]
31
33. write less to do the same
query engine
MethodDeclaration method = null;
Collection members = type.getMembers();
Iterator it = members.iterator();
while (it.hasNext()){
BodyDeclaration member = (BodyDeclaration)it.next();
if (member instance of MethodDeclararion){
MethodDeclarion aux = (MethodDeclaration) member;
if(“execute”.equals(aux.getName()){
method = aux;
break;
}
}
}
type.methods.find({it.name.equals(“execute”)})
java code to
look up the
“execute”
method of a
type
equivalent gpath
expression
33
34. language features
• All queries have an object context and a query expression. By default, the
context is the root element of a parsed source file.
• The default query language is gPath (groovy), but you can change it for
your favorite language.
• Common used large query expressions can be referenced from Alias.
“TypeDeclaration.metaClass.getMethods = { -> delegate.members.findAll({it instanceof MethodDeclaration}); }”
query engine
34
35. queries from templates
Using the query object: ${query.resolve(“expr”)}.
query engine
import org.apache.log4j.Logger;
public class ${query.resolve("type.name")}{
public static Logger log = Logger.getLogger(${query.resolve("type.name")}.class);
}
template to add Loggers
35
36. queries from visitors
Implementing QueryEngineAware or extendingVisitorSupport.
query engine
public class MyVisitor extends VisitorSupport{
@Overwrite
public void visit(TypeDeclaration td, VisitorContext ctx){
Object result = query(
td, //context
“methods.find({it.name.equals(“foo”)})” //expr
);
}
}
visitor code with a gpath query
36
37. queries from scripts
accessing through a binding called query
query engine
..
for( type in node.types) {
def result = query.resolve(type, “methods”);
...
}
...
groovy script querying the type methods
37
40. why a merge engine?
• To avoid duplicate results by transformations (i.e duplicate a method)
in existing code.
• Simplify transformations. Otherwise, transformations must check many
conditions to avoid repeating code or overwriting it.
• Reuse transformations. transformations can specify a single fragment
to append or overwrite.
• Sometimes, developer changes (i.e. adding a new method) must be
respected by the engine.
merge engine
40
41. semantic merge
• Code is merged according to the meaning of its elements instead of
simply merging text.
• In semantic merge, the element location in a source file it is not
important.
• Only elements with the same identifier are merged. Indentifiable
element types must implement the interface mergeable.
merge engine
41
42. previous concepts
• local object is the current version of an element.
• remote object is the modified version of an element generated by a
single transformation. It may be a fragment to add in a local object.
merge engine
42
43. merge policies
Configurable and extensible merge policies for each object type.
merge engine
Object
merge
policy
Finds the equivalent local version of a remote (and thus,
generated) object and choose its final value of its fields.
These objects must be identifiable to be searched and found.
These policies should be applied for fields, methods, types..
Type
merge
policy
select which merge action do for local and remote objects which
are not identifiable, although being instances of the same class. i.e
policies for the statements of an existent method.
43
44. object merge policies
• append policy only writes new values for null fields. Otherwise, these
are not modified.
• overwrite policy modifies all field values of a local object for those
generated by a transformation.
merge engine
44
45. type merge policies
• assign policy only writes the remote values. i.e replacing the list of
statements of a method for the generated list.
• unmodify policy only writes the local values. i.e to respect the
developer changes in the statements of an old transformation.
merge engine
45
47. how to extend walkmod?
• Creating new plugins (java libraries) and deploying them into a maven
repository (public or private). See repo.maven.apache.org
• All walkmod extensions need a plugin descriptor of their components
in the META-INF/walkmod directory inside the jar library.
plugins
47
48. plugin descriptor
• Plugin descriptor is a XML file with the name walkmod-xxx-plugin.xml
which follows the spring bean configuration.
• New readers, writers, walkers or transformations must be specified
with a unique name “groupId:artifactId:name” as a spring bean in the
plugin descriptor.
plugins
<beans>
...
<bean id="walkmod:commons:import-cleaner" class="org.walkmod.visitors.ImportOrganizer" />
...
</beans>
48
50. plugin usage (II)
Beans declared in a plugin descriptor can be referenced from walkmod.xml
using the type attribute.
plugins
<walkmod>
<plugins>
<plugin groupId="walkmod" artifactId="walkmod-commons-plugin" version="1.0">
</plugin>
</plugins>
<chain name="my-chain">
...
<transformation type="walkmod:commons:imports-cleaner" />
...
</chain>
</walkmod>
<transformation type="walkmod:commons:imports-cleaner" />
50
51. commands
> walkmod install
Downloads all your plugins and their dependencies.
> walkmod apply [chain] [--offline]
Downloads all your plugins and their dependencies and executes the
chain. If offline is present, it executes the chain without downloading
missing plugin libraries.
plugins
51
52. plugins backend
• Walkmod embeds apache ivy to download plugins from maven
repositories.
• Custom repositories are in ${walkmod-home}/conf/ivysettings.xml
• All plugin jars and their dependencies are files loaded dynamically into
a new classloader.
• All beans used and declared in plugin descriptors are resolved by the
spring source engine using the new classloader.
plugins
52
