Page tree

Have questions? Stuck? Please check our FAQ for some common questions and answers.

This wiki documents the current development version of ONOS (master). Refer to the Wiki Archives for documentation for all previous versions of ONOS.

Skip to end of metadata
Go to start of metadata

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.

Publish the artifacts to local repository

ONOS project started using BUCK from 1.7.0 hummingbird release. If you want to build ONOS application with maven archetype, you should publish the artifacts to local repository in ~/.m2:

onos-buck-publish-local

Generate your ONOS application project

Let's now generate an ONOS 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 (wink). So let's start by running the following in a directory outside of $ONOS_ROOT:

mvn archetype:generate -DarchetypeGroupId=org.onosproject -DarchetypeArtifactId=onos-bundle-archetype

Notably, this command will download the newest RELEASE version of onos-archetypes plugin and generate an ONOS application.

Alternatively, if you have the ONOS code checked out and available, you can use the onos-create-app tool to accomplish the same thing. It's important to note that if your ONOS is  a SNAPSHOT version and is built with Buck, you should change directory to $ONOS_ROOT/tools/package/archetypes and generate the onos-archetypes firstly:

cd $ONOS_ROOT/tools/package/archetypes
mvn clean install

Then run in a directory outside of $ONOS_ROOT where you want to have your application:

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.

 

Define 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: : 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 the following output:

[INFO] ----------------------------------------------------------------------------
[INFO] Using following parameters for creating project from Archetype: onos-bundle-archetype:1.2.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] project created from Archetype in dir: /private/tmp/onos-app/foo-app
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 01:54 min
[INFO] Finished at: 2014-12-03T18:00:55-08:00
[INFO] Final Memory: 14M/245M
[INFO] ------------------------------------------------------------------------

This has now generated a new project for you. Let's move on to building it and loading it into ONOS.

Loading your generated component into ONOS

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.

$ cd foo-app
$ vi pom.xml

Uncomment the onos.app.name and onos.app.origin properties as shown in the following snippet.

pom.xml
    ...    
    <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:

$ 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.

$ 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,

onos> apps -s
...
   29 org.foo.app                      1.0.SNAPSHOT ONOS OSGi bundle archetype

and it is ready to be activated.

onos> app activate org.foo.app
onos> apps -s
...
*  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. 

Overlays

ONOS applications can hook into the ONOS CLI and GUI. When generating your application, you can use overlays to generate the classes needed to give your application access to these services.

Command Line Overlay

To allow your application to add commands to the ONOS CLI, overlay the CLI interface like this:

Creating a CLI Overlay
onos-create-app cli org.foo.app foo-app 1.0.0

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:

Rebuild and reinstall the app
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):

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:

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 and 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 one of the UI interfaces. Navigate in the shell to the directory in which you have already created your app.

Choose to use either the "Custom View" overlay, like this:

Creating a UI Overlay – Custom View
onos-create-app ui org.foo.app foo-app 1.0.0

... or the "Tabular View" overlay, like this:

Creating a UI Overlay – Tabular View
onos-create-app uitab org.foo.app foo-app 1.0.0

... or you can even create a REST interface for your application, like this:

Creating a REST interface
onos-create-app rest org.foo.app foo-app 1.0.0

 

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:

Rebuild and reinstall the app
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):

onos> app activate org.foo.app

The web UI overlay is now 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.

You can now use the generated web UI to add your own UI elements.

See the Web UI tutorials for more detailed information.

ONOS can automatically generate 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/ . You need to select Sample app REST API to test the URIs of your application.

Happy coding 

Finally your application is loaded and running withing ONOS. Also, the generation process has generated an entire project which can be loaded into your favourite JAVA editor.

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


 

  • No labels