docs/developer-guide/odl-parent-developer-guide.rst

   1 ODL Parent Developer Guide
   2 ==========================
   3
   4 Parent POMs
   5 -----------
   6
   7 Overview
   8 ~~~~~~~~
   9
  10 The ODL Parent component for OpenDaylight provides a number of Maven
  11 parent POMs which allow Maven projects to be easily integrated in the
  12 OpenDaylight ecosystem. Technically, the aim of projects in OpenDaylight
  13 is to produce Karaf features, and these parent projects provide common
  14 support for the different types of projects involved.
  15
  16 | These parent projects are:
  17
  18 -  ``odlparent-lite`` — the basic parent POM for Maven modules which
  19    don’t produce artifacts (*e.g.* aggregator POMs)
  20
  21 -  ``odlparent`` — the common parent POM for Maven modules containing
  22    Java code
  23
  24 -  ``bundle-parent`` — the parent POM for Maven modules producing OSGi
  25    bundles
  26
  27 -  ``features-parent`` — the parent POM for Maven modules producing
  28    Karaf features
  29
  30 odlparent-lite
  31 ~~~~~~~~~~~~~~
  32
  33 | This is the base parent for all OpenDaylight Maven projects and
  34   modules. It provides the following, notably to allow publishing
  35   artifacts to Maven Central:
  36
  37 -  license information;
  38
  39 -  organization information;
  40
  41 -  issue management information (a link to our Bugzilla);
  42
  43 -  continuous integration information (a link to our Jenkins setup);
  44
  45 -  default Maven plugins (``maven-clean-plugin``,
  46    ``maven-deploy-plugin``, ``maven-install-plugin``,
  47    ``maven-javadoc-plugin`` with HelpMojo support,
  48    ``maven-project-info-reports-plugin``, ``maven-site-plugin`` with
  49    Asciidoc support, ``jdepend-maven-plugin``);
  50
  51 -  distribution management information.
  52
  53 It also defines two profiles which help during development:
  54
  55 -  ``q`` (``-Pq``), the quick profile, which disables tests, code
  56    coverage, Javadoc generation, code analysis, etc. — anything which
  57    isn’t necessary to build the bundles and features (see `this blog
  58    post <http://blog2.vorburger.ch/2016/06/improve-maven-build-speed-with-q.html>`__
  59    for details);
  60
  61 -  ``addInstallRepositoryPath``
  62    (``-DaddInstallRepositoryPath=…/karaf/system``) which can be used to
  63    drop a bundle in the appropriate Karaf location, to enable
  64    hot-reloading of bundles during development (see `this blog
  65    post <http://blog2.vorburger.ch/2016/06/maven-install-into-additional.html>`__
  66    for details).
  67
  68 For modules which don’t produce any useful artifacts (*e.g.* aggregator
  69 POMs), you should add the following to avoid processing artifacts:
  70
  71 ::
  72
  73     <build>
  74         <plugins>
  75             <plugin>
  76                 <groupId>org.apache.maven.plugins</groupId>
  77                 <artifactId>maven-deploy-plugin</artifactId>
  78                 <configuration>
  79                     <skip>true</skip>
  80                 </configuration>
  81             </plugin>
  82             <plugin>
  83                 <groupId>org.apache.maven.plugins</groupId>
  84                 <artifactId>maven-install-plugin</artifactId>
  85                 <configuration>
  86                     <skip>true</skip>
  87                 </configuration>
  88             </plugin>
  89         </plugins>
  90     </build>
  91
  92 odlparent
  93 ~~~~~~~~~
  94
  95 This inherits from ``odlparent-lite`` and mainly provides dependency and
  96 plugin management for OpenDaylight projects.
  97
  98 | If you use any of the following libraries, you should rely on
  99   ``odlparent`` to provide the appropriate versions:
 100
 101 -  Akka (and Scala)
 102
 103 -  | Apache Commons:
 104
 105    -  ``commons-codec``
 106
 107    -  ``commons-fileupload``
 108
 109    -  ``commons-io``
 110
 111    -  ``commons-lang``
 112
 113    -  ``commons-lang3``
 114
 115    -  ``commons-net``
 116
 117 -  Apache Shiro
 118
 119 -  Guava
 120
 121 -  JAX-RS with Jersey
 122
 123 -  | JSON processing:
 124
 125    -  GSON
 126
 127    -  Jackson
 128
 129 -  | Logging:
 130
 131    -  Logback
 132
 133    -  SLF4J
 134
 135 -  Netty
 136
 137 -  | OSGi:
 138
 139    -  Apache Felix
 140
 141    -  core OSGi dependencies (``core``, ``compendium``\ …)
 142
 143 -  | Testing:
 144
 145    -  Hamcrest
 146
 147    -  JSON assert
 148
 149    -  JUnit
 150
 151    -  Mockito
 152
 153    -  Pax Exam
 154
 155    -  PowerMock
 156
 157 -  | XML/XSL:
 158
 159    -  Xerces
 160
 161    -  XML APIs
 162
 163 .. note::
 164
 165     This list isn’t exhaustive. It’s also not cast in stone; if you’d
 166     like to add a new dependency (or migrate a dependency), please
 167     contact `the mailing
 168     list <https://lists.opendaylight.org/mailman/listinfo/odlparent-dev>`__.
 169
 170 ``odlparent`` also enforces some Checkstyle verification rules. In
 171 particular, it enforces the common license header used in all
 172 OpenDaylight code:
 173
 174 ::
 175
 176     /*
 177      * Copyright © ${year} ${holder} and others.  All rights reserved.
 178      *
 179      * This program and the accompanying materials are made available under the
 180      * terms of the Eclipse Public License v1.0 which accompanies this distribution,
 181      * and is available at http://www.eclipse.org/legal/epl-v10.html
 182      */
 183
 184 where “\ ``${year}``\ ” is initially the first year of publication, then
 185 (after a year has passed) the first and latest years of publication,
 186 separated by commas (*e.g.* “2014, 2016”), and “\ ``${holder}``\ ” is
 187 the initial copyright holder (typically, the first author’s employer).
 188 “All rights reserved” is optional.
 189
 190 If you need to disable this license check, *e.g.* for files imported
 191 under another license (EPL-compatible of course), you can override the
 192 ``maven-checkstyle-plugin`` configuration. ``features-test`` does this
 193 for its ``CustomBundleUrlStreamHandlerFactory`` class, which is
 194 ASL-licensed:
 195
 196 ::
 197
 198     <plugin>
 199         <artifactId>maven-checkstyle-plugin</artifactId>
 200         <executions>
 201             <execution>
 202                 <id>check-license</id>
 203                 <goals>
 204                     <goal>check</goal>
 205                 </goals>
 206                 <phase>process-sources</phase>
 207                 <configuration>
 208                     <configLocation>check-license.xml</configLocation>
 209                     <headerLocation>EPL-LICENSE.regexp.txt</headerLocation>
 210                     <includeResources>false</includeResources>
 211                     <includeTestResources>false</includeTestResources>
 212                     <sourceDirectory>${project.build.sourceDirectory}</sourceDirectory>
 213                     <excludes>
 214                         <!-- Skip Apache Licensed files -->
 215                         org/opendaylight/odlparent/featuretest/CustomBundleUrlStreamHandlerFactory.java
 216                     </excludes>
 217                     <failsOnError>false</failsOnError>
 218                     <consoleOutput>true</consoleOutput>
 219                 </configuration>
 220             </execution>
 221         </executions>
 222     </plugin>
 223
 224 bundle-parent
 225 ~~~~~~~~~~~~~
 226
 227 | This inherits from ``odlparent`` and enables functionality useful for
 228   OSGi bundles:
 229
 230 -  ``maven-javadoc-plugin`` is activated, to build the Javadoc JAR;
 231
 232 -  ``maven-source-plugin`` is activated, to build the source JAR;
 233
 234 -  ``maven-bundle-plugin`` is activated (including extensions), to build
 235    OSGi bundles (using the “bundle” packaging).
 236
 237 In addition to this, JUnit is included as a default dependency in “test”
 238 scope.
 239
 240 features-parent
 241 ~~~~~~~~~~~~~~~
 242
 243 | This inherits from ``odlparent`` and enables functionality useful for
 244   Karaf features:
 245
 246 -  ``karaf-maven-plugin`` is activated, to build Karaf features — but
 247    for OpenDaylight, projects need to use “jar” packaging (**not**
 248    “kar”);
 249
 250 -  ``features.xml`` files are processed from templates stored in
 251    ``src/main/features/features.xml``;
 252
 253 -  Karaf features are tested after build to ensure they can be activated
 254    in a Karaf container.
 255
 256 The ``features.xml`` processing allows versions to be ommitted from
 257 certain feature dependencies, and replaced with “\ ``{{version}}``\ ”.
 258 For example:
 259
 260 ::
 261
 262     <features name="odl-mdsal-${project.version}" xmlns="http://karaf.apache.org/xmlns/features/v1.2.0"
 263        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 264        xsi:schemaLocation="http://karaf.apache.org/xmlns/features/v1.2.0 http://karaf.apache.org/xmlns/features/v1.2.0">
 265
 266         <repository>mvn:org.opendaylight.odlparent/features-odlparent/{{VERSION}}/xml/features</repository>
 267
 268         [...]
 269         <feature name='odl-mdsal-broker-local' version='${project.version}' description="OpenDaylight :: MDSAL :: Broker">
 270             <feature version='${yangtools.version}'>odl-yangtools-common</feature>
 271             <feature version='${mdsal.version}'>odl-mdsal-binding-dom-adapter</feature>
 272             <feature version='${mdsal.model.version}'>odl-mdsal-models</feature>
 273             <feature version='${project.version}'>odl-mdsal-common</feature>
 274             <feature version='${config.version}'>odl-config-startup</feature>
 275             <feature version='${config.version}'>odl-config-netty</feature>
 276             <feature version='[3.3.0,4.0.0)'>odl-lmax</feature>
 277             [...]
 278             <bundle>mvn:org.opendaylight.controller/sal-dom-broker-config/{{VERSION}}</bundle>
 279             <bundle start-level="40">mvn:org.opendaylight.controller/blueprint/{{VERSION}}</bundle>
 280             <configfile finalname="${config.configfile.directory}/${config.mdsal.configfile}">mvn:org.opendaylight.controller/md-sal-config/{{VERSION}}/xml/config</configfile>
 281         </feature>
 282
 283 As illustrated, versions can be ommitted in this way for repository
 284 dependencies, bundle dependencies and configuration files. They must be
 285 specified traditionally (either hard-coded, or using Maven properties)
 286 for feature dependencies.
 287
 288 Features
 289 --------
 290
 291 The ODL Parent component for OpenDaylight provides a number of Karaf
 292 features which can be used by other Karaf features to use certain
 293 third-party upstream dependencies.
 294
 295 | These features are:
 296
 297 -  | Akka features (in the ``features-akka`` repository):
 298
 299    -  ``odl-akka-all`` — all Akka bundles;
 300
 301    -  ``odl-akka-scala`` — Scala runtime for OpenDaylight;
 302
 303    -  ``odl-akka-system`` — Akka actor framework bundles;
 304
 305    -  ``odl-akka-clustering`` — Akka clustering bundles and
 306       dependencies;
 307
 308    -  ``odl-akka-leveldb`` — LevelDB;
 309
 310    -  ``odl-akka-persistence`` — Akka persistence;
 311
 312 -  general third-party features (in the ``features-odlparent``
 313    repository):
 314
 315    -  ``odl-netty`` — all Netty bundles;
 316
 317    -  ``odl-guava`` — Guava;
 318
 319    -  ``odl-lmax`` — LMAX Disruptor.
 320
 321 To use these, you need to declare a dependency on the appropriate
 322 repository in your ``features.xml`` file:
 323
 324 ::
 325
 326     <repository>mvn:org.opendaylight.odlparent/features-odlparent/{{VERSION}}/xml/features</repository>
 327
 328 and then include the feature, *e.g.*:
 329
 330 ::
 331
 332     <feature name='odl-mdsal-broker-local' version='${project.version}' description="OpenDaylight :: MDSAL :: Broker">
 333         [...]
 334         <feature version='[3.3.0,4.0.0)'>odl-lmax</feature>
 335         [...]
 336     </feature>
 337
 338 You also need to depend on the features repository in your POM:
 339
 340 ::
 341
 342     <dependency>
 343         <groupId>org.opendaylight.odlparent</groupId>
 344         <artifactId>features-odlparent</artifactId>
 345         <classifier>features</classifier>
 346         <type>xml</type>
 347     </dependency>
 348
 349 assuming the appropriate dependency management:
 350
 351 ::
 352
 353     <dependencyManagement>
 354         <dependencies>
 355             <dependency>
 356                 <groupId>org.opendaylight.odlparent</groupId>
 357                 <artifactId>odlparent-artifacts</artifactId>
 358                 <version>1.7.0-SNAPSHOT</version>
 359                 <scope>import</scope>
 360                 <type>pom</type>
 361             </dependency>
 362         </dependencies>
 363     </dependencyManagement>
 364
 365 (the version number there is appropriate for Boron). For the time being
 366 you also need to depend separately on the individual JARs as
 367 compile-time dependencies to build your dependent code; the relevant
 368 dependencies are managed in ``odlparent``'s dependency management.
 369
 370 | The suggested version ranges are as follows:
 371
 372 -  ``odl-netty``: ``[4.0.37,4.1.0)`` or ``[4.0.37,5.0.0)``;
 373
 374 -  ``odl-guava``: ``[18,19)`` (if your code is ready for it, ``[19,20)``
 375    is also available, but the current default version of Guava in
 376    OpenDaylight is 18);
 377
 378 -  ``odl-lmax``: ``[3.3.4,4.0.0)``
 379