sdnr/wireless-transport/code-Carbon-SR1/docs/README2CreateApp4Carbon.md

   1 # Create app for ODL Boron and some backgrounds
   2
   3 ## Common information and workshop tasks
   4
   5 ### Overall
   6
   7   - Demo ODL, GUI and Simulators
   8   - [Opendaylight](http://5g-crosshaul.eu/wp-content/uploads/2016/10/UC3M_5tonic_SdnOdlDay_19Oct2016.pdf)
   9     - Three slides: 6:MDSAL, 8:AppDev, 11:Karaf
  10   - Demo Eclipse
  11   - User's home and the tools to use
  12   - Git/ Maven &co mvn command, .m2
  13   - HANDS-ON: Setup Single server development environment
  14     - Follow [DevEnv](READMEInstallDevelopmentEnvironment.md)
  15
  16 ### Karaf
  17
  18    - OSGi and what does Karaf do
  19      - [osgi](https://en.wikipedia.org/wiki/OSGi)
  20      - [karaf](https://stackoverflow.com/questions/17350281/what-exactly-is-apache-karaf)
  21    - How does it come and the directory structure
  22      - Opendaylight karaf [odlkaraf](https://nexus.opendaylight.org/content/groups/public/org/opendaylight/integration/distribution-karaf/)
  23      - show setup
  24          - Repository
  25          - data log
  26    - Bundles and Features
  27      - related xml files
  28    - clean start
  29    - Start&stop
  30      - commands start/stop/client
  31      - command karaf
  32    - command line
  33      - start and list features and bundles
  34    - Debug and log files
  35      - see read me
  36    - Problems
  37      - Startup timing
  38
  39 ### Network applications
  40
  41    - commons bundle and parents
  42      - See CENTENNIAL/code/features (features-parent)
  43      - binding-parent => Access of MDSAL
  44      - config-parent => Push config xml file
  45    - Karaf / Yang and the device model
  46    - DLUX, Angular JS, Chromium
  47    - Clone myapp
  48    - ODL Datamodel, Access the database and the Netconf model
  49    - [Documentation Boron](http://docs.opendaylight.org/en/stable-boron/)
  50    - [ArchetypeRPCHelloWorld](https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:Startup_Project_Archetype)
  51
  52
  53 ## 1. Create app for ODL Boron
  54
  55 ### 1.1. Prerequirements
  56
  57 - Development environment for ODL Boron according to Description "InstallDevelopmentEnvironment".
  58 - Clone from git the projects CENTENNIAL and WirelessTranportEmulator to get the following structure
  59     ```
  60     odl
  61     ├── CENTENNIAL
  62     ├── WirelessTransportEmulator
  63     └── distribution-karaf-0.6.1-Carbon
  64     ```
  65
  66 ### 1.2. Create the app
  67
  68 Approach is to copy the template application in the CENTENNIAL repository apps directory and adapt it to the needs.<br/>
  69   - Northbound: Provide RPC northbound
  70   - Southbound: Monitors mountpoints connected to netconf devices.
  71
  72 The template app is located here:
  73
  74     CENTENNIAL/code/apps/template/
  75     ├── api
  76     │   ├── pom.xml
  77     │   └── src
  78     ├── impl
  79     │   ├── pom.xml
  80     │   └── src
  81     ├── features
  82     │   ├── pom.xml
  83     │   └── src
  84     └── pom.xml
  85
  86 Use the commandline and copy template to a new directory and modify with vi
  87
  88     cd ~/odl/CENTENNIAL/code/apps
  89     cp -r template myapp
  90
  91 ### 1.3. Adapt myapp
  92
  93 Remove files which are recreated later
  94
  95     cd myapp
  96     rm -r target api/target impl/target
  97     rm -r .settings/ api/.settings/ impl/.settings/
  98     rm -r .project api/.project impl/.project
  99
 100 Change with eclipse editor (or vi) within the directory tree the four pom.xml files from<br/>
 101 template_something to myapp_something
 102
 103   Example:
 104
 105       <artifactId>myapp</artifactId>
 106       <name>myapp</name>
 107
 108 Adapt in the impl/pom.xml and the features/pom.xml the dependency to the myapps-api project.
 109
 110 Import into eclipse under the apps working set, that you see the new projects:
 111   - myapp
 112   - myapp-api
 113   - myapp-impl
 114   - myapp-features
 115
 116 Using eclipse do rename
 117
 118   - filename or partial filenames from "template" to "myapp"
 119     - .yang file in myapp-api
 120     - .yang file in myapp-impl
 121   - bundle name in myapp-impl/src/main/java to org.opendaylight.mwtn.myapp
 122
 123 Modify module name, namespace, prefix revision date of myapp-api yang file:
 124
 125     module myapp {
 126         yang-version 1;
 127         namespace "urn:opendaylight:params:xml:ns:yang:myapp";
 128         prefix "myapp";
 129
 130         revision "2018-01-23" {
 131             description "Initial revision of myapp model";
 132         }
 133
 134         rpc hello-world {
 135             input {
 136                 leaf name {
 137                     type string;
 138                 }
 139             }
 140             output {
 141                 leaf greeting {
 142                     type string;
 143                 }
 144             }
 145         }
 146     }
 147
 148 Similar with myapp-impl yang file. Adapt module name, namespace, prefix, revision date, java-name-prefix.
 149
 150     module myapp-impl {
 151         yang-version 1;
 152         namespace "urn:opendaylight:params:xml:ns:yang:myapp:impl";
 153         prefix "myapp-impl";
 154
 155         import config { prefix config; revision-date 2013-04-05; }
 156         import opendaylight-md-sal-binding { prefix md-sal-binding; revision-date 2013-10-28;}
 157
 158         description
 159             "Service definition for myapp project";
 160
 161         revision "2018-01-23" {
 162             description
 163                 "Initial myapp revision";
 164         }
 165
 166         identity myapp {
 167             base config:module-type;
 168             config:java-name-prefix MyappImpl;
 169         }
 170
 171         augment "/config:modules/config:module/config:configuration" {
 172             case myapp {
 173                 when "/config:modules/config:module/config:type = 'myapp'";
 174                 container broker {
 175                     uses config:service-ref {
 176                         refine type {
 177                             mandatory true;
 178                             config:required-identity md-sal-binding:binding-broker-osgi-registry;
 179                         }
 180                     }
 181                 }
 182             }
 183         }
 184     }
 185
 186 Adapt Java classes using eclipse refactor
 187
 188   - TemplateAppProvider -> MyAppProvider
 189   - TemplateServiceImpl -> MyAppServiceImpl
 190
 191 HINT1: The enabled *eclipse -> project -> Build Automatically* option interferes with external Maven builds in the command line. You can see strange errors during maven build. If this is the case than disable it and try again. Basically handling is easier if option is switched on, but disable it before you use cli/maven.
 192
 193 HINT2: After cli/maven build is done use F5 to see all generated files files.
 194
 195 HINT3: If you feel that errors are all corrected, but the errors will not go away in eclipse use *eclipse -> projects -> clean* for the project.
 196
 197 Enable  *eclipse -> project -> Build Automatically* or use maven build command below to build the app.<br/>
 198
 199     cd myapp
 200     mvn clean install -DskipTests -Dmaven.javadoc.skip=true
 201
 202 You see the new created sources with the timestamp in the package name.<br/>
 203 Open "MyAppImplModule" and fill the implementation with addapted code similar to the code in the "TemplateImplModule.java" in the function "createInstance()". The eclipse refactor has already renamed the code snippet to the right class name.
 204
 205 Next steps:
 206
 207   - Remove the old package.
 208   - Correct the imports where necessary
 209
 210 If all errors are corrected, do a cli maven build. If you see this you are ready with this section.
 211
 212     [INFO] Reactor Summary:
 213     [INFO]
 214     [INFO] myapp-api .......................................... SUCCESS [ 10.130 s]
 215     [INFO] myapp-impl ......................................... SUCCESS [  4.644 s]
 216     [INFO] ONF :: Wireless :: myapp-features .................. SUCCESS [  8.811 s]
 217     [INFO] myapp .............................................. SUCCESS [  3.727 s]
 218     [INFO] ------------------------------------------------------------------------
 219     [INFO] BUILD SUCCESS
 220     [INFO] ------------------------------------------------------------------------
 221
 222 In case of errors:
 223
 224   - Remove all targets
 225     rm -r target api/target impl/target features/target
 226   - Grep for all string "template" and replace
 227     grep -r template
 228   - Activate enough logging
 229   - (!)Remove in the karaf the xml config file: rm $ODL_KARAF_HOME/etc/opendaylight/karaf/myapp.xml. New install of the feature/bundle is required to re-create this file.
 230
 231
 232 ### 1.4 Test it
 233
 234 HINT1: At this point your .m2 repository needs to contain all jars of the applications in apps, features and ux. If not done before you need to compile everything with the following command:
 235
 236     cd ~/odl/CENTENNIAL/code
 237     mvn clean install -DskipTests
 238
 239 HINT2: If karaf container is already running you get a feedback that start is not possible. Use the stop command to stop it:
 240
 241     cd ~/odl/CENTENNIAL/code
 242     ./install.sh stop
 243
 244 HIN3: In new environment you should use the the ```./odl``` command insteadt of ```./install.sh```
 245 Change to the code directory and start the karaf container using the *imd* option:
 246
 247     cd ~/odl/CENTENNIAL/code
 248     ./install.sh imd
 249
 250 To **Test it** step into to the karaf cli:
 251
 252     ./karafcmd.sh
 253
 254 Add the new feature in the karaf command line:
 255
 256     feature:repo-add mvn:org.opendaylight.mwtn/myapp-features/0.4.0-SNAPSHOT/xml/features
 257     feature:install odl-mwt-myapp
 258     bundle:list
 259
 260 You are done with this test if you see something like this, especially the last line is important!
 261
 262     herbert@vm2-herbert:~/odl/distribution-karaf-0.5.3-Boron-SR3/data/log$ grep -ia "session i" *
 263     2018-01-23 20:24:18,651 | INFO  | config-pusher    | TemplateProvider                 | 331 - org.opendaylight.mwtn.template-impl - 0.4.0.SNAPSHOT | TemplateProvider Session Initiated
 264     2018-01-23 20:24:18,760 | INFO  | config-pusher    | WebsocketmanagerProvider         | 329 - org.opendaylight.mwtn.websocketmanager-impl - 0.4.0.SNAPSHOT | WebsocketmanagerProvider Session Initiated
 265     2018-01-23 20:26:39,218 | INFO  | config-pusher    | MyAppProvider                    | 337 - org.opendaylight.mwtn.myapp-impl - 0.4.0.SNAPSHOT | TemplateProvider Session Initiated
 266
 267 Nect test is to access the RPC via restonf. This is done via ODLs APIDOC explorer.
 268 Use this link to open the application, enter login credentials admin, admin <br/>
 269 [odl apidoc](http://127.0.0.1:8181/apidoc/explorer/index.html)
 270
 271
 272 ### 1.5. Change higher-level POM files
 273
 274   - code/feature.xml
 275   - code/pom.xml
 276
 277 ### 1.6. Adapt install.sh script
 278
 279   - code/install.sh
 280
 281 ## 2.0 Test and debug app
 282
 283 ### 2.1 Setup and connect netconf simulator
 284
 285
 286 ### 2.2 Setup ODL debug level
 287
 288
 289 ### Remarks
 290
 291   - Karaf Intro and Install
 292   - Simulators