Decomposition Class Reference
[Network Data Structures]

class encapsulating the breakdown of a Trace into substreams according to some criteria More...

#include <Aggregate.h>

Inheritance diagram for Decomposition:

List of all members.

Public Types
typedef std::map< StreamKeyWrapper, Aggregate * >::const_iterator	const_iterator
Public Member Functions
	Decomposition (const Decomposition &toCopy)
Decomposition *	clone (void) const
virtual const TraceIterator &	addPacket (const StreamKey &stream, Packet *pkt)
	add a packet to the specified stream
virtual std::map< StreamKeyWrapper, Aggregate * >::iterator	addSubstream (const StreamKey &stream, Aggregate *aggr) throw ( DuplicateElementException )
	Add a substream to the Decomposition.
void	expireSubstream (const StreamKey &stream) throw ( ElementNotFoundException )
	move an active substream to the expired list
void	eraseSubstream (const StreamKey &stream) throw ( ElementNotFoundException )
	erase an active substream
bool	addStreamAttrib (const std::string &ident, const Attribute &attrib)
	Add an attribute to the Decomposition that is to be computed on a per-stream basis, as opposed to for the entire Decomposition.
bool	addStreamListener (StreamListener &listener)
	add an object listening for stream events
uint32_t	callSubstreamListeners (StreamEvent &e) throw ( ListenerConflictException )
	call entities listening for new substreams to be added
std::map< StreamKeyWrapper, Aggregate * >::iterator	activeSubstreamsBegin (void)
std::map< StreamKeyWrapper, Aggregate * >::const_iterator	activeSubstreamsBegin (void) const
std::map< StreamKeyWrapper, Aggregate * >::iterator	activeSubstreamsEnd (void)
std::map< StreamKeyWrapper, Aggregate * >::const_iterator	activeSubstreamsEnd (void) const
std::map< StreamKeyWrapper, Aggregate * >::iterator	activeSubstreamsFind (const StreamKey &key)
std::map< StreamKeyWrapper, Aggregate * >::const_iterator	activeSubstreamsFind (const StreamKey &key) const
std::vector< Aggregate * >::iterator	expiredSubstreamsBegin (void)
std::vector< Aggregate * >::const_iterator	expiredSubstreamsBegin (void) const
std::vector< Aggregate * >::iterator	expiredSubstreamsEnd (void)
std::vector< Aggregate * >::const_iterator	expiredSubstreamsEnd (void) const
virtual int	getPacketCount (void) const
	Return the number of packets contained within the aggregate.
const Attribute &	getAttrib (const std::string &ident) const throw ( UnknownAttributeException )
	Return a reference to the requested attribute, or throw an exception if the attribute doesn't exist for this aggregate.
const StreamKey &	getStreamKey (void) const
virtual void	addAttrib (const std::string &ident, const Attribute &attrib, uint32_t tier=0)
	Add an attribute to the aggregate.
void	addListener (PacketListener &listener)
void	setParent (Aggregate &p)
void	setStreamKey (const StreamKey &stream)
virtual void	handlePacket (TraceIterator &newPkt)
void	copyFrom (const Aggregate &toCopy)
void	clear (void)
Static Public Attributes
static const uint32_t	MAX_FOLLOWON_DEPTH = 3
Protected Member Functions
Decomposition &	operator= (const Decomposition &rhs)
void	callListeners (TraceIterator &newPkt)
Protected Attributes
std::map< std::string, Attribute * >	attributes
std::vector< std::vector< Attribute * > >	tiers
std::map< std::string, Aggregate * >	aggregates
std::vector< PacketListener * >	listeners
StreamKey *	streamKey
Aggregate *	parent
Static Protected Attributes
static const PacketCountAttribute	countAttrib

---

Detailed Description

class encapsulating the breakdown of a Trace into substreams according to some criteria

A Decomposition is an aggregate of aggregates that are derived from a common Aggregate, subdivided according to some criterion or criteria. For example, a stream of IPv4Packets could be decomposed by ( ip.src, ip.dst ) to give a set of packet streams where each stream corresponds to all packets exchanged between a particular pair of hosts; a stream of such packets could be decomposed by ( ip.proto ), then the ip.proto == 6 stream could be passed through a TCP sessionizer to create a decomposition by ( tcp.src_port, tcp.dst_port, tcp.sessionID ), where each stream is a TCP session. (Note that tcp.sessionID in that example would be a pseudo-attribute generated by the TCP sessionizer to distinguish sessions)

A Decomposition is fairly passive; most of the heavy lifting is done by classes using it.

Examples:

profile_streams_thesis.cc, and test_harness.cc.

---

Member Function Documentation

void Aggregate::addAttrib (  const std::string &  ident, const Attribute &  attrib, uint32_t  tier = 0 )  [virtual, inherited]

Add an attribute to the aggregate. Parameters: [in]  attrib  is a pointer to an attribute to be added; the attribute includes a specification of how the attribute is to be computed. The attribute will be cloned before being added to the aggregate. Examples: profile_streams_thesis.cc, and test_harness.cc.

void Aggregate::addListener (  PacketListener &  listener  )  [inherited]

