VMessageHandler Class Reference

VMessageHandler is the abstract base class for objects that process inbound messages from various client connections. More...

#include <vmessagehandler.h>

List of all members.

Public Member Functions
	VMessageHandler (const VString &name, VMessagePtr m, VServer *server, VClientSessionPtr session, VSocketThread *thread, const VMessageFactory *messageFactory, VMutex *mutex)
	Constructs a message handler with a message to handle and the server in which it is running.
virtual	~VMessageHandler ()
	Virtual destructor.
virtual void	processMessage ()=0
	Processes the message.
VMessagePtr	getMessage (VMessageID messageID)
	Returns a newly instantiated message, using the message factory associated with this message handler.
void	logMessageContentRecord (const VString &details, VNamedLoggerPtr logger=VNamedLoggerPtr()) const
	Logs (at the appropriate log level) the supplied information about the message being handled.
void	logMessageContentFields (const VString &details, VNamedLoggerPtr logger=VNamedLoggerPtr()) const
	Logs (at the appropriate log level) the supplied information about the message being handled.
void	logMessageDetailsFields (const VString &details, VNamedLoggerPtr logger=VNamedLoggerPtr()) const
	Similar to logMessageContentFields, but for a lower level of messaging.
virtual void	logProcessMessageStart () const
	Logs (at the appropriate log level) the message handler name to indicate that the handler has been invoked or has ended.
virtual void	logProcessMessageEnd () const
	Logs (at the appropriate log level) the message handler name to indicate that the handler has been invoked or has ended.
Static Public Member Functions
static VMessageHandler *	get (VMessagePtr m, VServer *server, VClientSessionPtr session, VSocketThread *thread)
	Returns a message handler suitable for handling the specified message.
static void	registerHandlerFactory (VMessageID messageID, VMessageHandlerFactory *factory)
	Registers a message handler factory for a particular message ID.
Protected Member Functions
void	_logDetailedDispatch (const VString &dispatchInfo) const
	Logs (at the appropriate log level) highly detailed status info about message handling dispatch.
void	_logMessageContentRecord (const VString &contentInfo) const
	Logs (at the appropriate log level) simple content info for a message that has been received or will be sent.
VNamedLoggerPtr	_getMessageContentRecordLogger () const
	Returns the logger for message content, or NULL if that level is not enabled.
void	_logMessageContentFields (const VString &contentInfo) const
	Logs (at the appropriate log level) simple content info for a message that has been received or will be sent.
VNamedLoggerPtr	_getMessageContentFieldsLogger () const
	Returns the logger for message fields, or NULL if that level is not enabled.
void	_logMessageContentHexDump (const VString &info, const Vu8 *buffer, Vs64 length) const
	Logs (at the appropriate log level) full hex dump content info for a message that has been received or will be sent.
Protected Attributes
VString	mName
	The name to identify this handler type in log output.
VString	mLoggerName
	The logger name which we will use when emitting log output.
VMessagePtr	mMessage
	The message this handler is to process.
VServer *	mServer
	The server in which we are running.
VClientSessionPtr	mSession
	The session reference for which we are running, which holds NULL if n/a.
VSocketThread *	mThread
	The thread in which we are running.
const VMessageFactory *	mMessageFactory
	Factory for instantiating new messages this handler wants to send.
VInstant	mStartTime
	The time at which this handler was instantiated (message receipt). MUST BE DECLARED BEFORE mLocker.
VMutexLocker	mLocker
	The mutex locker for the mutex we were given.
VInstant	mUnblockTime
	The time at which this handler obtained the mLocker lock. MUST BE DECLARED AFTER mLocker.
VString	mSessionName
	The name to identify this handler's session in log output.

---

Detailed Description

VMessageHandler is the abstract base class for objects that process inbound messages from various client connections.

