com.h3c.of.ctl

Interface ControllerService

All Known Implementing Classes:

ControllerServiceAdapter

public interface ControllerService

Provides the public API to the SDN OpenFlow Controller — a one-stop-shop for SDN applications interacting with the controller.

This service allows applications to:

• register as packet listeners, to participate in the processing of Packet-In messages
• register as datapath listeners, to be notified when OpenFlow datapaths connect to, or disconnect from, the controller
• register as message listeners, to be notified when OpenFlow messages sent from connected datapaths are received by the controller
• request information about the OpenFlow datapaths currently connected to the controller
• instruct the controller to send an OpenFlow message to an OpenFlow datapath
• register as flow listeners, to request information about flows installed on a given datapath
• instruct the controller to send flows through the Flow Tracker
• request information about the pipeline definition for a given datapath

Method Summary

Methods

Modifier and Type	Method and Description
void	addDataPathListener(DataPathListener listener) Adds the specified datapath listener to the controller.
void	addFlowListener(FlowListener listener) Adds the specified flow listener to the controller.
void	addGroupListener(GroupListener listener) Adds the specified group listener to the controller.
void	addMessageListener(MessageListener listener, Set<MessageType> types) Adds the specified message listener to the controller.
void	addMeterListener(MeterListener listener) Adds the specified meter listener to the controller.
void	addPacketListener(SequencedPacketListener listener, PacketListenerRole role, int altitude) Adds the specified packet listener to the packet sequencer, in the specified role and at the specified altitude.
void	addPacketListener(SequencedPacketListener listener, PacketListenerRole role, int altitude, Set<ProtocolId> interest) Adds the specified packet listener to the sequencer, in the specified role and at the specified altitude.
MessageContext	createMsgContext(OpenflowEventType type, OpenflowMessage msg, DataPathId dpid, int auxId, ProtocolVersion pv)
MessageContextForHost	createMsgContextForHost(MessageContext context, boolean bL3Forwarding)
MessageContextForPath	createMsgContextForPath(MessageContext context, boolean bL3Forwarding)
MessageFuture	enablePort(DataPathId dpid, BigPortNumber port, boolean enable) Instructs the controller to enable or disable the given port on the specified datapath.
Set<DataPathInfo>	getAllDataPathInfo() Returns information describing each of the OpenFlow datapaths currently connected to the controller.
ControllerMx	getControllerMx() Returns an instance of the management interface.
DataPathInfo	getDataPathInfo(DataPathId dpid) Returns information describing a specific OpenFlow datapath.
MBodyDesc	getDesc(DataPathInfo dpinfo)
List<MBodyExperimenter>	getExperimenter(DataPathId dpid) Returns meter configuration or statistics (for OF 1.0 datapaths), encoded in experimenter multipart replies.
List<MBodyFlowStats>	getFlowStats(DataPathId dpid, TableId tableId) Returns flows installed in the specified table of the given datapath.
List<MBodyGroupDescStats>	getGroupDescription(DataPathId dpid) Returns the group descriptions from the specified datapath.
MBodyGroupDescStats	getGroupDescription(DataPathId dpid, GroupId groupId) Returns the group description for the given group ID, from the specified datapath.
MBodyGroupFeatures	getGroupFeatures(DataPathId dpid) Returns the supported group features for the specified datapath.
List<MBodyGroupStats>	getGroupStats(DataPathId dpid) Returns the group statistics from the specified datapath.
MBodyGroupStats	getGroupStats(DataPathId dpid, GroupId groupId) Returns the group statistics for the given group ID, from the specified datapath.
List<MBodyMeterConfig>	getMeterConfig(DataPathId dpid) Returns the meter configuration details from the specified datapath.
MBodyMeterConfig	getMeterConfig(DataPathId dpid, MeterId meterId) Returns the meter configuration for the given meter ID, from the specified datapath.
MBodyMeterFeatures	getMeterFeatures(DataPathId dpid) Returns the meter features for the specified datapath.
List<MBodyMeterStats>	getMeterStats(DataPathId dpid) Returns the meter statistics from the specified datapath.
MBodyMeterStats	getMeterStats(DataPathId dpid, MeterId meterId) Returns the meter statistics for the given meter ID, from the specified datapath.
List<SequencedPacketListener>	getPacketListeners(PacketListenerRole role) Returns an ordered list of packet listeners registered with the packet sequencer, for the specified role.
PipelineDefinition	getPipelineDefinition(DataPathId dpid) Returns the PipelineDefinition for the given datapath.
List<MBodyPortStats>	getPortStats(DataPathId dpid) Returns the port statistics from the specified datapath.
MBodyPortStats	getPortStats(DataPathId dpid, BigPortNumber portNumber) Returns the port statistics for the given port, from the specified datapath.
ControllerStats	getStats() Returns statistical information about the controller.
void	removeDataPathListener(DataPathListener listener) Removes the specified datapath listener from the controller.
void	removeFlowListener(FlowListener listener) Removes the specified flow listener from the controller.
void	removeGroupListener(GroupListener listener) Removes the specified group listener from the controller.
void	removeMessageListener(MessageListener listener) Removes the specified message listener from the controller.
void	removeMeterListener(MeterListener listener) Removes the specified meter listener from the controller.
void	removePacketListener(SequencedPacketListener listener) Removes the specified packet listener from the packet sequencer.
List<MessageFuture>	send(List<OpenflowMessage> msgs, DataPathId dpid) Instructs the controller to send the specified list of messages (in order) to the specified datapath.
MessageFuture	send(OpenflowMessage msg, DataPathId dpid) Instructs the controller to send the specified message to the specified datapath.
MessageFuture	sendFlowMod(OfmFlowMod flowMod, DataPathId dpid) Sends the given FlowMod message to the specified datapath.
MessageFuture	sendGroupMod(OfmGroupMod groupMod, DataPathId dpid) Sends the given GroupMod message to the specified datapath.
MessageFuture	sendMeterMod(OfmMeterMod meterMod, DataPathId dpid) Sends the given MeterMod message to the specified datapath.
ProtocolVersion	versionOf(DataPathId dpid) Returns the (negotiated) protocol version of the specified datapath.

