Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
walkmod
a tool to apply coding conventions
1
2
how it works
introduction
query engine
merge engine
plugins
quick start
3
What are coding conventions?
“coding conventions are a set of guidelines for a specific programming
language that recommend...
examples
• Naming conventions
• Code formatting
• Code licenses
• Code documentation
• Code refactoring
• Apply programmin...
walkmod is a tool to...
• automatize the practice of code conventions in development teams (i.e
license usage).
• automati...
how it works
introduction
query engine
merge engine
plugins
quick start
7
requirements
• walkmod is a Java tool, so you need the java virtual machine (jdk) 1.6 or
higher in order to proceed.
Pleas...
installation
• download walkmod-{version}.zip from walkmod.com.
• unzip the folder.The created folder is called$walkmod_ho...
walkmod.xml
• Create a walkmod.xml file in the root directory of your java project.
• Edit the file and put the following co...
configure a project
• Replace ${source directory} from where read your java packages. i.e
src/main/java.
• Replace${target...
run
Open your prompt and go to your project directory.
> cd {project directory}
Then, type:
> walkmod apply
And voila! you...
how it works
introduction
query engine
merge engine
plugins
quick start
13
workflowhow it works
•All conventions are applied
with blocks of
transformations for each
source file.
•Transformations may...
overview
• reader: reads the sources. i.e retrieves all files from a directory
recursively.
• walker: executes a chain of ...
reader
• Reads the sources. By default, reads the folder src/main/java.
• Works with multiple include/exclude rules.
• Cre...
reader configuration
<reader path="src/main/java" >
</reader>	
how it works
type="walkmod:commons:file-reader"
<param name...
walker
• Executes a chain of transformations for each object allocated in a
resource. i.e all java source files of an spec...
walker configuration
<walker root-namespace="" >		
<transformations>	 	
<transformation >
	 	 	
	 	 </transformation>
	 	
...
transformations
• modifies or creates objects that will be written.
• There are three ways to design a transformation. Usi...
template transformations
package ${query.resolve("node.package.name")};
public class ${query.resolve("type.name")}{
${for ...
why templates?
• Using templates is a well known practice in code generation, specially
in the backend of web applications...
template configuration
<!DOCTYPE walkmod PUBLIC "-//WALKMOD//DTD" "http://www.walkmod.com/dtd/walkmod-1.0.dtd">
<walkmod>
...
script transformations
import org.walkmod.lang.ast.body.ModifierSet;
import java.lang.reflect.Modifier;
import org.walkmod...
why scripts?
• Scripts allow the design of inline transformations.
• Scripts should be used to apply simple modifications ...
script configuration
how it works
...
<transformation type="walkmod:commons:scripting" >
<param name="language">
groovy
</...
visitor transformations
public class HelloVisitor extends VoidVisitor<VisitorContext>{
...
@Overwrite
public void visit(Me...
why visitors?
• Visitors are developed and compiled in java.They allow the creation of
complex and efficient transformatio...
visitor configuration
how it works
<!DOCTYPE walkmod PUBLIC "-//WALKMOD//DTD" "http://www.walkmod.com/dtd/walkmod-1.0.dtd"...
writer
• writes each object allocated in a resource. i.e all java source files of a
specific folder.
• Has include/exclude...
<writer path="src/main/java" >
	 </writer>
type="walkmod:commons:eclipse-formatter"
<param name="my1stparam">my1stvalue</p...
how it works
introduction
query engine
merge engine
plugins
quick start
32
write less to do the same
query engine
MethodDeclaration method = null;
Collection members = type.getMembers();
Iterator i...
language features
• All queries have an object context and a query expression. By default, the
context is the root element...
queries from templates
Using the query object: ${query.resolve(“expr”)}.
query engine
import org.apache.log4j.Logger;
publ...
queries from visitors
Implementing QueryEngineAware or extendingVisitorSupport.
query engine
public class MyVisitor extend...
queries from scripts
accessing through a binding called query
query engine
..
for( type in node.types) {
def result = quer...
how it works
introduction
query engine
merge engine
plugins
quick start
38
walkmod merges outputs with existential sources
39
why a merge engine?
• To avoid duplicate results by transformations (i.e duplicate a method)
in existing code.
• Simplify ...
semantic merge
• Code is merged according to the meaning of its elements instead of
simply merging text.
• In semantic mer...
previous concepts
• local object is the current version of an element.
• remote object is the modified version of an elemen...
merge policies
Configurable and extensible merge policies for each object type.
merge engine
Object
merge
policy
Finds the ...
object merge policies
• append policy only writes new values for null fields. Otherwise, these
are not modified.
• overwrite...
type merge policies
• assign policy only writes the remote values. i.e replacing the list of
statements of a method for th...
how it works
introduction
query engine
merge engine
plugins
quick start
46
how to extend walkmod?
• Creating new plugins (java libraries) and deploying them into a maven
repository (public or priva...
plugin descriptor
• Plugin descriptor is a XML file with the name walkmod-xxx-plugin.xml
which follows the spring bean con...
plugin usage (I)
<!DOCTYPE walkmod SYSTEM "walkmod-1.0.dtd">
<walkmod>
<plugins>
	 	 <plugin groupId="walkmod" artifactId=...
plugin usage (II)
Beans declared in a plugin descriptor can be referenced from walkmod.xml
using the type attribute.
plugi...
commands
> walkmod install
Downloads all your plugins and their dependencies.
> walkmod apply [chain] [--offline]
Download...
plugins backend
• Walkmod embeds apache ivy to download plugins from maven
repositories.
• Custom repositories are in ${wa...
Upcoming SlideShare
Loading in …5
×

walkmod: An open source tool for coding conventions

6,237 views

Published on

Published in: Technology
  • If you have any problems with writing, feel free to ask our writers for help! The team of Paper Help HelpWriting.net is ready to help with any kind of academic writing!
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • Dating for everyone is here: ❤❤❤ http://bit.ly/39sFWPG ❤❤❤
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • Dating direct: ❶❶❶ http://bit.ly/39sFWPG ❶❶❶
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • Be the first to like this

walkmod: An open source tool for coding conventions

  1. 1. walkmod a tool to apply coding conventions 1
  2. 2. 2
  3. 3. how it works introduction query engine merge engine plugins quick start 3
  4. 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
  5. 5. examples • Naming conventions • Code formatting • Code licenses • Code documentation • Code refactoring • Apply programming practices • Architectural best practices • More.. Introduction 5
  6. 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
  7. 7. how it works introduction query engine merge engine plugins quick start 7
  8. 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. 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. 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. 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. 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
  13. 13. how it works introduction query engine merge engine plugins quick start 13
  14. 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. 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. 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. 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. 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. 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. 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
  21. 21. template transformations package ${query.resolve("node.package.name")}; public class ${query.resolve("type.name")}{ ${for ( field in query.resolve("type.fields") ){ print “public ${field.type} get ${field.name}() { return ${field.name} ; }”; }//end for } how it works getter generator using groovy templates 21
  22. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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
  32. 32. how it works introduction query engine merge engine plugins quick start 32
  33. 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. 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. 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. 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. 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
  38. 38. how it works introduction query engine merge engine plugins quick start 38
  39. 39. walkmod merges outputs with existential sources 39
  40. 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. 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. 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. 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. 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. 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
  46. 46. how it works introduction query engine merge engine plugins quick start 46
  47. 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. 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
  49. 49. plugin usage (I) <!DOCTYPE walkmod SYSTEM "walkmod-1.0.dtd"> <walkmod> <plugins> <plugin groupId="walkmod" artifactId="walkmod-commons-plugin" version="1.0"> </plugin> </plugins> <chain name="my-chain"> ... </chain> <walkmod> plugins <plugins> <plugin groupId="walkmod" artifactId="walkmod-commons-plugin" version="1.0"> </plugin> </plugins> Plugins are declared into ${project}/walkmod.xml 49
  50. 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. 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. 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

×