Step Class Reference

This interface represents a type of message log Message. More...

#include <MessageLog.h>

Inheritance diagram for Step:

List of all members.

Public Types

typedef std::vector< Message * >
::iterator iterator

typedef std::vector< Message * >
::const_iterator const_iterator

typedef ::size_t size_t

Public Member Functions

virtual Step * addStep (const std::string &action, const std::string &component, const std::string &key, bool recurse=true)=0

virtual Message * addMessage (const std::string &action, const std::string &component, const std::string &key, bool finalizeOnCreate=false, bool recurse=true)=0

virtual bool finalize (Result result, const std::string &failureReason="")=0

virtual bool finalize ()=0

virtual const std::string & getFailureMessage () const =0

virtual Result getResult () const =0

virtual Step::size_t size () const =0

virtual Step::iterator begin ()=0

virtual Step::const_iterator begin () const =0

virtual Step::iterator end ()=0

virtual Step::const_iterator end () const =0

virtual Message * operator[] (Step::size_t i)=0

virtual const Message * operator[] (Step::size_t i) const =0

Static Public Member Functions

static const std::string & signalMessageAdded ()

static const std::string & signalMessageHidden ()

static const std::string & signalMessageDeleted ()

static const std::string & signalMessageDetached ()

Protected Member Functions

virtual ~Step ()

Detailed Description

This interface represents a type of message log Message.

Steps represent individual algorithmic steps. Each can contain properties and substeps which break the algorithm down further.

Step is a subclass of Subject. It will notify upon the following conditions:

The following methods are called: addStep(), addMessage(),
A sub-Step or Message notifies. An unfinalized Step will forward any notification. pValue will be forwarded, containing a Message* of the originally notifying Message.
Everything else documented in Message.

Definition at line 456 of file MessageLog.h.

Member Typedef Documentation

typedef std::vector<Message*>::iterator Step::iterator

An STL iterator type.

Has the semantics of an std::vector

Definition at line 462 of file MessageLog.h.

typedef std::vector<Message*>::const_iterator Step::const_iterator

An STL iterator type.

Has the semantics of an std::vector

Definition at line 467 of file MessageLog.h.

typedef ::size_t Step::size_t

A type representing sizes and indices.

Definition at line 472 of file MessageLog.h.

Constructor & Destructor Documentation

virtual Step::~Step ( ) [protected, virtual]

This will be cleaned up during application close.

Plug-ins do not need to destroy it.

Definition at line 665 of file MessageLog.h.

Member Function Documentation

static const std::string& Step::signalMessageAdded ( ) [static]

Emitted with any<Message*> when a message is added to the step.

Definition at line 478 of file MessageLog.h.

static const std::string& Step::signalMessageHidden ( ) [static]

Emitted with any<Message*> when a message in the step is finalized.

Definition at line 482 of file MessageLog.h.

static const std::string& Step::signalMessageDeleted ( ) [static]

Emitted with any<Message*> when a message is deleted from the step.

Definition at line 486 of file MessageLog.h.

static const std::string& Step::signalMessageDetached ( ) [static]

Emitted with any<Message*> when a message is detached from the step.

Definition at line 490 of file MessageLog.h.

virtual Step* Step::addStep	(	const std::string &	action,
		const std::string &	component,
		const std::string &	key,
		bool	recurse = `true`
	)			`[pure virtual]`

Creates a new sub-step.

Parameters:

	action	A string describing the nature of the event that triggered the message.
	component	A string specifying the component that is requesting a step be created, for example the name of the plug-in suite logging the step.
	key	A string that specifies a identifier for this step being created. The key combined with the component shall uniquely identify a step.
	recurse	If this is true, steps are recursed and the new Step is added to the deepest un-finalized step.

Returns:: A pointer to the message created. This pointer will be valid until it or a parent message is finalized. This will return NULL if the parent Message object isn't a step.

Subject Notifications:: This method will notify signalMessageAdded with any<Message*>.

virtual Message* Step::addMessage	(	const std::string &	action,
		const std::string &	component,
		const std::string &	key,
		bool	finalizeOnCreate = `false`,
		bool	recurse = `true`
	)			`[pure virtual]`

Adds a sub-message to a step.

Parameters:

	action	A string describing the nature of the event that triggered the message.
	component	A string specifying the component that is requesting a message be created, for example the name of the plug-in suite logging the message.
	key	A string that specifies a identifier for this message being created. The key combined with the component shall uniquely identify a message.
	finalizeOnCreate	If this is true, the Message will be automatically finalize()'d
	recurse	If this is true, steps are recursed and the Message is added to the deepest un-finalized step.