Add a PacketListener for the aggregate Parameters: listener  PacketListener wishing to be notified of new packets Note: Will not take responsibility for the listener; its memory will still have to be cleaned up. Note that this is NOT an issue for Attributes, as the attributes of an aggregate are cleaned up independently of its listeners. Examples: profile_streams_thesis.cc, and test_harness.cc.

const TraceIterator & Decomposition::addPacket (  const StreamKey &  stream, Packet *  pkt )  [virtual]

add a packet to the specified stream Parameters: stream  Stream for new packet pkt  Packet to add Returns: a KeyedTraceIterator describing the location of the new packet Warning: The return value is a reference to a static local variable; if you need to hang on to it, clone it. Also, don't call this twice in one statement, or there WILL be trouble. Note: takes ownership of the given packet and will deallocate its memory when cleaning up currently no enforced restriction that the streams be keyed with homogeneous keys; however, I haven't tested it with heterogeneous keys, so I wouldn't recommend it.

bool Decomposition::addStreamAttrib (  const std::string &  ident, const Attribute &  attrib )

Add an attribute to the Decomposition that is to be computed on a per-stream basis, as opposed to for the entire Decomposition. Each new stream created as part of the Decomposition will take a copy of the attribute for itself. Parameters: ident  identifier for attribute attrib  attribute to be computed Returns: true on success, false on failure Deprecated: moving this kind of intelligence out of the Decomposition into the parser

bool Decomposition::addStreamListener (  StreamListener &  listener  )

add an object listening for stream events Note: StreamListeners are not the responsibility of the Decomposition and will be neither cloned nor destroyed with the Decomposition. Examples: profile_streams_thesis.cc.

map< StreamKeyWrapper, Aggregate * >::iterator Decomposition::addSubstream (  const StreamKey &  stream, Aggregate *  aggr )  throw ( DuplicateElementException ) [virtual]

Add a substream to the Decomposition. Add a new substream to the Decomposition. It's assumed that the Aggregate being added has already been appropriately configured wrt attributes and listeners. Parameters: stream  - key for the substream aggr  - aggregate to hold the substream items Note: It's up to the user to remember what their Decomposition holds - Traces or other Decompositions. The parent and streamkey values for the substream will be set appropriately by this method.

void Aggregate::callListeners (  TraceIterator &  newPkt  )  [protected, inherited]

Notify any listeners that a packet has been added to the Aggregate. Note: Any Aggregate subclasses have to invoke this method when a new packet is added; for now, it's too difficult to do a template method trick.

void Decomposition::eraseSubstream (  const StreamKey &  stream  )  throw ( ElementNotFoundException )

erase an active substream Note: erasing expired substreams not yet supported - it's expected that we'll discard those we want to discard at time of expiry.

const Attribute & Aggregate::getAttrib (  const std::string &  ident  )  const throw ( UnknownAttributeException ) [inherited]

Return a reference to the requested attribute, or throw an exception if the attribute doesn't exist for this aggregate. Parameters: ident  string identifying the Attribute requested, will correspond, in the usual case, to the string used to add the attribute with addAttrib (q.v.). ident could also be of a compound form comprised of zero or more subaggregates followed by an attribute followed by zero or more subattributes, all dot-seperated. e.g. "forward.count" to get the value of the PacketCount attribute 'count' of the subaggregate 'forward', or "count.forward" to get the forward subattribute of the PacketCount attribute 'count', or "port80.count.forward" to get the 'forward' subattribute of the 'count' attribute of the 'port80' subaggregate. Exceptions: UnknownAttributeException  thrown if no Attribute of the requested name has been added to the Aggregate. Examples: profile_streams_thesis.cc, and test_harness.cc.

int Aggregate::getPacketCount (  void   )  const [virtual, inherited]

Return the number of packets contained within the aggregate. The count of packets in an Aggregate can also be accessed via the 'count' attribute - for non-Trace Aggregates, that may be the only reliable way to get it, as this method probably will not be implemented properly. Todo: this is going to get tricky if we need a packet count of non-basic aggregates that contain other (not necessarily exclusive) aggregates (i.e. overlapping sub-aggregates). Reimplemented in Trace.

void Aggregate::handlePacket (  TraceIterator &  newPkt  )  [virtual, inherited]

handler for a new packet Implements PacketListener.

Decomposition & Decomposition::operator= (  const Decomposition &  rhs  )  [protected]

not implemented; provided to avoid implicit definitions and for later implementation

---

Member Data Documentation

std::map<std::string, Aggregate*> Aggregate::aggregates [protected, inherited]

sub-aggregates

std::map<std::string, Attribute*> Aggregate::attributes [protected, inherited]

attributes

const PacketCountAttribute Aggregate::countAttrib [static, protected, inherited]

prototype packet count attribute - a clone will be added by individual aggregates

std::vector<PacketListener*> Aggregate::listeners [protected, inherited]

ProtocolParsers listening for new packets

Aggregate* Aggregate::parent [protected, inherited]

Aggregate containing this one, if any

StreamKey* Aggregate::streamKey [protected, inherited]

Key indicating to which stream this Trace belongs, if applicable

std::vector< std::vector<Attribute*> > Aggregate::tiers [protected, inherited]

tiers for prioritizing attributes Todo: reimplement this to use a vector of pairs and the STL sort algorithm

---

The documentation for this class was generated from the following files:

• data_structures/Aggregate.h
• data_structures/Aggregate.cc

---