====== Publishing - ODL Tutorial ======
====== Quickstart ======

  * https://communities.cisco.com/community/developer/opendaylight/blog/2016/02/03/introduction-to-opendaylight-startup-archetype

This is a short introduction to the opendaylight-startup-archetype which is the easiest way to get started writing an OpenDaylight MD-SAL application. An archetype creates a maven project from a template, giving you a working project to start from.

<code>
mvn archetype:generate \
-DarchetypeGroupId=org.opendaylight.controller \
-DarchetypeArtifactId=opendaylight-startup-archetype \
-DarchetypeVersion=1.0.3-Lithium-SR3 \
-DarchetypeRepository=http://nexus.opendaylight.org/content/repositories/opendaylight.release/
-DarchetypeCatalog=http://nexus.opendaylight.org/content/repositories/opendaylight.release/archetype-catalog.xml
</code>

TODO: Check archetypeArtifactId. Each command show diffrent list of archetype.
<code>
mvn archetype:generate -DarchetypeGroupId=org.opendaylight.controller -DarchetypeArtifactId=opendaylight-startup-archetype -DarchetypeRepository=https://nexus.opendaylight.org/content/repositories/public/ -DarchetypeCatalog=https://nexus.opendaylight.org/content/repositories/public/archetype-catalog.xml
</code>

"archetypeCatalog=https://nexus.opendaylight.org/content/repositories/public/archetype-catalog.xml" shows external archetypes.
<code>
mvn archetype:generate \
-DarchetypeGroupId=org.opendaylight.controller \
-DarchetypeArtifactId=opendaylight-startup-archetype \
-DarchetypeRepository=https://nexus.opendaylight.org/content/repositories/opendaylight.release/ \
-DarchetypeCatalog=https://nexus.opendaylight.org/content/repositories/public/archetype-catalog.xml
</code>
"archetypeCatalog=http://nexus.opendaylight.org/content/repositories/opendaylight.snapshot/archetype-catalog.xml" shows only odl archetypes.
<code>
mvn archetype:generate \
-DarchetypeGroupId=org.opendaylight.controller \
-DarchetypeRepository=http://nexus.opendaylight.org/content/repositories/opendaylight.snapshot/ \
-DarchetypeCatalog=http://nexus.opendaylight.org/content/repositories/opendaylight.snapshot/archetype-catalog.xml
</code>

Follow the prompts to set the project parameters. When I ran the archetype I called my project demoproject so the snippets I use will always reference demoproject. Let me explain the structure of the generated project and the purpose of each part.

 

Note that the default value for the 'version' property is 1.0-SNAPSHOT. This causes problems when you want to install the project into an OpenDaylight release such as Lithium-SR3 because it is configured to ignore snapshots. If you set the 'version' property to 1.0 then the generated artifacts will work.

This is the structure of the generated project:

<code>
api  # contains the YANG model for your project
  |-- src/main/yang/demoproject.yang
  `-- pom.xml
impl # contains the project implementation
  |-- src/main/java
  | |-- com/cisco/impl/DemoProvider.java
  | `-- org/.../demoproject/impl/rev141210/DemoModule.java # Your module init class
  |-- src/main/yang/demoproject-impl.yang # YANG definition for your module config
  |-- src/main/config/default-config.xml  # Your module config file
  `-- pom.xml
features # contains the feature definition for Karaf
  |-- src/main/features/features.xml # defines features that can be installed in karaf
  `-- pom.xml
artifacts # maven project that includes all artifacts required by project
  `-- pom.xml # references demoproject-api, demoproject-impl, demoproject-features
karaf # maven project that builds an OpenDaylight karaf distribution
  `-- pom.xml # includes odl-demoproject-ui in the list of karaf local features

</code>
Without changing anything in the generated project, you can build the project and then run the generated Karaf distribution:

<code>
% cd demoproject
% mvn install
% ./karaf/target/assembly/bin/karaf

    ________                      ________                .__  .__      .__    __      
    \_____  \ ______  ____  ____ \______ \ _____  ___.__.|  | |__| ____ |  |___/  |_    
    /  |  \\____ \_/ __ \ /    \ |    |  \\__  \<  |  ||  | |  |/ ___\|  |  \  __\    
    /    |    \  |_> >  ___/|  |  \|    `  \/ __ \\___  ||  |_|  / /_/  >  Y  \  |      
    \_______  /  __/ \___  >___|  /_______  (____  / ____||____/__\___  /|___|  /__|      
            \/|__|        \/    \/        \/    \/\/            /_____/      \/          
                                                                                    

Hit '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command.
Hit '<ctrl-d>' or type 'system:shutdown' or 'logout' to shutdown OpenDaylight.

opendaylight-user@root>feature:list | grep demoproject
odl-demoproject-api  | 1.0-SNAPSHOT | x  | odl-demoproject-1.0-SNAPSHOT | OpenDaylight :: demoproject :: api
odl-demoproject      | 1.0-SNAPSHOT | x  | odl-demoproject-1.0-SNAPSHOT | OpenDaylight :: demoproject
odl-demoproject-rest | 1.0-SNAPSHOT | x  | odl-demoproject-1.0-SNAPSHOT | OpenDaylight :: demoproject :: REST
odl-demoproject-ui  | 1.0-SNAPSHOT | x  | odl-demoproject-1.0-SNAPSHOT | OpenDaylight :: demoproject :: UI

</code>

As you can see, there are 4 features instlalled in karaf from my project. These features are define in the features.xml file. Features are a karaf concept that make it easier to install multiple OSGi bundles and their dependencies. A features.xml file is a "Feature Repository" which can contain multiple feature definitions. Here is the features.xml file with inline comments:

<code>

<?xml version="1.0" encoding="UTF-8"?>
<features name="odl-demoproject-${project.version}" xmlns="http://karaf.apache.org/xmlns/features/v1.2.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://karaf.apache.org/xmlns/features/v1.2.0 http://karaf.apache.org/xmlns/features/v1.2.0">
  <!--
    Karaf features are defined in repositories. In order to reference a feature, you first need to
    declare its repository location. Repositories are just feature definition files that are stored
    in a Maven repo.
  -->
  <repository>mvn:org.opendaylight.yangtools/features-yangtools/${yangtools.version}/xml/features</repository>
  <repository>mvn:org.opendaylight.controller/features-mdsal/${mdsal.version}/xml/features</repository>
  <repository>mvn:org.opendaylight.controller/features-restconf/${mdsal.version}/xml/features</repository>
  <!--
    The odl-demoproject-api feature references the odl-yangtools-models as a dependency and
    adds the demoproject-api bundle. This feature just installs the model into karaf.
  -->
  <feature name='odl-demoproject-api' version='${project.version}' description='OpenDaylight :: demoproject :: api'>
    <feature version='${yangtools.version}'>odl-yangtools-models</feature>
    <bundle>mvn:com.cisco/demoproject-api/${project.version}</bundle>
  </feature>
  <!--
    The odl-demoproject feature references mdsal and the odl-demoproject-api features.
    It adds the demoproject-impl bundle. It also adds a configfile that tells OpenDaylight how
    to start this feature.
  -->
  <feature name='odl-demoproject' version='${project.version}' description='OpenDaylight :: demoproject'>
    <feature version='${mdsal.version}'>odl-mdsal-broker</feature>
    <feature version='${project.version}'>odl-demoproject-api</feature>
    <bundle>mvn:com.cisco/demoproject-impl/${project.version}</bundle>
    <configfile finalname="${configfile.directory}/demoproject.xml">mvn:com.cisco/demoproject-impl/${project.version}/xml/config</configfile>
  </feature>
  <!--
    This feature references the odl-demoproject and odl-restconf features.
    It ensures that the necessary features get installed to allow you to call your application via RESTCONF
  -->
  <feature name='odl-demoproject-rest' version='${project.version}' description='OpenDaylight :: demoproject :: REST'>
    <feature version="${project.version}">odl-demoproject</feature>
    <feature version="${mdsal.version}">odl-restconf</feature>
  </feature>
  <!--
    This feature references the odl-demoproject-rest feature and also MD-SAL apidocs and xsql features.
    It ensures that the necessary features get installed to allow API doc UI to work for your project.
  -->
  <feature name='odl-demoproject-ui' version='${project.version}' description='OpenDaylight :: demoproject :: UI'>
    <feature version="${project.version}">odl-demoproject-rest</feature>
    <feature version="${mdsal.version}">odl-mdsal-apidocs</feature>
    <feature version="${mdsal.version}">odl-mdsal-xsql</feature>
  </feature>
</features>

</code>

You can install your application into a separate OpenDaylight runtime such as the Lithium-SR3 distribution. The maven project builds a Karaf "kar" file in features/target/demoproject-features-1.0.kar which can be copied into the karaf deploy directory:

    % cp demoproject/features/target/demoproject-features-1.0.kar distribution-karaf-0.3.3-Lithium-SR3/deploy

Note that the OpenDaylight Lithium-SR3 distribution is configured to ignore snapshots so it is important that your project does not have a version like 1.0-SNAPSHOT.

====== Scalable Project Structure ======
===== Parent pom Module =====

==== Maven refresher ====

  * *-Management block means the configuration of the artifact is applied for declaring pom and their children. But Child pom must explicitly declare the use of the artifact with groupId and artifactId.
  * Build profile can be activated with condition.
  * Properties are inherited implicitly.


===== Distribution Module =====

===== Main Bundle - Modle =====

===== Main Bundle - Implementation =====

===== Features =====