A VMessageHandler is constructed with a message to be processed, and the server, session, and thread in which or on behalf of which the handler is being executed. The base class constructor is supplied an optional mutex to lock, and it does so using a VMutexLocker instance variable mLocker, which subclass can choose to unlock as appropriate. If no lock is needed, the subclass can either pass NULL for the mutex in the base class constructor, or unlock the locker in the subclass constructor. The concrete subclass needs to implement the processMessage() function and do its work there to process the mMessage. Because the mutex lock is acquired in the constructor, the implementation may rely on exclusive access to the data that is protected by the lock. This also means that if the handler runs for a significant amount of time, it may need to take care to not keep the lock too long. Whether or not the handler decides to farm its long-running work out to a background task or do it locally, long-running work will have to release the lock and reacquire it periodically, or other threads will be blocked for an unacceptably long time. And if appropriate, a handler or background task should try to release the lock as soon as possible when it no longer needs it, or if it doesn't really need it in the first place.

Definition at line 52 of file vmessagehandler.h.

---

Constructor & Destructor Documentation

VMessageHandler::VMessageHandler	(	const VString &	name,
		VMessagePtr	m,
		VServer *	server,
		VClientSessionPtr	session,
		VSocketThread *	thread,
		const VMessageFactory *	messageFactory,
		VMutex *	mutex
	)

Constructs a message handler with a message to handle and the server in which it is running.

Parameters:

name	the handler's name for logger output
m	the message to process
server	the server we're running in
session	the session for the client that sent this message, or NULL if n/a
thread	the thread processing the message (used to correlate the message to a client session)
messageFactory	a factory that instantiates messages suitable for this handler when it needs to send a message (assuming all such messages are uniform; if not, messages can be instantiated explicitly); the caller owns the factory.
mutex	if not null, a mutex that will be initially locked by the constructor and unlocked by the destructor

Definition at line 44 of file vmessagehandler.cpp.

References VString::chars(), VThread::getName(), VMessage::kMessageHandlerLifecycleLevel, mLoggerName, mName, mSessionName, mThread, and NULL.

VMessageHandler::~VMessageHandler

(

)

[virtual]

Virtual destructor.

VMessageHandler will delete the owned message (setting mMessage to NULL will obviously circumvent this).

Definition at line 67 of file vmessagehandler.cpp.

References VString::chars(), VMessage::kMessageHandlerLifecycleLevel, mLoggerName, mMessageFactory, mName, mServer, mSessionName, mThread, and NULL.

---

Member Function Documentation

VMessageHandler * VMessageHandler::get	(	VMessagePtr	m,
		VServer *	server,
		VClientSessionPtr	session,
		VSocketThread *	thread
	)		[static]

Returns a message handler suitable for handling the specified message.

When a message is read from the network, this is what is called to find a message handler for it. The message handler should then simply be told to processMessage(), and deleted.

Parameters:

m	the message to supply to the handler
server	the server to supply to the handler
session	the session for the client that sent this message, or NULL if n/a
thread	the thread processing the message (used to correlate the message to a client session)

Definition at line 19 of file vmessagehandler.cpp.

References VMessageHandlerFactory::createHandler(), and NULL.

void VMessageHandler::registerHandlerFactory	(	VMessageID	messageID,
		VMessageHandlerFactory *	factory
	)		[static]

Registers a message handler factory for a particular message ID.

When a call is made to get(), the appropriate factory function is called to create a handler for the message ID.

Definition at line 29 of file vmessagehandler.cpp.

VMessagePtr VMessageHandler::getMessage

(

VMessageID

messageID

)

Returns a newly instantiated message, using the message factory associated with this message handler.

Parameters:

messageID

value with which to init the message's message ID

Returns:

a message object

Definition at line 77 of file vmessagehandler.cpp.

References VMessageFactory::instantiateNewMessage(), and mMessageFactory.

void VMessageHandler::logMessageContentRecord	(	const VString &	details,
		VNamedLoggerPtr	logger = VNamedLoggerPtr()
	)		const

