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

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