Method Detail

addPacketListener

void addPacketListener(SequencedPacketListener listener,
                     PacketListenerRole role,
                     int altitude)

Adds the specified packet listener to the packet sequencer, in the specified role and at the specified altitude. Higher altitudes come earlier in the sequence than lower altitudes (within the specific role). Note that no two listeners (in the same role) may register with the same altitude; if this is attempted an exception will be thrown.

The listener's event() callback will be invoked for every Packet-In message that the controller passes to the packet sequencer.

Parameters:

listener - the listener to be added

role - the role the listener wishes to assume

altitude - the listener's altitude

Throws:

NullPointerException - if listener or role is null

IllegalArgumentException - if altitude is negative

IllegalStateException - if the altitude (for the role) has already been claimed

See Also:

addPacketListener(SequencedPacketListener, PacketListenerRole, int, Set)

addPacketListener

void addPacketListener(SequencedPacketListener listener,
                     PacketListenerRole role,
                     int altitude,
                     Set<ProtocolId> interest)

Adds the specified packet listener to the sequencer, in the specified role and at the specified altitude. Higher altitudes come earlier in the sequence than lower altitudes (within the specific role). Note that no two listeners (in the same role) may register with the same altitude; if this is attempted an exception will be thrown.

The interest argument specifies the protocols that the listener cares about. When the sequencer receives a Packet-In message, it will be forwarded to the listener if the packet contains any protocol that is a member of the specified set.

Parameters:

listener - the listener to be added

role - the role the listener wishes to assume

altitude - the listener's altitude

interest - the packet protocols the listener is interested in

Throws:

NullPointerException - if listener or role is null

IllegalArgumentException - if altitude is negative

IllegalStateException - if the altitude (for the role) has already been claimed

See Also:

addPacketListener(SequencedPacketListener, PacketListenerRole, int)

removePacketListener

void removePacketListener(SequencedPacketListener listener)

Removes the specified packet listener from the packet sequencer.

Parameters:

listener - the listener to be removed

Throws:

NullPointerException - if listener is null

getPacketListeners

List<SequencedPacketListener> getPacketListeners(PacketListenerRole role)

