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