[[TOC(heading=Tutorial TOC, Tutorial, depth=2)]]
= How to integrate your application with Node Handler =

This tutorial is for users who want to use the NodeHandler to launch their applications on the nodes in an experiment. For example, we assume that you want to launch 
{{{
   tcpdump -i eth1
}}}
on all the nodes in the experiment. 

Three steps are needed

== Step 1: Create application definition file ==
This definition tells the Node Handler about your new application that you want to launch. It mainly includes details such as what are the command line options it takes and what are the statistics it returns. Here is a sample application definition for our above application

'''Think about this as a class definition for your application'''
 * '''Put this file in your home directory as test_app_tcpdump.rb'''

{{{
#
# Create an application representation from scratch
#
require 'handler/appDefinition'

a = AppDefinition.create('test:app:tcpdump')
a.name = "tcpdump"
a.version(0, 0, 1)
a.shortDescription = "Tcpdump application"
a.description = <<TEXT
TCPDump application
TEXT

# addProperty(name, description, mnemonic, type, isDynamic = false, constraints = nil)

#Here ?i means tcpdump will be launched with -i <interface> option
a.addProperty('interface', 'Interface to run on', ?i, String, false)

a.path = "/usr/sbin/tcpdump"

if $0 == __FILE__
  require 'stringio'
  require 'rexml/document'
  include REXML

  sio = StringIO.new()
  a.to_xml.write(sio, 2)
  sio.rewind
  puts sio.read

  sio.rewind
  doc = Document.new(sio)
  t = AppDefinition.from_xml(doc.root)

  puts
  puts "-------------------------"
  puts
  t.to_xml.write($stdout, 2)

end

}}}
 

== Step 2: Prototype definition ==
After informing nodeHandler about our new application, we then need to create a prototype using our application definition. 

'''Think about this as an instance of your above class'''
 * '''Put this file in your home directory as test_proto_tcpdumper.rb'''
{{{
#
# Define a prototype
#

require 'handler/prototype'
require 'handler/filter'
require 'handler/appDefinition'

p = Prototype.create("test:proto:tcpdumper")
p.name = "TCPdump proto"
p.description = "TCPdump"
p.defProperty('interface', 'Interface to listen on')


tcpd = p.addApplication('aodvd', "test:app:tcpdump")
tcpd.bindProperty('interface')



if $0 == __FILE__
  p.to_xml.write($stdout, 2)
  puts
end

}}}

== Step 3: Using this prototype in an actual script ==

The following example script uses our newly defined application definition. 
{{{
##################################################
# TCPDump using nodeHandler
##################################################

Experiment.name = "tutorial-tcpdump"
Experiment.project = "orbit:tutorial"

#
# Define nodes used in experiment
#
defGroup('nodes', [[1,1],[1,2]]) {|node|
  node.image = nil  # assume the right image to be on disk

  node.prototype("test:proto:tcpdumper", {
    'interface' => 'eth1' #This is where we assign the interface for this specific instance
   })
  node.net.w0.mode = "master"
}


allGroups.net.w0 { |w|
  w.type = 'b'
  w.essid = "helloworld"
  w.ip = "%192.168.%x.%y"
}

#
# Now, start the application
#
whenAllInstalled() {|node|
 # Launch TCPdump on all nodes

  #startApplications will launch all the applications defined for the group "nodes"
  NodeSet['nodes'].startApplications

 

  wait 180

  Experiment.done
}

}}}