Logs (at the appropriate log level) the supplied information about the message being handled.

A message handler should call this to log the data contained in the inbound message, one whole message at a time. An optional facility here is that the caller may supplie the logger object to which the output will be written, and may obtain that object via a prior call to _getMessageContentRecordLogger(), which may return NULL. This allows the caller to: first call _getMessageContentRecordLogger() to obtain the logger object; if it's NULL (indicating the log level would emit nothing), it can avoid calling logMessageContentRecord() at all and also avoid building the log message strings; and if the logger is not NULL (indicating the log level would emit data) then it can supply the logger to logMessageContentRecord() so that this function doesn't have to keep re-finding the logger over repeated calls.

Parameters:

details	the text to be logged
logger	the logger to write to, or NULL to force the function to look up the logger

Definition at line 82 of file vmessagehandler.cpp.

References _getMessageContentRecordLogger(), and VMessage::kMessageContentRecordingLevel.

void VMessageHandler::logMessageContentFields	(	const VString &	details,
		VNamedLoggerPtr	logger = VNamedLoggerPtr()
	)		const

Logs (at the appropriate log level) the supplied information about the message being handled.

A message handler should call this to log the data contained in the inbound message, one field at a time. An optional facility here is that the caller may supply the logger object to which the output will be written, and may obtain that object via a prior call to _getMessageContentFieldsLogger(), which may return NULL. This allows the caller to: first call _getMessageContentFieldsLogger() to obtain the logger object; if it's NULL (indicating the log level would emit nothing), it can avoid calling logMessageContentFields() at all and also avoid building the log message strings; and if the logger is not NULL (indicating the log level would emit data) then it can supply the logger to logMessageContentFields() so that this function doesn't have to keep re-finding the logger over repeated calls.

Parameters:

details	the text to be logged
logger	the logger to write to, or NULL to force the function to look up the logger

Definition at line 90 of file vmessagehandler.cpp.

References _getMessageContentFieldsLogger(), and VMessage::kMessageContentFieldsLevel.

void VMessageHandler::_logDetailedDispatch

(

const VString &

dispatchInfo

)

const [protected]

Logs (at the appropriate log level) highly detailed status info about message handling dispatch.

Parameters:

dispatchInfo

the info to be logged

Definition at line 123 of file vmessagehandler.cpp.

References VMessage::kMessageHandlerDetailLevel, and mLoggerName.

void VMessageHandler::_logMessageContentRecord

(

const VString &

contentInfo

)

const [protected]

Logs (at the appropriate log level) simple content info for a message that has been received or will be sent.

You should only supply a simple form of the data, not a full hex dump (see _logContentHexDump).

Parameters:

contentInfo

the info to be logged

Definition at line 127 of file vmessagehandler.cpp.

References VMessage::kMessageContentRecordingLevel, and mLoggerName.

void VMessageHandler::_logMessageContentFields

(

const VString &

contentInfo

)

const [protected]

Logs (at the appropriate log level) simple content info for a message that has been received or will be sent.

You should only supply a simple form of the data, not a full hex dump (see _logContentHexDump).

Parameters:

contentInfo

the info to be logged

Definition at line 131 of file vmessagehandler.cpp.

References VMessage::kMessageContentFieldsLevel, and mLoggerName.

void VMessageHandler::_logMessageContentHexDump	(	const VString &	info,
		const Vu8 *	buffer,
		Vs64	length
	)		const [protected]

Logs (at the appropriate log level) full hex dump content info for a message that has been received or will be sent.

Parameters:

info	informational text to label the output
buffer	the buffer to dump in hex form
length	the length of the buffer (or how much of it to dump)

Definition at line 135 of file vmessagehandler.cpp.

References VMessage::kMessageContentHexDumpLevel, and mLoggerName.

---

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

• vmessagehandler.h
• vmessagehandler.cpp