Table of Contents |
---|
Introduction
In this tutorial we will show you how to generate an ONOS bundle template. This makes it easy for you to add either an ONOS service or application. We will be using maven archetypes to generate our template, therefore this link could be handy if you would like to know more about this process.
...
template application using the onos-create-app
tool. This tool relies on the Maven archetypes to generate a base ONOS application as well as several different variants that add CLI command, REST API, and a few means of extending the GUI.
Select ONOS version
Because the tool uses Maven archetypes, we need to first indicate what version of ONOS API we would like to build our application against. To do this, simply export the ONOS_POM_VERSION
environment variable to the desired ONOS version as follows:
Code Block |
---|
$ export ONOS_POM_VERSION=2.0.0 |
If the above environment variable is not explicitly set, Maven will look for the most recent version of the archetypes available in your ~/.m2/repository
(and then on Maven central) and this may not be what you intended so it's always best to set this explicitly.
Generate a new base ONOS application project
Let's now generate an a skeletal ONOS application project which will be fully compilable and ready to be deployed. Although, you will still have to code up your application, we haven't yet figured out how to generate code that does exactly what you would like it to do . So let's start by running the following in a directory outside of $ONOS_ROOT:
Code Block | ||
---|---|---|
| ||
mvn archetype:generate -DarchetypeGroupId=org.onosproject -DarchetypeArtifactId=onos-bundle-archetype |
When creating the base project, we have to specify the Maven groupId, artifactId and version. These are necessary for locating the application in the Maven coordinate space. Additionally, we will also specify Java package name where the generated code will be located. Let's run the following command:
Code Block |
---|
$ onos-create-app app org.foo foo-app 1.0-SNAPSHOT org.foo.app |
Alternatively, you could invoke mvn archetype:generate
command directly, but we recommend that you Alternatively, if you have the ONOS code checked out and available, you can use the onos-create-app
tool to accomplish the same thing. Run in a directory outside of $ONOS_ROOT:
Code Block |
---|
onos-create-app |
You will now be asked for several pieces of specific information about the bundle you would like to generate as you can see below. Make sure to enter parameters that are appropriate for you.
instead. Also, for a real application, you would want to use your own groupId, artifactId, etc., but for the purpose of this tutorial, it is recommended that you use the suggested values.
After this you should see the following output:
Code Block | ||
---|---|---|
| ||
Define[INFO] value for property 'groupId': : org.foo Define value for property 'artifactId': : foo-app Define value for property 'version': 1.0-SNAPSHOT: : Define value for property 'package': org.foo: :Scanning for projects... [INFO] [INFO] ------------------------------------------------------------------------ [INFO] Building Maven Stub Project (No POM) 1 [INFO] ------------------------------------------------------------------------ [INFO] [INFO] >>> maven-archetype-plugin:3.0.1:generate (default-cli) > generate-sources @ standalone-pom >>> [INFO] [INFO] <<< maven-archetype-plugin:3.0.1:generate (default-cli) < generate-sources @ standalone-pom <<< [INFO] [INFO] --- maven-archetype-plugin:3.0.1:generate (default-cli) @ standalone-pom --- [INFO] Generating project in Interactive mode [INFO] Archetype [org.onosproject:onos-bundle-archetype:2.1.0-SNAPSHOT] found in catalog local [INFO] Using property: groupId = org.foo [INFO] Using property: artifactId = foo-app [INFO] Using property: version = 1.0-SNAPSHOT [INFO] Using property: package = org.foo.app Confirm properties configuration: groupId: org.foo artifactId: foo-app version: 1.0-SNAPSHOT package: org.foo.app Y: : |
After this you should see Confirm the properties by typing "y
" and you will be presented with the following output:
Code Block | ||
---|---|---|
| ||
Y: : y [INFO] ---------------------------------------------------------------------------- [INFO] Using following parameters for creating project from Archetype: onos-bundle-archetype:12.20.0-SNAPSHOT [INFO] ---------------------------------------------------------------------------- [INFO] Parameter: groupId, Value: org.foo [INFO] Parameter: artifactId, Value: foo-app [INFO] Parameter: version, Value: 1.0-SNAPSHOT [INFO] Parameter: package, Value: org.foo.app [INFO] Parameter: packageInPathFormat, Value: org/foo/app [INFO] Parameter: package, Value: org.foo.app [INFO] Parameter: version, Value: 1.0-SNAPSHOT [INFO] Parameter: groupId, Value: org.foo [INFO] Parameter: artifactId, Value: foo-app [INFO] projectProject created from Archetype in dir: /privateUsers/tmptom/onos-appfoobar/foo-app [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 01:54 min24.439 s [INFO] Finished at: 20142019-1203-03T1811T17:0035:5521-0807:00 [INFO] Final Memory: 14M/245M219M [INFO] ------------------------------------------------------------------------ |
This has now generated a new project for you. Note that the onos-bundle-archetype
version 2.0.0
was used for this. This is because we explicitly set the ONOS_POM_VERSION
to 2.0.0
.
Let's move on to building it and loading it into ONOS.
Loading your generated component into ONOS
Compile, install and activate your new ONOS application
Now we are ready to build the ONOS app. We can do that by changing into the root directory of the generated project and invoking Maven as follows:If you want to designate the newly created project as an ONOS application, rather than just an OSGi bundle, enter the directory of your generated component and edit the pom.xml
file within.
Code Block |
---|
$ cd foo-app
$ vi pom.xml |
Uncomment the onos.app.name
and onos.app.origin
properties as shown in the following snippet.
Code Block | ||||
---|---|---|---|---|
| ||||
...
<properties>
<onos.version>1.2.0-SNAPSHOT</onos.version>
<onos.app.name>org.foo.app</onos.app.name>
<onos.app.origin>Foo, Inc.</onos.app.origin>
</properties>
... |
This will instruct the onos-maven-plugin
to package the bundle as an ONOS application by producing an .oar
(ONOS Application aRchive). After saving the changes, build the project as follows:
Code Block |
---|
$ mvn clean install |
When the build is complete, both the OSGi bundle and the application archive have been installed in your local maven repository. To install the application into running ONOS instance (or cluster), you can use the onos-app
tool, which uses ONOS REST API within, to upload the .oar
file as shown in the following example. If you need help running ONOS please refer to this page. Note that by using the exclamation mark with the install
parameter, the application will be activated immediately after being installed.
Code Block | ||
---|---|---|
| ||
$ onos-app localhost install! target/foo-app-1.0-SNAPSHOT.oar |
Now, from the ONOS console, you should be able to see the application has been installed and activated,
Code Block | ||
---|---|---|
| ||
onos> apps -s ... 29 org.foo.app 1.0.SNAPSHOT ONOS OSGi bundle archetype |
and it is ready to be activated.
Code Block | ||
---|---|---|
| ||
onos> app activate org.foo.app onos> apps -s-a ... * 29 org.foo.app 1.0.SNAPSHOT ONOS OSGi bundle archetype |
You can now use the generated code for this test app as a framework for adding your own custom code. If you edit the file src/main/java/org/foo/app/AppComponent.java
, you can see how the application is created, and add your own code to the application.
...
Generate various project overlays
ONOS applications can hook into the ONOS CLI, REST API and GUI. When generating your application, you can use overlays to generate the classes needed to give your application access to these services.
...
Code Block | ||
---|---|---|
| ||
$ onos-create-app cli org.foo.app foo-app 1.0.0-SNAPSHOT org.foo.app |
Now, as before, we need to build and install our application. Since we installed it once already, we will use the reinstall!
command to deploy it:
Code Block | ||
---|---|---|
| ||
$ mvn clean install $ onos-app localhost reinstall org.foo.app! target/foo-app-1.0-SNAPSHOT.oar |
Using the ONOS command line, restart the application (or use reinstall! in the command above):
Code Block |
---|
onos> app activate org.foo.app |
Using the ONOS command line, we now have access to the 'sample' command, which was defined by our overlay:
Code Block |
---|
onos> sample Hello World |
...
You can use the CLI overlay to add your own commands to the CLI for your app. Edit the file src/main/java/org/foo/app/AppCommand.java
to see how the sample command is implemented.
REST API Overlay
You can even create a REST interface for your application by overlaying a REST API project facet. Run the following to generate the project overlay and to rebuild and reinstall the application:
Code Block | ||||
---|---|---|---|---|
| ||||
$ onos-create-app rest org.foo foo-app 1.0-SNAPSHOT org.foo.app
$ mvn clean install
$ onos-app localhost reinstall! target/foo-app-1.0-SNAPSHOT.oar |
Note that ONOS automatically generates SwaggerUI documentation for the URIs exposed in your RESTful application. After activating the application, you can visit the SwaggerUI at http://localhost:8181/v1/docs/ . To view the documentation for the newly generated app REST API, you will need to select Sample app REST API from the SwaggerUI menu bar the file src/main/resources/OSGI-INF/blueprint/shell-config.xml to see how new commands are integrated into the existing CLI.
User Interface Overlays
To allow your application to add to the ONOS web UI, overlay you can use one of the UI interfacesseveral different project overlays. Navigate in the shell to the directory in which you have already created your app .and run one of the following commands:
... generate a Choose to use either the "Custom View" overlay, like this:
Code Block | ||
---|---|---|
| ||
$ onos-create-app ui org.foo.app foo-app 1.0.0-SNAPSHOT org.foo.app |
... or the "Tabular View" overlay, like this:
Code Block | ||
---|---|---|
| ||
$ onos-create-app uitab org.foo foo-app 1.0-SNAPSHOT org.foo.app |
... or the "Topology Overlay" overlay, like this:
Code Block | ||
---|---|---|
| ||
$ onos-create-app uitopo org.foo foo-app 1.0.0 |
...
-SNAPSHOT org.foo.app |
Now, as before, we need to build and install our application. Since we installed it once already, we will use the reinstall command to deploy it:
Code Block | ||
---|---|---|
| ||
$ mvn clean install $ onos-app localhost reinstall! org.foo.app target/foo-app-1.0-SNAPSHOT.oar |
Using the ONOS command line, restart the application (or use reinstall! in the command above):
Code Block |
---|
onos> app activate org.foo.app |
The web UI overlay is now active. To Your new forms of application that extends the GUI will now be active. To view the new application page that was just created, point your browser to the ONOS GUI at http://localhost:8181/onos/ui/. In the upper left corner of the home page, click the navigation button to activate the drop down navigation menu. At the bottom of the list, you will see an entry for "Sample Custom" or "Sample Table", depending on which overlay you used. If you select it, you will navigate to the page that was installed by your test application.
...
See the Web UI tutorials for more detailed information.
Happy coding
...
Publish the artifacts to local repository
Note that, if you wish to build an application against the current ONOS master, i.e. an unreleased version, you will need to first build ONOS yourself and then publish the resulting artifacts in the Maven repository under ~/.m2/repository
by running the following command:
Code Block | ||
---|---|---|
| ||
$ onos-publish -l # publish ONOS libraries only |
Also, you will have to build the current version of the ONOS application archetypes as follows:
Code Block | ||
---|---|---|
| ||
$ cd $ONOS_ROOT/tools/package/archetypes
$ mvn clean install # yes, the archetypes are still built via Maven |
Happy coding
Learn more about the Application Subsystem.
Here is a post on Sample PortStatistics Application tutorial based on template application tutorial .
...
Return To : Tutorials and Walkthroughs
...