+.. _odl-parent-developer-guide:
+
ODL Parent Developer Guide
==========================
is to produce Karaf features, and these parent projects provide common
support for the different types of projects involved.
-| These parent projects are:
+These parent projects are:
- ``odlparent-lite`` — the basic parent POM for Maven modules which
don’t produce artifacts (*e.g.* aggregator POMs)
- ``bundle-parent`` — the parent POM for Maven modules producing OSGi
bundles
-- ``features-parent`` — the parent POM for Maven modules producing
- Karaf features
+The following parent projects are deprecated, but still used in Carbon:
+
+- ``feature-parent`` — the parent POM for Maven modules producing
+ Karaf 3 feature repositories
+
+- ``karaf-parent`` — the parent POM for Maven modules producing Karaf 3
+ distributions
+
+The following parent projects are new in Carbon, for Karaf 4 support (which
+won’t be complete until Nitrogen):
+
+- ``single-feature-parent`` — the parent POM for Maven modules producing
+ a single Karaf 4 feature
+
+- ``feature-repo-parent`` — the parent POM for Maven modules producing
+ Karaf 4 feature repositories
+
+- ``karaf4-parent`` — the parent POM for Maven modules producing Karaf 4
+ distributions
odlparent-lite
~~~~~~~~~~~~~~
-| This is the base parent for all OpenDaylight Maven projects and
- modules. It provides the following, notably to allow publishing
- artifacts to Maven Central:
+This is the base parent for all OpenDaylight Maven projects and
+modules. It provides the following, notably to allow publishing
+artifacts to Maven Central:
- license information;
This inherits from ``odlparent-lite`` and mainly provides dependency and
plugin management for OpenDaylight projects.
-| If you use any of the following libraries, you should rely on
- ``odlparent`` to provide the appropriate versions:
+If you use any of the following libraries, you should rely on
+``odlparent`` to provide the appropriate versions:
- Akka (and Scala)
-- | Apache Commons:
+- Apache Commons:
- ``commons-codec``
- JAX-RS with Jersey
-- | JSON processing:
+- JSON processing:
- GSON
- Jackson
-- | Logging:
+- Logging:
- Logback
- Netty
-- | OSGi:
+- OSGi:
- Apache Felix
- core OSGi dependencies (``core``, ``compendium``\ …)
-- | Testing:
+- Testing:
- Hamcrest
- PowerMock
-- | XML/XSL:
+- XML/XSL:
- Xerces
bundle-parent
~~~~~~~~~~~~~
-| This inherits from ``odlparent`` and enables functionality useful for
- OSGi bundles:
+This inherits from ``odlparent`` and enables functionality useful for
+OSGi bundles:
- ``maven-javadoc-plugin`` is activated, to build the Javadoc JAR;
features-parent
~~~~~~~~~~~~~~~
-| This inherits from ``odlparent`` and enables functionality useful for
- Karaf features:
+This inherits from ``odlparent`` and enables functionality useful for
+Karaf features:
- ``karaf-maven-plugin`` is activated, to build Karaf features — but
for OpenDaylight, projects need to use “jar” packaging (**not**
- “kar”);
+ “feature” or “kar”);
- ``features.xml`` files are processed from templates stored in
``src/main/features/features.xml``;
specified traditionally (either hard-coded, or using Maven properties)
for feature dependencies.
-Features
---------
+karaf-parent
+~~~~~~~~~~~~
+
+This allows building a Karaf 3 distribution, typically for local testing
+purposes. Any runtime-scoped feature dependencies will be included in the
+distribution, and the ``karaf.localFeature`` property can be used to
+specify the boot feature (in addition to ``standard``).
+
+single-feature-parent
+~~~~~~~~~~~~~~~~~~~~~
+
+This inherits from ``odlparent`` and enables functionality useful for
+Karaf 4 features:
+
+- ``karaf-maven-plugin`` is activated, to build Karaf features, typically
+ with “feature” packaging (“kar” is also supported);
+
+- ``feature.xml`` files are generated based on the compile-scope dependencies
+ defined in the POM, optionally initialised from a stub in
+ ``src/main/feature/feature.xml``.
+
+- Karaf features are tested after build to ensure they can be activated
+ in a Karaf container.
+
+The ``feature.xml`` processing adds transitive dependencies by default, which
+allows features to be defined using only the most significant dependencies
+(those that define the feature); other requirements are determined
+automatically as long as they exist as Maven dependencies.
+
+“configfiles” need to be defined both as Maven dependencies (with the
+appropriate type and classifier) and as ``<configfile>`` elements in the
+``feature.xml`` stub.
+
+Other features which a feature depends on need to be defined as Maven
+dependencies with type “xml” and classifier “features” (note the plural here).
+
+feature-repo-parent
+~~~~~~~~~~~~~~~~~~~
+
+This inherits from ``odlparent`` and enables functionality useful for
+Karaf 4 feature repositories. It follows the same principles as
+``single-feature-parent``, but is designed specifically for repositories
+and should be used only for this type of artifacts.
+
+It builds a feature repository referencing all the (feature) dependencies
+listed in the POM.
+
+karaf4-parent
+~~~~~~~~~~~~~
-The ODL Parent component for OpenDaylight provides a number of Karaf
-features which can be used by other Karaf features to use certain
+This allows building a Karaf 4 distribution, typically for local testing
+purposes. Any runtime-scoped feature dependencies will be included in the
+distribution, and the ``karaf.localFeature`` property can be used to
+specify the boot feature (in addition to ``standard``).
+
+Features (for Karaf 3)
+----------------------
+
+The ODL Parent component for OpenDaylight provides a number of Karaf 3
+features which can be used by other Karaf 3 features to use certain
third-party upstream dependencies.
-| These features are:
+These features are:
-- | Akka features (in the ``features-akka`` repository):
+- Akka features (in the ``features-akka`` repository):
- ``odl-akka-all`` — all Akka bundles;
- - ``odl-akka-scala`` — Scala runtime for OpenDaylight;
+ - ``odl-akka-scala-2.11`` — Scala runtime for OpenDaylight;
- - ``odl-akka-system`` — Akka actor framework bundles;
+ - ``odl-akka-system-2.4`` — Akka actor framework bundles;
- - ``odl-akka-clustering`` — Akka clustering bundles and
+ - ``odl-akka-clustering-2.4`` — Akka clustering bundles and
dependencies;
- - ``odl-akka-leveldb`` — LevelDB;
+ - ``odl-akka-leveldb-0.7`` — LevelDB;
- - ``odl-akka-persistence`` — Akka persistence;
+ - ``odl-akka-persistence-2.4`` — Akka persistence;
- general third-party features (in the ``features-odlparent``
repository):
- - ``odl-netty`` — all Netty bundles;
+ - ``odl-netty-4`` — all Netty bundles;
+
+ - ``odl-guava-18`` — Guava 18;
+
+ - ``odl-guava-21`` — Guava 21 (not indended for use in Carbon);
- - ``odl-guava`` — Guava;
+ - ``odl-lmax-3`` — LMAX Disruptor;
- - ``odl-lmax`` — LMAX Disruptor.
+ - ``odl-triemap-0.2`` — Concurrent Trie HashMap.
To use these, you need to declare a dependency on the appropriate
repository in your ``features.xml`` file:
<dependency>
<groupId>org.opendaylight.odlparent</groupId>
<artifactId>odlparent-artifacts</artifactId>
- <version>1.7.0-SNAPSHOT</version>
+ <version>1.8.0-SNAPSHOT</version>
<scope>import</scope>
<type>pom</type>
</dependency>
</dependencies>
</dependencyManagement>
-(the version number there is appropriate for Boron). For the time being
+(the version number there is appropriate for Carbon). For the time being
you also need to depend separately on the individual JARs as
compile-time dependencies to build your dependent code; the relevant
dependencies are managed in ``odlparent``'s dependency management.
- ``odl-lmax``: ``[3.3.4,4.0.0)``
+Features (for Karaf 4)
+----------------------
+
+There are equivalent features to all the Karaf 3 features, for Karaf 4.
+The repositories use “features4” instead of “features”, and the features
+use “odl4” instead of “odl”.
+
+The following new features are specific to Karaf 4:
+
+- Karaf wrapper features (also in the ``features4-odlparent``
+ repository) — these can be used to pull in a Karaf feature
+ using a Maven dependency in a POM:
+
+ - ``odl-karaf-feat-feature`` — the Karaf ``feature`` feature;
+
+ - ``odl-karaf-feat-jdbc`` — the Karaf ``jdbc`` feature;
+
+ - ``odl-karaf-feat-jetty`` — the Karaf ``jetty`` feature;
+
+ - ``odl-karaf-feat-war`` — the Karaf ``war`` feature.
+
+To use these, all you need to do now is add the appropriate dependency
+in your feature POM; for example:
+
+::
+
+ <dependency>
+ <groupId>org.opendaylight.odlparent</groupId>
+ <artifactId>odl4-guava-18</artifactId>
+ <classifier>features</classifier>
+ <type>xml</type>
+ </dependency>
+
+assuming the appropriate dependency management:
+
+::
+
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>org.opendaylight.odlparent</groupId>
+ <artifactId>odlparent-artifacts</artifactId>
+ <version>1.8.0-SNAPSHOT</version>
+ <scope>import</scope>
+ <type>pom</type>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+
+(the version number there is appropriate for Carbon). We no longer use version
+ranges, the feature dependencies all use the ``odlparent`` version (but you
+should rely on the artifacts POM).
Code Review / docs.git / blobdiff