Returns an ordered list of packet listeners registered with the packet sequencer, for the specified role. The order of listeners is that of descending altitude.

Parameters:

role - the role to examine

Returns:

the packet listeners in this role

Throws:

NullPointerException - if role is null

addMessageListener

void addMessageListener(MessageListener listener,
                      Set<MessageType> types)

Adds the specified message listener to the controller.

The types argument specifies the types of message that the listener cares about. When the controller receives a message, it will be forwarded to the listener if and only if the message's type is a member of the specified set.

An empty set (or null) is taken to mean that the listener wants to hear about every message, regardless of type. However, PacketIn messages are not forwarded in this case; see note below.

If a listener calls this method when it is already registered, the specified set of message types completely replaces the original set.

Important Note:
PacketIn messages are processed exclusively by the packet sequencer. To participate in PacketIn processing, you must use addPacketListener(SequencedPacketListener, PacketListenerRole, int, Set). Attempting to request PacketIn messages by including PACKET_IN in the types set will throw an exception.

Parameters:

listener - the listener to be added

types - the message types the listener cares about

Throws:

NullPointerException - if listener is null

IllegalArgumentException - types includes PACKET_IN

removeMessageListener

void removeMessageListener(MessageListener listener)

Removes the specified message listener from the controller.

Parameters:

listener - the listener to be removed

Throws:

NullPointerException - if listener is null

addDataPathListener

void addDataPathListener(DataPathListener listener)

Adds the specified datapath listener to the controller.

Parameters:

listener - the listener to be added

Throws:

NullPointerException - if listener is null

removeDataPathListener

void removeDataPathListener(DataPathListener listener)

Removes the specified datapath listener from the controller.

Parameters:

listener - the listener to be removed

Throws:

NullPointerException - if listener is null

getAllDataPathInfo

Set<DataPathInfo> getAllDataPathInfo()

Returns information describing each of the OpenFlow datapaths currently connected to the controller.

Returns:

information describing all connected datapaths

getDataPathInfo

DataPathInfo getDataPathInfo(DataPathId dpid)

Returns information describing a specific OpenFlow datapath. A NotFoundException will be thrown if there is no datapath connected to the controller with the given ID.

Parameters:

dpid - the datapath id

Returns:

information describing the corresponding datapath

Throws:

NullPointerException - if dpid is null

NotFoundException - if the specified datapath does not exist

versionOf

ProtocolVersion versionOf(DataPathId dpid)

Returns the (negotiated) protocol version of the specified datapath. A NotFoundException will be thrown if there is no datapath connected to the controller with the given ID.

Parameters:

dpid - the datapath ID

Returns:

the negotiated protocol version

Throws:

NullPointerException - if dpid is null

NotFoundException - if the specified datapath does not exist

getStats

ControllerStats getStats()

Returns statistical information about the controller.

Returns:

controller statistics

getPortStats

List<MBodyPortStats> getPortStats(DataPathId dpid)

Returns the port statistics from the specified datapath.

Note that this is a synchronous call that blocks until all the port statistics replies have returned from the datapath.

Parameters:

dpid - the target datapath

Returns:

the list of port statistics

Throws:

NullPointerException - if dpid is null

NotFoundException - if the specified datapath does not exist

getPortStats

MBodyPortStats getPortStats(DataPathId dpid,
                          BigPortNumber portNumber)

Returns the port statistics for the given port, from the specified datapath.

Note that this is a synchronous call that blocks until the port statistics reply has returned from the datapath.

Parameters:

dpid - the target datapath

portNumber - the target port

Returns:

the port statistics

Throws:

NullPointerException - if dpid is null

NotFoundException - if the specified datapath does not exist or the specified port does not exist on the datapath

enablePort

MessageFuture enablePort(DataPathId dpid,
                       BigPortNumber port,
                       boolean enable)

Instructs the controller to enable or disable the given port on the specified datapath. A message future is returned, to allow the caller to discover the outcome of the request once it has been satisfied.

Parameters:

dpid - the target datapath

port - the target port

enable - true to enable; false to disable

Returns:

a message future

Throws:

NullPointerException - if either parameter is null