Returns:: A pointer to the message created. This pointer will be valid until it or a parent message is finalized.

Subject Notifications:: This method will notify signalMessageAdded with any<Message*>.

virtual bool Step::finalize	(	Result	result,
		const std::string &	failureReason = `""`
	)			`[pure virtual]`

If the step is a top-level step (i.e.

not a sub-step), this method writes the message and any submessages to the log. No properties can be added to the message or any submessages after finalization. The message pointer and pointers to all of its sub-messages are no longer valid pointers and must not be de-referenced. This will recursively call finalize on all sub-steps and sub-messages, passing a Result of Success to the sub-steps. Calling finalize on a sub-step or sub-message closes the message or step and all sub-messages or sub-steps to modification, but does not cause the sub-step or sub-message to be written to disk. Serialize only actually writes to disk when called on a top-level step or message. Upon finalization of a message, the log will notify all of its observers.

Parameters:

	result	An indication of the cause of the completion of the step.
	failureReason	An message that indicates the reason for step failure. This should ony be used to provided details in the case of message failure.

Returns:: true if successfully closed or written; false otherwise.

virtual bool Step::finalize ( ) [pure virtual]

This method finalizes the current Step with the result being Message::Success and an empty failure reason string.

Returns:: true if the step is successfully closed or written; otherwise returns false.

Implements Message.

virtual const std::string& Step::getFailureMessage ( ) const [pure virtual]

This method returns the failure message passed to the finalize method or an string of length zero if no failure message was provided.

Returns:: the failure message provided to the finalize method.

See also:: Step::finalize

virtual Result Step::getResult ( ) const [pure virtual]

Get the result associated with this Step.

Returns:: The Result of this Step.

virtual Step::size_t Step::size ( ) const [pure virtual]

Obtain the count of Messages in this Step.

Returns:: the number of Messages

virtual Step::iterator Step::begin ( ) [pure virtual]

Obtain an STL iterator over Messages in this Step starting at the begining of the vector.

This iterator has the behavior of a std::vector::iterator

Returns:: an iterator over the Step's Messages

virtual Step::const_iterator Step::begin ( ) const [pure virtual]

Obtain an STL const_iterator over Messages in this Step starting at the begining of the vector.

This iterator has the behavior of a std::vector::const_iterator

Returns:: a const_iterator over the Step's Messages

virtual Step::iterator Step::end ( ) [pure virtual]

Obtain an STL iterator over Messages in this Step starting at the end of the vector.

This iterator has the behavior of a std::vector::iterator

Returns:: an iterator over the Step's Messages

virtual Step::const_iterator Step::end ( ) const [pure virtual]

Obtain an STL const_iterator over Messages in this Step starting at the end of the vector.

This iterator has the behavior of a std::vector::const_iterator

Returns:: a const_iterator over the Step's Messages

virtual Message* Step::operator[] ( Step::size_t i ) [pure virtual]

Get the Message at index i.

This function has the same semantics as std::vector::operator[]. It does not ensure that i is a valid index.

Parameters:

i

The index to return.

Returns:: The Message requested

virtual const Message* Step::operator[] ( Step::size_t i ) const [pure virtual]


Public Types
typedef std::vector< Message * > ::iterator	iterator
typedef std::vector< Message * > ::const_iterator	const_iterator
typedef ::size_t	size_t
Public Member Functions
virtual Step *	addStep (const std::string &action, const std::string &component, const std::string &key, bool recurse=true)=0
virtual Message *	addMessage (const std::string &action, const std::string &component, const std::string &key, bool finalizeOnCreate=false, bool recurse=true)=0
virtual bool	finalize (Result result, const std::string &failureReason="")=0
virtual bool	finalize ()=0
virtual const std::string &	getFailureMessage () const =0
virtual Result	getResult () const =0
virtual Step::size_t	size () const =0
virtual Step::iterator	begin ()=0
virtual Step::const_iterator	begin () const =0
virtual Step::iterator	end ()=0
virtual Step::const_iterator	end () const =0
virtual Message *	operator[] (Step::size_t i)=0
virtual const Message *	operator[] (Step::size_t i) const =0
Static Public Member Functions
static const std::string &	signalMessageAdded ()
static const std::string &	signalMessageHidden ()
static const std::string &	signalMessageDeleted ()
static const std::string &	signalMessageDetached ()
Protected Member Functions
virtual	~Step ()