MavenOSGi[1]

Continuous integration in OSGi projects using Maven(v:0.1)Sergio Blanco DiezDecember1,2009Contents1Introduction22Maven42.1What is Maven? (4)2.2How does Maven work? (5)2.2.1Life cycles (5)2.2.2Maven coordinates (7)2.2.3Repositories (8)2.3Project Object Model (8)2.3.1The Super POM (8)2.3.2Simple POM Example (9)2.3.3Project dependencies (9)2.3.4Effective POM (10)2.3.5Build profiles (10)2.4Maven plugins (11)2.5Is Maven java-exclusive? (11)3Managing and building OSGi projects using Maven133.1Maven plug-ins for OSGi projects (13)3.2Pax usage (13)3.2.1Project creation (14)3.2.2Bundle creation (18)3.2.3Libraries and third party bundles (19)3.2.4Provisioning the project (22)3.2.5Enabling integration testing (23)3.2.6Using Eclipse to edit and debug code (24)Chapter1IntroductionSearching documentation about continuous integration in OSGi projects is quite difficult;there isn’t that much of it and the few documents one mayfind aren’t that great.Even when asking fellow developers one usually gets another question:“Well,is it that different to how we do it with standard Java apps?”That question is not an easy one to answer,as there aren’t really that many differences but the way many developers are used to work with OSGi projects makes continuous integration complicated.Let’s take a look for example at the typical Eclipse+Equinox framework.Eclipse gives the developers a very complete building solution for OSGi projects.One can develop bundles as sepa-rate projects and Eclipse makes sure they build in the correct order,runs the Equinox container, makes debugging possible through the IDE,makes provisioning easy,makes unit testing as easy as a click on a menu.This works well for typical development,but what happens if we want to use a continuous integration system like CruiseControl on a build server?Who builds all the bundles in the correct order?How are unit and integration tests launched?Sure,one can create some scripts for each project,but how much does that cost in hours?Are those scripts going to be generic? Ant could be a very interesting option.It has existed for quite some time,it’s really easy to understand and work with it and all Java continuous integration solutions support it.Ant ensures other developers don’t need your IDE or developing facilities(except Ant itself,of course)to build and run the project out of the box.One could use ant to build and run from Eclipse,too,and get the best from both worlds.But unfortunately,it is not possible to create generic ant tasks for building interdependent bundles.Developers must develop a way tofigure out the build order or write it explicitly in the ant build configurationfile.I like my projects to be as compatible and easy to build as possible.I have to use Netbeans? Well,import,configure libraries and go on.Eclipse?The same.I just want to checkout from SVN,build and run?Ant is the way.Having a well done ant buildfile makes possible to use ant from any IDE,making the building process repeatable and ensuring anyone with just some very standard software installed can work easily with the project.To achieve that effect with OSGi projects a new challenger comes in:Maven.Given how much time I’ve using it,I can’t write the ultimate guide to Maven,but I can put in one place links to relevant documentation,comprehensive info about using Maven for OSGi development and at least help others go through thefirst steps painlessly.This document may also be completed over time with the experience of different fellow developers.The ultimate goal of this document is making continuous integration of large OSGi projects easy,therefore explaining unit and integration testing of OSGi systems,configuration of continuous integration systems,etc.I hope for this document to end up as a stable developer’s guide to all these concepts in the future, but as for now,I will be happy if this humble text just helps you in any way.Sergio Blanco(sergio.blanco@deusto.es)Chapter2Maven2.1What is Maven?Most users of Ant tend to think Maven is like a fork of Ant;the same concept in a different body. Even though Maven and Ant are both from Apache and even share some of their goals,they are not the same kind of software[5][4].For now,let’s take a look at Maven itself for what it is. Maven is defined by“Maven:The Definitive Guide”[5][4]the following way:The great majority of Maven users are going to call Maven a build tool:a tool usedto build deployable artifacts from source code.Build engineers and project managersmight refer to Maven as something more comprehensive:a project management tool.What is the difference?A build tool such as Ant is focused solely on preprocessing,compilation,packaging,testing,and distribution.A project management tool such asMaven provides a superset of features found in a build tool.In addition to providingbuild capabilities,Maven can also run reports,generate a web site,and facilitatecommunication among members of a working team.A more formal definition of Apache Maven:Maven is a project management toolwhich encompasses a project object model,a set of standards,a projectlifecycle,a dependency management system,and logic for executing plugingoals at defined phases in a lifecycle.When you use Maven,you describe yourproject using a well-defined project object model,Maven can then apply cross-cuttinglogic from a set of shared(or custom)plugins.Don’t let the fact that Maven is a”project management”tool scare you away.If youwere just looking for a build tool,Maven will do the job.In fact,thefirst few chaptersof this book will deal with the most common use case:using Maven to build anddistribute your project.The second paragraph is specially important.The project object model(POM from now on) takes a declarative approach on the project management tasks;developers define project data in a XMLfile(unsurprisingly named pom.xml)and Maven uses this project data to manage project dependencies,find projects in repositories,customize a life cycle phase according to project configuration...This declarative approach is possible because Maven already assumes a standard software life cycle that enables developers to communicate with the same ideas in mind.“Maven: The Definitive Guide”[5][4]puts it this way:Before Maven,when you wanted to check out a project like Apache ActiveMQ orApache ServiceMix from Subversion and build it from source,you really had to setaside about an hour tofigure out the build system for each particular project.Whatdoes the project need to build?What libraries do I need to download?Where do Iput them?What goals can I execute in the build?In the best case,it took a fewminutes tofigure out a new project’s build,and in the worst cases(like the old ServletAPI implementation in the Jakarta Project),a project’s build was so difficult it wouldtake multiple hours just to get to the point where a new contributor could edit sourceand compile the project.These days,you check it out from source,and you run mvninstall.While Maven provides an array of benefits including dependency management andreuse of common build logic through plugins,the core reason why it has succeededis that it has defined a common interface for building software.When you see thata project like Apache ActiveMQ uses Maven,you can assume that you’ll be able tocheck it out from source and build it with mvn install without much hassle.You knowwhere the ignition keys goes,you know that the gas pedal is on the right-side,and thebrake is on the left.This standard life cycle can be seen as a limitation,but it actually isn’t.All the phases you may expect are there,and for exceptional functionality,you can call goals(which reside in plugins)in a way very similar to ant.Another useful feature of Maven is“Convention over Configuration”.This means two things:•Sane default values are provided for everything so a developer doesn’t have tofill a lot of configuration details.Obviously,even the default can be changed on different levels and a inheritance mechanism is provided.•Maven has been designed to make everything automatically.Thanks to the POM,Maven can retrieve dependencies from standard or custom repositories as they are needed,so if everything has been laid out correctly,the developer doesn’t even have to wonder about what a project needs to be built or where he/she needs to put those dependencies.Even the plugins used by the life cycle(default ones or configured in the POM)are automatically downloaded and not included with the Maven binaries.2.2How does Maven work?Maven as downloaded is unable to do anything beyond managing the life cycle of the project and parsing the configurationfiles and the POMfiles.The real work is done by plugins,which can be associated to different life cycle phases.Each phase has already a default set of plugins(for example,the Maven compiler plugin is associated to the compile phase)and each plugin can be configured via the POMfile to execute certain goals in each phase.Plugins are automatically downloaded and updated as needed.When one invokes a life cycle phase maven runs all the previous phases up to the invoked one. One can invoke a phase executing mvn phase.It is also possible to invoke plugin goals directly executing mvn plugin:goal.In both examples parameters can be appended using the“-D”notation(piler=whatever).There are goals that are not designed to be used in life cycle phases,like the project creation goals,which mimic the plain scripting model of Ant.2.2.1Life cyclesLet’s take a look at the life cycle(well,the life cycle s)Maven provides[1][5][4].Default life cycleThe default life cycle is the usual“build,test,package and deploy”process,but with additional steps like code generation and some validations.The following table contains all it’s phases with a brief explanation.Phase Descriptionvalidate Validate the project is correct and all necessary information isavailableinitialize Initialize build state,e.g.set properties or create directories generate-sources Generate any source code for inclusion in compilationprocess-sources Process the source code,for example tofilter any values generate-resources Generate resources for inclusion in the packageprocess-resources Copy and process the resources into the destination directory,ready for packagingcompile Compile the source code of the projectprocess-classes Post-process the generatedfiles from compilation,for example todo bytecode enhancement on Java classesgenerate-test-sources Generate any test source code for inclusion in compilation process-test-sources Process the test source code,for example tofilter any values generate-test-resources Create resources for testingprocess-test-resources Copy and process the resources into the test destination directory test-compile Compile the test source code into the test destination directory process-test-classes Post-process the generatedfiles from test compilation,for exampleto do bytecode enhancement on Java classes.For Maven2.0.5andabovetest Run tests using a suitable unit testing framework.These testsshould not require the code be packaged or deployedprepare-package Perform any operations necessary to prepare a package before theactual packaging.This often results in an unpacked,processedversion of the package.(Maven2.1and above)package Take the compiled code and package it in its distributable format,such as a JARpre-integration-test Perform actions required before integration tests are executed.This may involve things such as setting up the required environ-mentintegration-test Process and deploy the package if necessary into an environmentwhere integration tests can be runpost-integration-test Perform actions required after integration tests have been exe-cuted.This may including cleaning up the environmentverify Run any checks to verify the package is valid and meets qualitycriteriainstall Install the package into the local repository,for use as a depen-dency in other projects locallydeploy Done in an integration or release environment,copies thefinalpackage to the remote repository for sharing with other developersand projectsEach phase can have different plugin goals associated depending,tipically,on the type of project (packaging;EJB,JAR,Bundle,...)Clean life cycleThe clean life cycle is about deleting the build results of a project,making possible pre-clean and post-clean hooks.The following tables contains all it’s phases with a brief explanation.Phase Descriptionpre-clean Executes processes needed prior to the actual project cleaning clean Remove allfiles generated by the previous buildpost-clean Executes processes needed tofinalize the project cleaningSite life cycleThe site life cycle is about generating a documentation and reports site of the project or set of projects.The following tables contains all it’s phases with a brief explanation.Phase Descriptionpre-site Executes processes needed prior to the actual project site genera-tionsite Generates the project’s site documentationpost-site Executes processes needed tofinalize the site generation,and toprepare for site deploymentsite-deploy Deploys the generated site documentation to the specified webserver2.2.2Maven coordinatesMaven is based on the core concepts previously explained,but there is another important fact to understand when using Maven.Maven uses project repositories,be them local or remote.Those repositories contain projects with their POMs,so it seems evident Maven should be able to manage those projects and look up for them somehow.For doing so,some coordinates are needed to make each project distinct.Those coordinates are:•Group ID:Organization or developer group ID,beginning with the reverse domain name of the organization by convention.It is mandatory.Example:org.eclipse•Artifact ID:A unique identifier under the group ID that represents a single project •Version:A specific release of the project•Packaging:Type of project.Example:jar,war,bundle.Different plugins are used based on the packaging.•Classifier:Usually this coordinate is not used.You would use a classifier if you were releasing the same code but needed to produce two separate artifacts for technical reasons.For example,if you wanted to build two separate artifacts of a JAR,one compiled with the Java1.4compiler and another compiled with the Java6compiler2.2.3RepositoriesMaven works with repositories,be them local or remote.When one tries to invoke a life cycle phaseor a given goal for thefirst time,Maven looks for the associated plugins in the repositories.A plugin can specify the repository in which it can be found,but it isn’t mandatory.When buildinga project with Maven,the resulting package is deployed on a local repository so othe projects can reference it and use it.There are serious advantages to using the central repositories or complete third party repositories,as they both usually contain a lot of versions for each project and haveall project dependencies sorted out,making transitive dependencies resolution a reality.Anyway,one can import jars to Maven via the install plugin:mvn install:install-file-Dfile=path/file.jar-DgroupId=gid-DartifactId=aid-Dversion=v -Dpackaging=pck-DgeneratePom=true.This will create a project in the local repository with the jar and a simple pom with the basic coordinates.There won’t be any dependencies involved in the process,so they may be added manually after this process.2.3Project Object ModelAccording to“Maven:The Definitive Guide”[5][4]:The POM contains four categories of description and configuration:•General project information-This includes a projects name,the URL for aproject,the sponsoring organization,and a list of developers and contributorsalong with the license for a project•Build settings-In this section,we customize the behavior of the default Mavenbuild.We can change the location of source and tests,we can add new plugins,wecan attach plugin goals to the lifecycle,and we can customize the site generationparameters•Build environment-The build environment consists of profiles that can be ac-tivated for use in different environments.For example,during development youmay want to deploy to a development server,whereas in production you wantto deploy to a production server.The build environment customizes the buildsettings for specific environments and is often supplemented by a custom set-tings.xml in/.m2.This settingsfile is discussed in Chapter11,Build Profilesand in the section Section A.2,Settings Details•POM relationships-A project rarely stands alone;it depends on other projects,inherits POM settings from parent projects,defines its own coordinates,and mayinclude submodules2.3.1The Super POMAccording to“Maven:The Definitive Guide”[5][4]:All Maven project POMs extend the Super POM,which defines a set of defaults sharedby all projects.This Super POM is a part of the Maven installation and can be foundin the maven-2.2.1-uber.jarfile in M2HOME/lib.If you look in this JARfile,you willfind afile named pom-4.0.0.xml under the org.apache.maven.project package.The Super POM defines the central repository location(which,if changed,should be modified ina custom settings.xmlfile),the standard set of plugins and the update policy...2.3.2Simple POM ExampleListing2.1:Simple pom.xml2.3.3Project dependenciesProject POMs contains the project’s direct dependencies.Maven automatically adds on build time the transitive dependencies provided the direct dependencies’POMs have them listed and so on. That makes using Maven repositories a great advantage,as all the projects available have all their dependencies sorted out.Dependencies have a scope that dictates which dependencies are available in which moment of the build life cycle.According to“Maven:The Definitive Guide”[5][4]: Scope controls which dependencies are available in which classpath,and which depen-dencies are included with an application.Lets explore each scope in detail:•compile:compile is the default scope;all dependencies are compile-scoped if ascope is not pile dependencies are available in all classpaths,andthey are packaged•provided:provided dependencies are used when you expect the JDK or a con-tainer to provide them.For example,if you were developing a web application,you would need the Servlet API available on the compile classpath to compile aservlet,but you wouldnt want to include the Servlet API in the packaged WAR;the Servlet API JAR is supplied by your application server or servlet container.provided dependencies are available on the compilation classpath(not runtime).They are not transitive,nor are they packaged•runtime:runtime dependencies are required to execute and test the system,butthey are not required for compilation.For example,you may need a JDBC APIJAR at compile time and the JDBC driver implementation only at runtime•test:test-scoped dependencies are not required during the normal operation ofan application,and they are available only during test compilation and executionphases.The test scope was previously introduced in Section4.10,Adding Test-scoped Dependencies•system:The system scope is similar to provided except that you have to providean explicit path to the JAR on the localfile system.This is intended to allowcompilation against native objects that may be part of the system libraries.Theartifact is assumed to always be available and is not looked up in a repository.If you declare the scope to be system,you must also provide the systemPathelement.Note that this scope is not recommended(you should always try toreference dependencies in a public or custom Maven repository)The following is a fairly typical example of dependencies:Listing2.2:POM dependencies2.3.4Effective POMGiven the POM inheritance system it can be quite complited sometimes to track down the project configuration for a given module.Fortunately,the Help plugin has a goal called“effective-pom”that outputs the resulting POM used at build-time.To run the effective-pom goal,run the follow-ing on the directory that contains the pom.xml you want to analyse:mvn help:effective-pom.2.3.5Build profilesProfiles override a POM settings when activated.They are usually listed at the end of a project’s POM and enable build portability between systems.For example,one can deploy the application to different places or in different ways depending on if it is a development version or afinal version. Tests may be run differently on a developer profile than on a continuous integration server profile. Profiles may be activated when invoking life cycle phases with a parameter(-P profile)or they may declare a condition for them to be activated using a“¡activation¿”element in the profile configuration.Listing2.3:POM profiles(Not all elements are mandatory)2.4Maven pluginsThere is no need to download plugins manually,but searching for plugins that do what you need is vital as usually there is a plugin for99%of the needs of a project build.A good place to search for projects and plugins is [3].If you can’tfind a plugin that does what you need,you can always develop a plugin yourself using Ant,Java or Ruby.You canfind information about this in“Maven:The Definitive Guide”[5][4]and in the Maven documentation[2].2.5Is Maven java-exclusive?Maven seems somewhat oriented to managing java projects,but it is possible to create custom life cycles and custom packagings,enabling the use of plugins designed to manage other type of projects naturally.For more information on those procedures,read the chapters that explain them in“Maven:The Definitive Guide”[5][4].Bibliography[1]Maven life cycle reference[online].URL:/guides/introduction/introduction-to-the-lifecy%cle.html#Lifecycle_Reference.[2]Maven official documentation[online].URL:/.[3]Maven plugin search[online].URL:.[4]Tim O’Brien,John Casey,Brian Fox,Bruce Snyder,Jason Van Zyl,Eric Redmond,LarryShatzer.Maven:The Definitive Guide[online].URL:/books/ maven-book/reference/.[5]Tim O’Brien,John Casey,Brian Fox,Bruce Snyder,Jason Van Zyl,Eric Redmond,LarryShatzer.Maven:The Definitive Guide.O’Reilly,September2009.Chapter3Managing and building OSGi projects using Maven3.1Maven plug-ins for OSGi projectsThere are not many options to ease Maven usage when managing and building OSGi projects. One option when looking for Eclipse integration(a good idea when working with Equinox)is Tycho[18].Tycho enables some sort of dual management solution enabling automatic transforma-tion of Eclipse projects to Maven projects and Maven projects to Eclipse projects.The problem with Tycho is that it is on a early stage of development and so it isn’t feature complete yet.The option that will be explained throughout this document is OPS4J Pax projects[13].Pax is a series of projects to ease development,testing and deployment of OSGi projects,even enabling the use of many implementations of OSGi(Felix,Equinox,Knopplerfish,Concierge)easily.This document will explain three of it’s projects:•Pax Construct[7]:Pax Construct is a Maven plug-in that eases the creation and management of OSGi projects.Some shell scripts are available as a separate download[8]that makes the process even easier.•Pax Runner[15]:Pax Runner is a tool that enables easy provisioning of OSGi bundles on top of any of the most used OSGi implementations.Pax Construct’s pax:provision goal uses Pax Runner to create an execution environment for the project.Pax runner is automatically downloaded by Maven if the pax:provision goal is used,but can be downloaded separately so the even easier pax-run shell script may be used.•Pax Exam[12]:Pax Exam is a tool that enables easy integration testing of OSGi projects.3.2Pax usageThis section will review the management process of a OSGi project using Maven and Pax.It will propose a wokflow and explain different options related to each step of the process.3.2.1Project creationWhether creating a new project or“importing”an already existing project into Maven,thefirst step is creating a multimodule Maven project with the adequate structure and dependencies. Fortunately,Pax Construct has a Maven goal to ease this task:pax:create-project.The official Pax documentation assumes developers use the helper shell scripts,so the script to use would be pax-create-project.Two parameters are mandatory,be them Maven project group ID and artifact ID.Version defaults to1.0-SNAPSHOT,but may be changed with the proper parameter.There are other possible parameters[9].This goal creates a new directory with the artifact ID as name and the proper directory structure to manage the project.Listing3.1:pax:create-project example(Using Maven)Listing3.2:pax-create-project example(Using shell script)Configure default provisioning platformThe project POM already comes with some configuration regarding the pax plug-in.By default, the OSGi implementation it will attempt to use is Apache Felix.To change this configuration, just put the desired OSGi implementation where“felix”stands in the POM.For example,in order to use Equinox,the POM would be modified to the following:Listing3.3:Parent project POM modified to provision using EquinoxEnable automatic Eclipse project generationThe project POM has a whole section commented out that enables Eclipse project creation each time mvn install is run.This setting will only create somefiles so Eclipse can import the project. Dependencies to libraries will depend on the M2HOME classpath variable,which can be defined in Eclipse after importing the ter on there is a whole section about Eclipse integration, but for it to work,this POM section must be uncommented.The following is an example with the Eclipse configuration uncommented and the previous modifications.Listing3.4:Parent project POM modified to create Eclipse projectsChange default Java compiler version for the projectThe Maven compiler plug-in uses Java1.4to compile sources by default,which is problematic when using annotations or new Java features.This can be easily changed modifying the project POM.The following POM sets the1.6Java compiler as the default version and contains the previous modifications.Listing3.5:Parent project POM modified to use Java1.6compilerConfigure testing plug-inBy default,the testing plug-in(maven-surefire-plugin)puts the testing reports for each project intarget/surefire-reports.Each project has it’s own directory,and OSGi projects have a subpro-ject for each bundle.Then each bundle will have it’s testing results in bundledir/target/surefire-reports. This can be quite problematic for continuous integration systems like CruiseControl,because thereis no way to make them iterate through subdirectories.A very easy solution is make the projectleave the test results in the parent project’s target/surefire-reports directory.Another inter-esting setting for continuous integration system is whether a test failure should stop the buildingprocess or not(by default it does stop it).The following example sets the reports directory as explained and makes the build system ignore test failures.Listing3.6:Parent project POM with modified testing settingsOther configuration parameters may be found at the surefire:test documentation[17]3.2.2Bundle creationThe parent project just created serves as a multimodule project,each module being another project that contains a bundle.The only changes done to the parent project POM with each new bundle。