Add seed code for sdnr app based on ONF Centennial
[ccsdk/apps.git] / 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