summaryrefslogtreecommitdiffstats
path: root/sdnr/wireless-transport/code-Carbon-SR1/docs/README2CreateApp4Carbon.md
blob: e21b3aa414070b2f7e82abcd7f5695a0a19c8113 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
# Create app for ODL Boron and some backgrounds

## Common information and workshop tasks

### Overall

  - Demo ODL, GUI and Simulators
  - [Opendaylight](http://5g-crosshaul.eu/wp-content/uploads/2016/10/UC3M_5tonic_SdnOdlDay_19Oct2016.pdf)
    - Three slides: 6:MDSAL, 8:AppDev, 11:Karaf
  - Demo Eclipse
  - User's home and the tools to use
  - Git/ Maven &co mvn command, .m2
  - HANDS-ON: Setup Single server development environment
    - Follow [DevEnv](READMEInstallDevelopmentEnvironment.md)

### Karaf

   - OSGi and what does Karaf do
     - [osgi](https://en.wikipedia.org/wiki/OSGi)
     - [karaf](https://stackoverflow.com/questions/17350281/what-exactly-is-apache-karaf)
   - How does it come and the directory structure
     - Opendaylight karaf [odlkaraf](https://nexus.opendaylight.org/content/groups/public/org/opendaylight/integration/distribution-karaf/)
     - show setup
         - Repository
         - data log
   - Bundles and Features
     - related xml files
   - clean start
   - Start&stop
     - commands start/stop/client
     - command karaf
   - command line
     - start and list features and bundles
   - Debug and log files
     - see read me
   - Problems
     - Startup timing

### Network applications

   - commons bundle and parents
     - See CENTENNIAL/code/features (features-parent)
     - binding-parent => Access of MDSAL
     - config-parent => Push config xml file
   - Karaf / Yang and the device model
   - DLUX, Angular JS, Chromium
   - Clone myapp
   - ODL Datamodel, Access the database and the Netconf model
   - [Documentation Boron](http://docs.opendaylight.org/en/stable-boron/)
   - [ArchetypeRPCHelloWorld](https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:Startup_Project_Archetype)


## 1. Create app for ODL Boron

### 1.1. Prerequirements

- Development environment for ODL Boron according to Description "InstallDevelopmentEnvironment".
- Clone from git the projects CENTENNIAL and WirelessTranportEmulator to get the following structure
    ```
    odl
    ├── CENTENNIAL
    ├── WirelessTransportEmulator
    └── distribution-karaf-0.6.1-Carbon
    ```

### 1.2. Create the app

Approach is to copy the template application in the CENTENNIAL repository apps directory and adapt it to the needs.<br/>
  - Northbound: Provide RPC northbound
  - Southbound: Monitors mountpoints connected to netconf devices.

The template app is located here:

    CENTENNIAL/code/apps/template/
    ├── api
    │   ├── pom.xml
    │   └── src
    ├── impl
    │   ├── pom.xml
    │   └── src
    ├── features
    │   ├── pom.xml
    │   └── src
    └── pom.xml

Use the commandline and copy template to a new directory and modify with vi

    cd ~/odl/CENTENNIAL/code/apps
    cp -r template myapp

### 1.3. Adapt myapp

Remove files which are recreated later

    cd myapp
    rm -r target api/target impl/target
    rm -r .settings/ api/.settings/ impl/.settings/
    rm -r .project api/.project impl/.project

Change with eclipse editor (or vi) within the directory tree the four pom.xml files from<br/>
template_something to myapp_something

  Example:

      <artifactId>myapp</artifactId>
      <name>myapp</name>

Adapt in the impl/pom.xml and the features/pom.xml the dependency to the myapps-api project.

Import into eclipse under the apps working set, that you see the new projects:
  - myapp
  - myapp-api
  - myapp-impl
  - myapp-features

Using eclipse do rename

  - filename or partial filenames from "template" to "myapp"
    - .yang file in myapp-api
    - .yang file in myapp-impl
  - bundle name in myapp-impl/src/main/java to org.opendaylight.mwtn.myapp

Modify module name, namespace, prefix revision date of myapp-api yang file:

    module myapp {
        yang-version 1;
        namespace "urn:opendaylight:params:xml:ns:yang:myapp";
        prefix "myapp";

        revision "2018-01-23" {
            description "Initial revision of myapp model";
        }

        rpc hello-world {
            input {
                leaf name {
                    type string;
                }
            }
            output {
                leaf greeting {
                    type string;
                }
            }
        }
    }

Similar with myapp-impl yang file. Adapt module name, namespace, prefix, revision date, java-name-prefix.

    module myapp-impl {
        yang-version 1;
        namespace "urn:opendaylight:params:xml:ns:yang:myapp:impl";
        prefix "myapp-impl";

        import config { prefix config; revision-date 2013-04-05; }
        import opendaylight-md-sal-binding { prefix md-sal-binding; revision-date 2013-10-28;}

        description
            "Service definition for myapp project";

        revision "2018-01-23" {
            description
                "Initial myapp revision";
        }

        identity myapp {
            base config:module-type;
            config:java-name-prefix MyappImpl;
        }

        augment "/config:modules/config:module/config:configuration" {
            case myapp {
                when "/config:modules/config:module/config:type = 'myapp'";
                container broker {
                    uses config:service-ref {
                        refine type {
                            mandatory true;
                            config:required-identity md-sal-binding:binding-broker-osgi-registry;
                        }
                    }
                }
            }
        }
    }

Adapt Java classes using eclipse refactor

  - TemplateAppProvider -> MyAppProvider
  - TemplateServiceImpl -> MyAppServiceImpl

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.

HINT2: After cli/maven build is done use F5 to see all generated files files.

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.

Enable  *eclipse -> project -> Build Automatically* or use maven build command below to build the app.<br/>

    cd myapp
    mvn clean install -DskipTests -Dmaven.javadoc.skip=true

You see the new created sources with the timestamp in the package name.<br/>
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.

Next steps:

  - Remove the old package.
  - Correct the imports where necessary

If all errors are corrected, do a cli maven build. If you see this you are ready with this section.

    [INFO] Reactor Summary:
    [INFO]
    [INFO] myapp-api .......................................... SUCCESS [ 10.130 s]
    [INFO] myapp-impl ......................................... SUCCESS [  4.644 s]
    [INFO] ONF :: Wireless :: myapp-features .................. SUCCESS [  8.811 s]
    [INFO] myapp .............................................. SUCCESS [  3.727 s]
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------

In case of errors:

  - Remove all targets
    rm -r target api/target impl/target features/target
  - Grep for all string "template" and replace
    grep -r template
  - Activate enough logging
  - (!)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.


### 1.4 Test it

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:

    cd ~/odl/CENTENNIAL/code
    mvn clean install -DskipTests

HINT2: If karaf container is already running you get a feedback that start is not possible. Use the stop command to stop it:

    cd ~/odl/CENTENNIAL/code
    ./install.sh stop

HIN3: In new environment you should use the the ```./odl``` command insteadt of ```./install.sh```
Change to the code directory and start the karaf container using the *imd* option:

    cd ~/odl/CENTENNIAL/code
    ./install.sh imd

To **Test it** step into to the karaf cli:

    ./karafcmd.sh

Add the new feature in the karaf command line:

    feature:repo-add mvn:org.opendaylight.mwtn/myapp-features/0.4.0-SNAPSHOT/xml/features
    feature:install odl-mwt-myapp
    bundle:list

You are done with this test if you see something like this, especially the last line is important!

    herbert@vm2-herbert:~/odl/distribution-karaf-0.5.3-Boron-SR3/data/log$ grep -ia "session i" *
    2018-01-23 20:24:18,651 | INFO  | config-pusher    | TemplateProvider                 | 331 - org.opendaylight.mwtn.template-impl - 0.4.0.SNAPSHOT | TemplateProvider Session Initiated
    2018-01-23 20:24:18,760 | INFO  | config-pusher    | WebsocketmanagerProvider         | 329 - org.opendaylight.mwtn.websocketmanager-impl - 0.4.0.SNAPSHOT | WebsocketmanagerProvider Session Initiated
    2018-01-23 20:26:39,218 | INFO  | config-pusher    | MyAppProvider                    | 337 - org.opendaylight.mwtn.myapp-impl - 0.4.0.SNAPSHOT | TemplateProvider Session Initiated

Nect test is to access the RPC via restonf. This is done via ODLs APIDOC explorer.
Use this link to open the application, enter login credentials admin, admin <br/>
[odl apidoc](http://127.0.0.1:8181/apidoc/explorer/index.html)


### 1.5. Change higher-level POM files

  - code/feature.xml
  - code/pom.xml

### 1.6. Adapt install.sh script

  - code/install.sh

## 2.0 Test and debug app

### 2.1 Setup and connect netconf simulator


### 2.2 Setup ODL debug level


### Remarks

  - Karaf Intro and Install
  - Simulators