NotFoundException - if the specified datapath does not exist or the specified port does not exist on the datapath

send

MessageFuture send(OpenflowMessage msg,
                 DataPathId dpid)
                   throws OpenflowException

Instructs the controller to send the specified message to the specified datapath. A message future is returned, to allow the caller to discover the outcome of the request once it has been satisfied.

Important Note:
The sending of FlowMod messages via this method is disallowed; use sendFlowMod(com.h3c.of.lib.msg.OfmFlowMod, com.h3c.of.lib.dt.DataPathId) instead.

Parameters:

msg - the OpenFlow message to send

dpid - the OpenFlow datapath to which the message is to be sent

Returns:

a message future

Throws:

NullPointerException - if either parameter is null

IllegalArgumentException - if msg is mutable, or if it is a FlowMod

OpenflowException - if there was a problem encoding or sending the message

send

List<MessageFuture> send(List<OpenflowMessage> msgs,
                       DataPathId dpid)
                         throws OpenflowException

Instructs the controller to send the specified list of messages (in order) to the specified datapath. A list of message futures (one for each message) is returned, to allow the caller to discover the outcome of the requests once they have been satisfied.

Important Note:
The sending of FlowMod messages via this method is disallowed; use sendFlowMod(com.h3c.of.lib.msg.OfmFlowMod, com.h3c.of.lib.dt.DataPathId) instead.

Parameters:

msgs - the OpenFlow messages to send

dpid - the OpenFlow datapath to which the messages are to be sent

Returns:

a list of message futures

Throws:

NullPointerException - if either parameter is null, or if any element in the list is null

IllegalArgumentException - if any message in the list is mutable, or is a FlowMod

OpenflowException - if there was a problem encoding or sending the messages

getControllerMx

ControllerMx getControllerMx()
                             throws AuthorizationException

Returns an instance of the management interface. For this method to succeed, the caller must be in the list of known authorized classes in ControllerManagementAuthorizer.

Returns:

a handle on the management interface

Throws:

AuthorizationException - if the caller is not authorized

getFlowStats

List<MBodyFlowStats> getFlowStats(DataPathId dpid,
                                TableId tableId)

Returns flows installed in the specified table of the given datapath. If the table ID is not given (i.e. tableId is null) then all tables are assumed.

If the specified table ID is TableId.ALL, all flows from all tables will be returned. Note that table ID is ignored for OpenFlow 1.0 devices.

Note that this is a synchronous call that blocks until all the flow statistics replies have returned from the datapath.

Parameters:

dpid - the datapath from which the flows are requested

tableId - the ID of the flow table

Returns:

the list of flow statistics

Throws:

NullPointerException - if dpid is null

NotFoundException - if the specified datapath does not exist

sendFlowMod

MessageFuture sendFlowMod(OfmFlowMod flowMod,
                        DataPathId dpid)
                          throws OpenflowException

Sends the given FlowMod message to the specified datapath. A message future is returned, to allow the caller to discover the outcome of the request once it has been satisfied.

Adds the specified flow to the given datapath if the message's command is ADD. Deletes the specified flow from the given datapath if the message's command is DELETE.

Parameters:

flowMod - the FlowMod message to send

dpid - the target datapath

Returns:

a message future

Throws:

NullPointerException - if either parameter is null

IllegalArgumentException - if flowMod is mutable

NotFoundException - if the specified datapath does not exist

OpenflowException - if there was an issue sending the message

See Also:

FlowModCommand

addFlowListener

void addFlowListener(FlowListener listener)

Adds the specified flow listener to the controller.

Parameters:

listener - the flow listener to be added

Throws:

NullPointerException - if listener is null

removeFlowListener

void removeFlowListener(FlowListener listener)

Removes the specified flow listener from the controller.

Parameters:

listener - the flow listener to be removed

Throws:

NullPointerException - if listener is null

getGroupDescription

List<MBodyGroupDescStats> getGroupDescription(DataPathId dpid)

Returns the group descriptions from the specified datapath.

Note that this is a synchronous call that blocks until all the group description replies have returned from the datapath.

Parameters:

dpid - the target datapath

Returns:

the list of group descriptions

Throws:

NullPointerException - if dpid is null

