How to port a v0.91- module to the new API in v1.0+

Owned by Ryan Izard
Last updated: Aug 22, 2018
3 min read

Please familiarize yourself with the OpenFlowJ-Loxi tutorial prior to attempting to port your code.

If you have an older module written for Floodlight v0.91 or earlier, you might wish to convert it to the new APIs used in Floodlight v1.0 and higher to take advantage of new features, OpenFlow 1.3, and/or bug fixes.

If you'd rather not read but see an example of some ported code instead, here is a before and after for the DHCP server module's package:

Before, v0.90: https://github.com/rizard/DHCPServerForFloodlight/tree/master/floodlight-DHCPServer/src/main/java/net/floodlightcontroller/dhcpserver

After, v1.1: https://github.com/floodlight/floodlight/tree/master/src/main/java/net/floodlightcontroller/dhcpserver

This tutorial is intended as a guide and not step-by-step instructions. The exact instructions will vary for each custom module, but this is the recommended "recipe" for porting your code.

  1. Throughout the controller, primitive types have been replaced with classes where possible to enable safer code and to reduce the likelihood of bugs. For example, in Floodlight v1.0+, the DatapathId class replaces anyplace a long or String was used to store a switch DPID. The same is true for switch ports, which are not shorts but are exposed as type OFPort or OFPortDesc depending on the location. IPv4 addresses are now type IPv4Address, and MAC addresses are now type MacAddress. The old IPv4 and MAC address utilities have been removed, since the OpenFlowJ-Loxi library includes all those features within the library. The list of type changes is quite long, so I will not enumerate them all.

    Any value type can be constructed using the .of() function within that type, e.g. DatapathId.of("00:11:22:33:44:55:66:77"), OFPort.of(48), or IPv4Address.of("192.168.1.1"). You should not, nor can you, use the keyword "new" to create any value types.

    These types of changes (no pun intended) will likely constitute 90% of the work when porting code to the new API. Each change here will be trivial, but depending on how complex your module is and how effective find-and-replace is for you, changing the types is likely to be the most tedious step when porting your code.

  2. All types that represent OpenFlow "concepts" such as OFPacketOut, OFFlowAdd, Match, OFActionOutput, OFInstructionApplyActions, etc. are all instantiated using builders now – OFPacketOut.Builder, OFFlowAdd.Builder, Match.Builder, OFActionOutput.Builder, OFInstructionApplyActions.Builder, etc., respectively. These builders are exposed from an OFFactory that you can either get from an IOFSwitch's getOFFactory() function, or through OFFactories.getFactory(OFVersion.OF_13), for example.

    As a rule of thumb, you should never see the keyword "new" anywhere in your module unless it's your own type that you're instantiating. The OpenFlowJ-Loxi library constructs all concept types through the builder pattern, and once constructed, the type is immutable.

  3. Imports, imports, imports. The location of many classes have changed. Most importantly, the new library is in org.projectfloodlight.openflow.*. Most items you'll need are in the org.projectfloodlight.openflow.protocol or org.projectfloodlight.openflow.types packages. Many new types are defined in org.projectfloodlight.openflow.types, which we discussed in item #1 above. A good strategy is to first figure out what types you're going to update. Then, as you update your types, an IDE like Eclipse will help you add the correct import, which might clear up many existing import errors. Oftentimes, step #3 here can be completed as you complete step #1 and #2.

  4. In Floodlight v1.0+, switches are managed by a switch manager exposed via the IOFSwitchService. This is separate from the IFloodlightProviderService used for managing switches in v0.91-. Each time you lookup a switch, you'll want to use the IOFSwitchService instead. Simply depend on and add this new service in the same way you do already for IFloodlightProviderService. Then, use your new IOFSwitchService variable to access switches where and when you need them. Notice that the IFloodlightProviderService is still how you register to listen for OFPacketIn messages – this you will not and should not change.

Four steps, that's all? Yes, that's about it. You might have other changes you need to make though, depending of course on what you do in your module. If it's not a change specific to the internals of your module, write to our email list, and we will add your insight/findings to this page.