Continuous integration in OSGi projects using Maven (v:0.1) Sergio Blanco Diez

Transcription

1 Continuous integration in OSGi projects using Maven (v:0.1) Sergio Blanco Diez December 1, 2009

2 Contents 1 Introduction 2 2 Maven What is Maven? How does Maven work? Life cycles Maven coordinates Repositories Project Object Model The Super POM Simple POM Example Project dependencies Effective POM Build profiles Maven plugins Is Maven java-exclusive? Managing and building OSGi projects using Maven Maven plug-ins for OSGi projects Pax usage Project creation Bundle creation Libraries and third party bundles Provisioning the project Enabling integration testing Using Eclipse to edit and debug code

3 Chapter 1 Introduction Searching documentation about continuous integration in OSGi projects is quite difficult; there isn t that much of it and the few documents one may find 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 separate 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 to figure out the build order or write it explicitly in the ant build configuration file. 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 build file 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 the first 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. 2

4 Sergio Blanco 3

5 Chapter 2 Maven 2.1 What 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 used to build deployable artifacts from source code. Build engineers and project managers might 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 as Maven provides a superset of features found in a build tool. In addition to providing build capabilities, Maven can also run reports, generate a web site, and facilitate communication among members of a working team. A more formal definition of Apache Maven: Maven is a project management tool which encompasses a project object model, a set of standards, a project lifecycle, a dependency management system, and logic for executing plugin goals at defined phases in a lifecycle. When you use Maven, you describe your project using a well-defined project object model, Maven can then apply cross-cutting logic from a set of shared (or custom) plugins. Don t let the fact that Maven is a project management tool scare you away. If you were just looking for a build tool, Maven will do the job. In fact, the first few chapters of this book will deal with the most common use case: using Maven to build and distribute 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 XML file (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 or Apache ServiceMix from Subversion and build it from source, you really had to set 4

6 aside about an hour to figure out the build system for each particular project. What does the project need to build? What libraries do I need to download? Where do I put them? What goals can I execute in the build? In the best case, it took a few minutes to figure out a new project s build, and in the worst cases (like the old Servlet API implementation in the Jakarta Project), a project s build was so difficult it would take multiple hours just to get to the point where a new contributor could edit source and compile the project. These days, you check it out from source, and you run mvn install. While Maven provides an array of benefits including dependency management and reuse of common build logic through plugins, the core reason why it has succeeded is that it has defined a common interface for building software. When you see that a project like Apache ActiveMQ uses Maven, you can assume that you ll be able to check it out from source and build it with mvn install without much hassle. You know where the ignition keys goes, you know that the gas pedal is on the right-side, and the brake 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 to fill 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.2 How does Maven work? Maven as downloaded is unable to do anything beyond managing the life cycle of the project and parsing the configuration files and the POM files. 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 POM file 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 (-Djava.compiler=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 Life cycles Let s take a look at the life cycle (well, the life cycles) Maven provides[1][5][4]. 5

7 Default life cycle The 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 Description validate Validate the project is correct and all necessary information is available initialize Initialize build state, e.g. set properties or create directories generate-sources Generate any source code for inclusion in compilation process-sources Process the source code, for example to filter any values generate-resources Generate resources for inclusion in the package process-resources Copy and process the resources into the destination directory, ready for packaging compile Compile the source code of the project process-classes Post-process the generated files from compilation, for example to do bytecode enhancement on Java classes generate-test-sources Generate any test source code for inclusion in compilation process-test-sources Process the test source code, for example to filter any values generate-test-resources Create resources for testing process-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 generated files from test compilation, for example to do bytecode enhancement on Java classes. For Maven and above test Run tests using a suitable unit testing framework. These tests should not require the code be packaged or deployed prepare-package Perform any operations necessary to prepare a package before the actual packaging. This often results in an unpacked, processed version of the package. (Maven 2.1 and above) package Take the compiled code and package it in its distributable format, such as a JAR pre-integration-test Perform actions required before integration tests are executed. This may involve things such as setting up the required environment integration-test Process and deploy the package if necessary into an environment where integration tests can be run post-integration-test Perform actions required after integration tests have been executed. This may including cleaning up the environment verify Run any checks to verify the package is valid and meets quality criteria install Install the package into the local repository, for use as a dependency in other projects locally deploy Done in an integration or release environment, copies the final package to the remote repository for sharing with other developers and projects Each phase can have different plugin goals associated depending, tipically, on the type of project (packaging; EJB, JAR, Bundle,... ) 6

8 Clean life cycle The 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 pre-clean clean post-clean Description Executes processes needed prior to the actual project cleaning Remove all files generated by the previous build Executes processes needed to finalize the project cleaning Site life cycle The 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 pre-site site post-site site-deploy Description Executes processes needed prior to the actual project site generation Generates the project s site documentation Executes processes needed to finalize the site generation, and to prepare for site deployment Deploys the generated site documentation to the specified web server Maven coordinates Maven 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 Java 1.4 compiler and another compiled with the Java 6 compiler 7

9 2.2.3 Repositories Maven works with repositories, be them local or remote. When one tries to invoke a life cycle phase or a given goal for the first 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 building a 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 have all 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.3 Project Object Model According 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 a project, the sponsoring organization, and a list of developers and contributors along with the license for a project Build settings - In this section, we customize the behavior of the default Maven build. We can change the location of source and tests, we can add new plugins, we can attach plugin goals to the lifecycle, and we can customize the site generation parameters Build environment - The build environment consists of profiles that can be activated for use in different environments. For example, during development you may want to deploy to a development server, whereas in production you want to deploy to a production server. The build environment customizes the build settings for specific environments and is often supplemented by a custom settings.xml in /.m2. This settings file is discussed in Chapter 11, Build Profiles and 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 may include submodules The Super POM According to Maven: The Definitive Guide [5][4]: All Maven project POMs extend the Super POM, which defines a set of defaults shared by all projects. This Super POM is a part of the Maven installation and can be found in the maven uber.jar file in M2HOME/lib. If you look in this JAR file, you will find a file named pom xml under the org.apache.maven.project package. The Super POM defines the central repository location (which, if changed, should be modified in a custom settings.xml file), the standard set of plugins and the update policy... 8

10 2.3.2 Simple POM Example <project> <modelversion>4.0.0</modelversion> <groupid>es.deusto.morelab.project</groupid> <artifactid>subproject</artifactid> <version>1.0</version> </project> Listing 2.1: Simple pom.xml Project dependencies Project 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 dependencies are included with an application. Lets explore each scope in detail: compile: compile is the default scope; all dependencies are compile-scoped if a scope is not supplied. compile dependencies are available in all classpaths, and they are packaged provided: provided dependencies are used when you expect the JDK or a container 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 a servlet, 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, but they are not required for compilation. For example, you may need a JDBC API JAR at compile time and the JDBC driver implementation only at runtime test: test-scoped dependencies are not required during the normal operation of an application, and they are available only during test compilation and execution phases. The test scope was previously introduced in Section 4.10, Adding Testscoped Dependencies system: The system scope is similar to provided except that you have to provide an explicit path to the JAR on the local file system. This is intended to allow compilation against native objects that may be part of the system libraries. The artifact 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 systempath element. Note that this scope is not recommended (you should always try to reference dependencies in a public or custom Maven repository) The following is a fairly typical example of dependencies: <project>... <dependencies> 9

11 <dependency> <groupid>junit</groupid> <artifactid>junit</artifactid> <version>3.8.1</version> <scope>test</scope> </dependency> <dependency> <groupid>javax.servlet</groupid> <artifactid>servlet-api</artifactid> <version>2.4</version> <scope>provided</scope> </dependency> <dependency> <groupid>es.deusto.morelab.project</groupid> <artifactid>projecteventhandler</artifactid> <version>1.0</version> </dependency> </dependencies>... </project> Listing 2.2: POM dependencies Effective POM Given 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 following on the directory that contains the pom.xml you want to analyse: mvn help:effective-pom Build profiles Profiles 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 a final 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 (-Pprofile) or they may declare a condition for them to be activated using a activation element in the profile configuration. <project>... <profiles> <profile> <id></id> <activation>...</activation> <build> <defaultgoal>...</defaultgoal> <finalname>...</finalname> <resources>...</resources> <testresources>...</testresources> <plugins>...</plugins> </build> <reporting>...</reporting> 10

12 <modules>...</modules> <dependencies>...</dependencies> <dependencymanagement>...</dependencymanagement> <distributionmanagement>...</distributionmanagement> <repositories>...</repositories> <pluginrepositories>...</pluginrepositories> <properties>...</properties> </profile> </profiles> </project> Listing 2.3: POM profiles (Not all elements are mandatory) 2.4 Maven plugins There is no need to download plugins manually, but searching for plugins that do what you need is vital as usually there is a plugin for 99% of the needs of a project build. A good place to search for projects and plugins is If you can t find a plugin that does what you need, you can always develop a plugin yourself using Ant, Java or Ruby. You can find information about this in Maven: The Definitive Guide [5][4] and in the Maven documentation[2]. 2.5 Is 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]. 11

13 Bibliography [1] Maven life cycle reference [online]. URL: 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, Larry Shatzer. Maven: The Definitive Guide [online]. URL: maven-book/reference/. [5] Tim O Brien, John Casey, Brian Fox, Bruce Snyder, Jason Van Zyl, Eric Redmond, Larry Shatzer. Maven: The Definitive Guide. O Reilly, September

14 Chapter 3 Managing and building OSGi projects using Maven 3.1 Maven plug-ins for OSGi projects There 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 transformation 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.2 Pax usage This 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. 13

15 3.2.1 Project creation Whether creating a new project or importing an already existing project into Maven, the first 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 to 1.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. mvn org.ops4j:maven-pax-plugin:1.4:create-project -DgroupId=es.deusto.morelab.project - DartifactId=Project -Dversion=1.0-SNAPSHOT Listing 3.1: pax:create-project example (Using Maven) pax-create-project -g es.deusto.morelab.project -a Project -v 1.0-SNAPSHOT Listing 3.2: pax-create-project example (Using shell script) Configure default provisioning platform The 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: <?xml version="1.0" encoding="utf-8"?> <project xmlns:xsi=" xmlns=" xsi:schemalocation=" apache.org/maven-v4_0_0.xsd"> <modelversion>4.0.0</modelversion> <groupid>es.deusto.morelab.project</groupid> <artifactid>subproject</artifactid> <version>1.0-snapshot</version> <name>es.deusto.morelab.project.subproject (OSGi project)</name> <description>generated using Pax-Construct</description> <properties> <org.osgi.service.http.port>8080</org.osgi.service.http.port> <org.osgi.service.http.port.secure>8443</org.osgi.service.http.port.secure> </properties> <packaging>pom</packaging> <modules> <module>poms</module> <module>provision</module> </modules> <build> <plugins> <plugin> <groupid>org.ops4j</groupid> 14

16 <artifactid>maven-pax-plugin</artifactid> <version>1.4</version> <configuration> <provision> <param>--platform=equinox</param> </provision> </configuration> <executions> </executions> </plugin> </plugins> </build> </project> Listing 3.3: Parent project POM modified to provision using Equinox Enable automatic Eclipse project generation The project POM has a whole section commented out that enables Eclipse project creation each time mvn install is run. This setting will only create some files so Eclipse can import the project. Dependencies to libraries will depend on the M2 HOME classpath variable, which can be defined in Eclipse after importing the project. Later 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. <?xml version="1.0" encoding="utf-8"?> <project xmlns:xsi=" xmlns=" xsi:schemalocation=" apache.org/maven-v4_0_0.xsd"> <modelversion>4.0.0</modelversion> <groupid>es.deusto.morelab.project</groupid> <artifactid>subproject</artifactid> <version>1.0-snapshot</version> <name>es.deusto.morelab.project.subproject (OSGi project)</name> <description>generated using Pax-Construct</description> <properties> <org.osgi.service.http.port>8080</org.osgi.service.http.port> <org.osgi.service.http.port.secure>8443</org.osgi.service.http.port.secure> </properties> <packaging>pom</packaging> <modules> <module>poms</module> <module>provision</module> </modules> <build> <plugins> <plugin> <groupid>org.ops4j</groupid> <artifactid>maven-pax-plugin</artifactid> <version>1.4</version> <configuration> 15

17 <provision> <param>--platform=equinox</param> </provision> </configuration> <executions> <execution> <id>ide-support</id> <goals> <goal>eclipse</goal> </goals> </execution> </executions> </plugin> </plugins> </build> </project> Listing 3.4: Parent project POM modified to create Eclipse projects Change default Java compiler version for the project The Maven compiler plug-in uses Java 1.4 to 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 the 1.6 Java compiler as the default version and contains the previous modifications. <?xml version="1.0" encoding="utf-8"?> <project xmlns:xsi=" xmlns=" xsi:schemalocation=" apache.org/maven-v4_0_0.xsd"> <modelversion>4.0.0</modelversion> <groupid>es.deusto.morelab.project</groupid> <artifactid>subproject</artifactid> <version>1.0-snapshot</version> <name>es.deusto.morelab.project.subproject (OSGi project)</name> <description>generated using Pax-Construct</description> <properties> <org.osgi.service.http.port>8080</org.osgi.service.http.port> <org.osgi.service.http.port.secure>8443</org.osgi.service.http.port.secure> </properties> <packaging>pom</packaging> <modules> <module>poms</module> <module>provision</module> </modules> <build> <plugins> <plugin> <groupid>org.apache.maven.plugins</groupid> <artifactid>maven-compiler-plugin</artifactid> <configuration> 16

18 <source>1.6</source> <target>1.6</target> </configuration> </plugin> <plugin> <groupid>org.ops4j</groupid> <artifactid>maven-pax-plugin</artifactid> <version>1.4</version> <configuration> <provision> <param>--platform=equinox</param> </provision> </configuration> <executions> <execution> <id>ide-support</id> <goals> <goal>eclipse</goal> </goals> </execution> </executions> </plugin> </plugins> </build> </project> Listing 3.5: Parent project POM modified to use Java 1.6 compiler Configure testing plug-in By default, the testing plug-in (maven-surefire-plugin) puts the testing reports for each project in target/surefire-reports. Each project has it s own directory, and OSGi projects have a subproject 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 there is no way to make them iterate through subdirectories. A very easy solution is make the project leave the test results in the parent project s target/surefire-reports directory. Another interesting setting for continuous integration system is whether a test failure should stop the building process 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. <?xml version="1.0" encoding="utf-8"?> <project xmlns:xsi=" xmlns=" xsi:schemalocation=" apache.org/maven-v4_0_0.xsd"> <modelversion>4.0.0</modelversion> <groupid>es.deusto.morelab.project</groupid> <artifactid>subproject</artifactid> <version>1.0-snapshot</version> <name>es.deusto.morelab.project.subproject (OSGi project)</name> <description>generated using Pax-Construct</description> <properties> <org.osgi.service.http.port>8080</org.osgi.service.http.port> <org.osgi.service.http.port.secure>8443</org.osgi.service.http.port.secure> </properties> 17

19 <packaging>pom</packaging> <modules> <module>poms</module> <module>provision</module> </modules> <build> <plugins> <plugin> <groupid>org.apache.maven.plugins</groupid> <artifactid>maven-surefire-plugin</artifactid> <configuration> <reportformat>plain</reportformat> <reportsdirectory>../target/surefire-reports</reportsdirectory> <testfailureignore>true</testfailureignore> </configuration> </plugin> <plugin> <groupid>org.apache.maven.plugins</groupid> <artifactid>maven-compiler-plugin</artifactid> <configuration> <source>1.6</source> <target>1.6</target> </configuration> </plugin> <plugin> <groupid>org.ops4j</groupid> <artifactid>maven-pax-plugin</artifactid> <version>1.4</version> <configuration> <provision> <param>--platform=equinox</param> </provision> </configuration> <executions> <execution> <id>ide-support</id> <goals> <goal>eclipse</goal> </goals> </execution> </executions> </plugin> </plugins> </build> </project> Listing 3.6: Parent project POM with modified testing settings Other configuration parameters may be found at the surefire:test documentation[17] Bundle creation The 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 18

20 is a <module> entry in the <modules> section. Fortunately, Pax Construct also makes bundle creation easy using the Maven pax:create-bundle goal or the pax-create-bundle helper script on parent project s directory. Both add the <module> entry, creates a directory for the project with it s POM and example code. A very interesting feature is that one may indicate the JUnit version to use for testing and the plugin adds the required dependency and generates some sample testing code (unfortunately, the code is for JUnit 3.x, so it must be rewritten or copied from anywhere. Note that this may be solved with a custom archetype). org.ops4j:maven-pax-plugin:1.4:create-bundle "-Dpackage=es.deusto.morelab.project. subproject" "-DbundleName=SubProject" "-Dversion=1.0-SNAPSHOT" "-Djunit=4.7" Listing 3.7: pax:create-bundle example (Using Maven) pax-create-bundle -p es.deusto.morelab.project.subproject -n SubProject -v 1.0-SNAPSHOT -- "-Djunit=4.7" Listing 3.8: pax-create-bundle example (Using shell script) MANIFEST.MF generation Pax uses the Apache Felix Bundle Plugin to generate automatically the bundle s manifest. This plugin is already configured in a parent POM under the poms directory, so the bundle project just inherits the setting. This plugin generates a MANIFEST.MF file automatically each time the project builds using information of the POM file and the osgi.bnd file, using the information from the POM file for default values and the osgi.bnd as override settings. The osgi.bnd file is in fact a MANIFEST.MF file, so one may write the desired manifest and it will be respected. Beware, the Eclipse integration that was enabled before creates a META-INF directory with a manifest file, but changes to this file are omitted, it is just so Eclipse can detect the project is a bundle and manage the dependencies and package imports/exports Libraries and third party bundles The vast majority of bundles depend upon other bundles and libraries. A lot of those dependencies may already be in the central Maven repositories or other Maven repositories, and it pays to dedicate some time and look for those mavenized bundles and libraries. In the case of plain libraries, they have to be included as part of the final bundle and so they should be embedded or wrapped (which there are two goals and shell scripts that get the job done[10][16]). At the time of this writing, the pax-embed-jar and pax-wrap-jar scripts are not working (at least for me), so another option is add the jars to the resources of the project so they are added to the final bundle. This last solution loses the advantages of the version system, but keeps the tire going and still makes the build totally portable. Dependencies between mavenized bundles If a bundle depends upon other bundle (build time, not execution time) and this other bundle exists in some Maven repository, just adding a <dependency> entry with the usual Maven coordinates (and ensuring the Export-Package and Import-Package entries of the manifest are correct) is enough. This can also be done using the Maven goal pax:import-bundle or the helper shell script. <?xml version="1.0" encoding="utf-8"?> <project xmlns:xsi=" xmlns=" xsi:schemalocation=" apache.org/maven-v4_0_0.xsd"> 19

21 <parent> <relativepath>../poms/compiled/</relativepath> <groupid>es.deusto.morelab.project.build</groupid> <artifactid>compiled-bundle-settings</artifactid> <version>1.0-snapshot</version> </parent> <properties> <bundle.symbolicname>es.deusto.morelab.project.guicontroller</bundle.symbolicname> <bundle.namespace>es.deusto.morelab.project.subproject</bundle.namespace> </properties> <modelversion>4.0.0</modelversion> <groupid>es.deusto.morelab.proyect</groupid> <artifactid>subproject</artifactid> <version>1.0-snapshot</version> <name>${bundle.symbolicname} [${bundle.namespace}]</name> <packaging>bundle</packaging> <dependencies> <dependency> <groupid>es.deusto.morelab.project</groupid> <artifactid>subprojecta</artifactid> <version>1.0-snapshot</version> </dependency> <dependency> <groupid>es.deusto.morelab.project</groupid> <artifactid>subprojectb</artifactid> <version>1.0-snapshot</version> </dependency> <dependency> <groupid>org.eclipse</groupid> <artifactid>swt</artifactid> <version>3.3.0-v3346</version> </dependency> <dependency> <groupid>org.osgi</groupid> <artifactid>osgi_r4_core</artifactid> <optional>true</optional> </dependency> <dependency> <groupid>org.osgi</groupid> <artifactid>osgi_r4_compendium</artifactid> <optional>true</optional> </dependency> <dependency> <groupid>junit</groupid> <artifactid>junit</artifactid> <version>4.7</version> <scope>test</scope> </dependency> </dependencies> <profiles> <profile> <id>x32</id> 20

22 <activation> <os> <arch>x86</arch> </os> </activation> <dependencies> <dependency> <groupid>org.eclipse.swt.gtk.linux</groupid> <artifactid>x86</artifactid> <version>3.3.0-v3346</version> </dependency> </dependencies> </profile> <profile> <id>x64</id> <activation> <os> <arch>amd64</arch> </os> </activation> <dependencies> <dependency> <groupid>org.eclipse.swt.gtk.linux</groupid> <artifactid>x86_64</artifactid> <version>3.3.0-v3346</version> </dependency> </dependencies> </profile> </profiles> </project> Listing 3.9: Sample Bundle POM with dependencies Mavenize external bundles If the desired bundle is not found in any Maven repository, it is possible to locally mavenize it by adding the usual Maven coordinates to the bundle jar. This is problematic, as if others download the project and want to build it have to mavenize it in their machine with the exact same coordinates before building. To mavenize a bundle, the install:install-file goal may be used: mvn install:install-file -Dfile=bundle.jar -DgroupId=group -DartifactId=artifactName - Dversion=versionNumber -Dpackaging=bundle Listing 3.10: Mavenize bundle External libraries As stated before, the pax-embed-jar and pax-wrap-jar solutions would make external libraries easy to include in a bundle, retrieving them from a Maven repository on build time. Unfortunately, it didn t work at the time of this writing. Another option is copy the desired library jars to the src/main/resources so they will be packaged in the bundle jar. For the OSGi class loader to load those jars, a Bundle-ClassPath entry must be added to osgi.bnd. Whatever is in src/main/resources is copied to the root of the final bundle jar, so jars may be placed in a lib directory, for example. 21

23 Bundle-Activator: ${bundle.namespace}.internal.activator Export-Package: es.deusto.morelab.project.subproject Bundle-ClassPath: lib/sqlitejdbc-v056.jar,. Import-Package: org.osgi.framework, es.deusto.morelab.project.subprojecta, es.deusto. morelab.project.subprojectb, org.osgi.util.tracker Bundle-Name: SubProject Listing 3.11: Sample osgi.bnd Anyway, if the pax-embed-jar and pax-wrap-jar scripts do not work, the same effect may be achieved configuring the Felix Maven Bundle Plugin[6] (already configured in parent POMs, so it is just needed to override a part of it s config). This plugin enables dependency embeding via the <Embed-Dependency> tag. Configuration help may be found on the project page[6]. Embedded dependencies end up in the JAR root, so osgi.bnd should reflect that Provisioning the project First and foremost: Get used to do mvn clean and mvn install frequently. mvn clean because there are changes to the codebase that will leave garbage binaries (garbage tests is really typical). mvn install because projects get built with the dependencies that are on the local repository. If they never get updated by the newer builds, old binaries are used as dependencies. In fact, mvn clean install should be the usual way to let Maven do everything (clean, build, tests and install). Should you want to skip tests or whatever, then look into it, but do it being conscious of this. Once the project is built, it can be run using Pax tools very easily. Pax Construct provides a pax:provision goal that uses Pax Runner, and Pax Runner may be used manually. The good thing about Pax Runner is that it provides a lot of options to install bundles, being able to get them from Maven repositories, local file system, scanning directories... Running it on the parent project directory will install all referenced bundles. If specific start levels or sources are to be used, a simple configuration file gets the job done. #Libraries and system bundles scan-bundle:mvn:org.eclipse/swt/3.3.0-v3346@1 scan-bundle:mvn:org.eclipse.swt.gtk.linux/x86/3.3.0-v3346@1 scan-bundle:mvn:org.eclipse.swt.gtk.linux/x86_64/3.3.0-v3346@1 #Basic start bundles scan-bundle:mvn:es.deusto.morelab.project/subprojecta/1.0-snapshot@1@update scan-bundle:mvn:es.deusto.morelab.project/subprojectb/1.0-snapshot@2@update scan-bundle:mvn:es.deusto.morelab.project/subprojectc/1.0-snapshot@3@update scan-bundle:mvn:es.deusto.morelab.project/subprojectd/1.0-snapshot@4@update scan-bundle:mvn:es.deusto.morelab.project/subprojecte/1.0-snapshot@nostart@update Listing 3.12: Sample provision configuration file mvn pax:provision -Dplatform=equinox -Dargs=provision.conf Listing 3.13: pax:provision Maven goal usage pax-run.sh --platform=equinox scan-composite:file:provision.conf Listing 3.14: pax-run shell script usage Note that clean may be appended so the configuration file is reloaded. The provision configuration file used as example is a composite[14] configuration file that enables developers to specify various bundles sources. 22

24 3.2.5 Enabling integration testing Integration testing is done through a dedicated bundle. This bundle (or bundles) can be prepared manually, but Pax Exam provides an easy way to dynamically create a integration testing bundle by just writing the desired tests. This method is highly recommendable because it uses Pax Runner to create an execution environment for the tests to run and the provisioning can be configured in each test source code, limiting which bundles are loaded and how for each test. To use Pax Exam, another sub project must be created. It can be a bundle or a normal Java project. If it is a bundle, the bundle settings will be ignored because Pax Exam generates a bundle dynamically for each test case. No activator or manifest needed. To make it work, just add the Pax Exam dependencies[11] in the testing project POM. Then create as many JUnit 4 test cases as necessary. Each test case will be run in a separate container provisioned with the configuration specified in a method of the test case annotated The BundleContext is injected automatically in a field annotated package es.deusto.morelab.maventest.integration; import static org.junit.assert.*; import org.junit.test; import org.junit.runner.runwith; import org.osgi.framework.bundlecontext; import org.osgi.framework.bundle; import org.ops4j.pax.exam.inject; import org.ops4j.pax.exam.option; import org.ops4j.pax.exam.junit.junit4testrunner; import es.deusto.morelab.maventest.producer.exampleservice; import org.osgi.util.tracker.servicetracker; import org.ops4j.pax.exam.junit.configuration; import static org.ops4j.pax.exam.coreoptions.*; import static org.ops4j.pax.exam.container.def.paxrunneroptions.*; import static JUnit4TestRunner.class ) public class ProducerAvailableTest { /** * The value should be injected by Pax Exam. private BundleContext public Option[] configure() { return options ( /*Use only Equinox to test. More implementations may be appended and each test will be run with each*/ equinox(), /*Specify bundles to provision. Various provisioning options are available, as in the composite provisioning option of Pax Runner*/ provision ( mavenbundle().groupid( "es.deusto.morelab.maventest" ).artifactid( " simpleproducer" ).version(asinproject()) 23

25 ) ); } public void isproducerrunning() { assertnotnull( bundlecontext ); ServiceTracker tracker = new ServiceTracker(bundleContext,ExampleService.class. getname(),null); tracker.open(); ExampleService service = null; service = (ExampleService)tracker.getService(); tracker.close(); assertnotnull(service); } Listing 3.15: Integration test example Using Eclipse to edit and debug code Eclipse can still be used as a editor and debugger, but there are some things to have in mind while doing so. Maven should still be used to build the project separately. The way Eclipse builds and deploy bundles and the way Maven does it is different and separate Eclipse requires the M2 REPO classpath variable to be defined and pointed to the Maven local repository path There may be some dependencies like the pax eclipse one that are not solvable and should be ignored or deleted in Eclipse SVN commit and update must include the parent project (not included in Eclipse) and all the Maven files. Please clean the project before committing. The latest Eclipse project files are generated issuing mvn install. Configuration changes are respected and can be overridden by running the goal eclipse:clean The projects should be imported with the File->Import->Existing Projects into Workspace m2eclipse plugin is a really good option to keep doing things Maven-style, but it should be configured to use the external Maven installation instead of the embedded one 24

26 Bibliography [6] Felix Maven Bundle Plugin project homepage [online]. URL: site/apache-felix-maven-bundle-plugin-bnd.html%. [7] Pax Construct project main page [online]. URL: paxconstruct/pax+construct. [8] Pax Construct shell scripts download page [online]. URL: paxconstruct/download. [9] pax-create-project documentation [online]. URL: construct/help/create-project.html. [10] pax-embed-jar documentation [online]. URL: construct/help/embed-jar.html. [11] Pax Exam POM dependencies [online]. URL: Quick+Start. [12] Pax Exam project main page [online]. URL: Pax+Exam. [13] Pax project main page [online]. URL: [14] Pax Runner Composite Provisioning [online]. URL: display/paxrunner/composite+provisioning. [15] Pax Runner project main page [online]. URL: Runner. [16] pax-wrap-jar documentation [online]. URL: construct/help/wrap-jar.html. [17] surefire:test documentation [online]. URL: maven-surefire-plugin/test-mojo.html. [18] Tycho project overview [online]. URL: Tycho+project+overview. 25