NotFoundException - if the specified datapath does not exist

VersionMismatchException - if datapath is not OpenFlow 1.3 compliant

getGroupDescription

MBodyGroupDescStats getGroupDescription(DataPathId dpid,
                                      GroupId groupId)

Returns the group description for the given group ID, from the specified datapath.

Note that this is a synchronous call that blocks until the group description reply has returned from the datapath.

Parameters:

dpid - the target datapath

groupId - the ID of the group

Returns:

the group description

Throws:

NullPointerException - if either parameter is null

NotFoundException - if the specified datapath or group does not exist

VersionMismatchException - if datapath is not OpenFlow 1.3 compliant

getGroupStats

List<MBodyGroupStats> getGroupStats(DataPathId dpid)

Returns the group statistics from the specified datapath.

Note that this is a synchronous call that blocks until all the group statistics replies have returned from the datapath.

Parameters:

dpid - the target datapath

Returns:

the list of group statistics

Throws:

NullPointerException - if dpid is null

NotFoundException - if the specified datapath does not exist

VersionMismatchException - if datapath is not OpenFlow 1.3 compliant

getGroupStats

MBodyGroupStats getGroupStats(DataPathId dpid,
                            GroupId groupId)

Returns the group statistics for the given group ID, from the specified datapath.

Note that this is a synchronous call that blocks until the group statistics reply has returned from the datapath.

Parameters:

dpid - the target datapath

groupId - the target group ID

Returns:

the group statistics

Throws:

NullPointerException - if either parameter is null

NotFoundException - if the specified datapath or group does not exist

VersionMismatchException - if datapath is not OpenFlow 1.3 compliant

getGroupFeatures

MBodyGroupFeatures getGroupFeatures(DataPathId dpid)

Returns the supported group features for the specified datapath.

Note that this is a synchronous call that blocks until the group features reply has returned from the datapath.

Parameters:

dpid - the target datapath

Returns:

the group features

Throws:

NullPointerException - if dpid id null

NotFoundException - if the specified datapath does not exist

VersionMismatchException - if datapath is not OpenFlow 1.3 compliant

sendGroupMod

MessageFuture sendGroupMod(OfmGroupMod groupMod,
                         DataPathId dpid)
                           throws OpenflowException

Sends the given GroupMod message to the specified datapath. A message future is returned, to allow the caller to discover the outcome of the request once it has been satisfied.

Adds the group entry to the specified datapath if the message's command is ADD. Modifies the group entry on the specified datapath if the message's command is MODIFY. Deletes the group entry from the specified datapath if the message's command is DELETE.

Parameters:

groupMod - the GroupMod message to send

dpid - the target datapath

Returns:

a message future

Throws:

NullPointerException - if either parameter is null

IllegalArgumentException - if groupMod is mutable

NotFoundException - if the specified datapath does not exist

OpenflowException - if there was an issue sending the message

See Also:

GroupModCommand

addGroupListener

void addGroupListener(GroupListener listener)

Adds the specified group listener to the controller.

Parameters:

listener - the group listener to be added

Throws:

NullPointerException - if listener is null

removeGroupListener

void removeGroupListener(GroupListener listener)

Removes the specified group listener from the controller.

Parameters:

listener - the group listener to be removed

Throws:

NullPointerException - if listener is null

getMeterConfig

List<MBodyMeterConfig> getMeterConfig(DataPathId dpid)

Returns the meter configuration details from the specified datapath.

Note that this is a synchronous call that blocks until all the meter configuration replies have returned from the datapath.

Parameters:

dpid - the target datapath

Returns:

the list of meter configurations

Throws:

NullPointerException - if dpid is null

NotFoundException - if the specified datapath does not exist

VersionMismatchException - if datapath is not OpenFlow 1.3 compliant

getMeterConfig

MBodyMeterConfig getMeterConfig(DataPathId dpid,
                              MeterId meterId)

Returns the meter configuration for the given meter ID, from the specified datapath.

Note that this is a synchronous call that blocks until all the meter configuration reply has returned from the datapath.

Parameters:

dpid - the target datapath

meterId - the ID of the meter

Returns:

the meter configuration

Throws:

NullPointerException - if either parameter is null

NotFoundException - if the specified datapath or meter does not exist

VersionMismatchException - if datapath is not OpenFlow 1.3 compliant

getMeterStats

List<MBodyMeterStats> getMeterStats(DataPathId dpid)

Returns the meter statistics from the specified datapath.

Note that this is a synchronous call that blocks until all the meter statistics replies have returned from the datapath.

Parameters:

dpid - the target datapath

Returns:

the list of meter statistics

Throws:

NullPointerException - if dpid is null

NotFoundException - if the specified datapath does not exist

VersionMismatchException - if datapath is not OpenFlow 1.3 compliant

getMeterStats

MBodyMeterStats getMeterStats(DataPathId dpid,
                            MeterId meterId)

Returns the meter statistics for the given meter ID, from the specified datapath.

Note that this is a synchronous call that blocks until the meter statistics reply has returned from the datapath.

Parameters:

dpid - the target datapath

meterId - the target meter ID

Returns:

the meter statistics

Throws:

NullPointerException - if either parameter is null

NotFoundException - if the specified datapath or meter does not exist

VersionMismatchException - if datapath is not OpenFlow 1.3 compliant

getMeterFeatures

MBodyMeterFeatures getMeterFeatures(DataPathId dpid)

Returns the meter features for the specified datapath.

Note that this is a synchronous call that blocks until the meter features reply has returned from the datapath.

Parameters:

dpid - the target datapath

Returns:

the meter features

Throws:

NullPointerException - if dpid is null

NotFoundException - if the specified datapath does not exist

VersionMismatchException - if datapath is not OpenFlow 1.3 compliant

getExperimenter

List<MBodyExperimenter> getExperimenter(DataPathId dpid)

Returns meter configuration or statistics (for OF 1.0 datapaths), encoded in experimenter multipart replies.

Note that this is a synchronous call that blocks until the replies have returned from the datapath.

Parameters:

dpid - the target datapath

Returns:

the list of configuations or statistics

Throws:

NullPointerException - if dpid is null

NotFoundException - if the specified datapath does not exist

sendMeterMod

MessageFuture sendMeterMod(OfmMeterMod meterMod,
                         DataPathId dpid)
                           throws OpenflowException

Sends the given MeterMod message to the specified datapath. A message future is returned, to allow the caller to discover the outcome of the request once it has been satisfied.

Adds the meter to the specified datapath if the message's command is ADD. Modifies the meter on the specified datapath if the message's command is MODIFY. Deletes the meter from the specified datapath if the message's command is DELETE.

Parameters:

meterMod - the MeterMod message to send

dpid - the target datapath

Returns:

a message future

Throws:

NullPointerException - if either parameter is null

IllegalArgumentException - if meterMod is mutable

NotFoundException - if the specified datapath does not exist

OpenflowException - if there was an issue sending the message

See Also:

MeterModCommand

addMeterListener

void addMeterListener(MeterListener listener)

Adds the specified meter listener to the controller.

Parameters:

listener - the meter listener to be added

Throws:

NullPointerException - if listener is null

removeMeterListener

void removeMeterListener(MeterListener listener)

Removes the specified meter listener from the controller.

Parameters:

listener - the meter listener to be removed

Throws:

NullPointerException - if listener is null

getPipelineDefinition

PipelineDefinition getPipelineDefinition(DataPathId dpid)

Returns the PipelineDefinition for the given datapath.

Parameters:

dpid - the target datapath

Returns:

the pipeline definition for the given datapath

Throws:

NullPointerException - if dpid is null

NotFoundException - if the specified datapath does not exist

getDesc

MBodyDesc getDesc(DataPathInfo dpinfo)

Parameters:

dpinfo -

Returns:

createMsgContext

MessageContext createMsgContext(OpenflowEventType type,
                              OpenflowMessage msg,
                              DataPathId dpid,
                              int auxId,
                              ProtocolVersion pv)

createMsgContextForHost

MessageContextForHost createMsgContextForHost(MessageContext context,
                                            boolean bL3Forwarding)

createMsgContextForPath

MessageContextForPath createMsgContextForPath(MessageContext context,
                                            boolean bL3Forwarding)