Protocols::Generics::GenericSession Class Reference

#include <GenericSession.h> [code]

Inherits Protocols::Generics::Session, and Protocols::Generics::TransportStatus.

Inherited by Protocols::BitTorrent::Transfers::PacketSession.

Inheritance diagram for Protocols::Generics::GenericSession:

[legend]Collaboration diagram for Protocols::Generics::GenericSession:

[legend]List of all members.

Detailed Description

A generic Data exchange Session over a Transport.

GenericSession implements the Session interface. It is a generic component that provides a generic solution for Data exchange over an already connected Transport.

A DataSerializer helper object passed by reference to the ctor is used to read and write packets from and to Transport. DataSerializer will know how to convert C++ representation of protocol data from and to a raw bytes representation,

A DataQueue helper object passed by reference to the ctor is used to queue outgoing Data objects (protocol data) if the Transport's buffer gets full. Different DataQueue objects could implement different queueing policies and even flow control algorithms.

A SessionStatus object passed by reference to the ctor will get different notifications from the GenericSession object.

Note:: A concrete protocol could implement a Session object that derives from and extends GenericSession. The derived class could declare a DataSerializer and a DataQueue objects of the correct type as members and pass references to them when initializing the base class GenericSession:

Todo:: Do test the example and make sure it compiles and works!

    class ConcreteSession : public GenericSession, public SessionStatus
    {
    public:
        ConcreteSession (Transport &t)
        : GenericSession (t, serializer, queue, this),
          serializer (...), queue (...)
        {}

        // SessionStatus interface implementation:
        ...

    private:
        ConcreteSerializer  serializer;
        ConcreteQueue       queue;
    };

Note:: The proposed solution is quite flexible becaus it allows ConcreteSession to react on the status notifications of GenericSession and even use extra functionality from ConcreteSerializer and ConcreteQueue (e.g. checking how full the buffer actually is). ConcreteSession could even provide a more verbose status notifications interface to its users.
Multiple inheritance (no matter whether only from abstract base classes) results in different addresses when the same object is cast (statically and dynamically) to the abstract base classes.

Todo:: Another approach (that would also be easier to test and thus probably better!) would be to have a GenericSession object as a member and just delegate the Session functions to GenericSession. Update the example and description to it eventually!

See also:: Testing::GenericSessionTest

Definition at line 99 of file GenericSession.h.

Public Member Functions

GenericSession (Transport *, DataSerializer *, DataQueue *, SessionStatus *)

Constructs a GenericSession object.

~GenericSession ()

Destroys a GenericSession object.

void open ()

Opens the session and start reading buffered data from Transport.

void send (const Data &)

Sends a serialized Data object over the underlying Transport.

void close ()

Closes the session by flusing the queue and disconnecting the Transport.

void abort ()

Aborts the session by stopping data exchange and aborting the Transport.

void transportConnected (Transport *)

Implements part of the TransportSession interface.

void transportReadyRead (Transport *)

Tries to read any Data objects buffered in Transport.

void transportReadyWrite (Transport *)

Tries to write to Transport as much queued Data objects as possible.

void transportDisconnected (Transport *)

Handles the TransportStatus notification and closes the session.

Private Types

enum State {
  Closed,
  Opened,
  Closing
}

Private Member Functions

CALITKO_TESTABLE GenericSession (const GenericSession &)

GenericSession & operator= (const GenericSession &)

Private Attributes

Transport * transport

DataSerializer * dataSerializer

DataQueue * dataQueue

SessionStatus * status

State state

Member Enumeration Documentation

enum Protocols::Generics::GenericSession::State [private]

Enumerator:

Closed

Opened

Closing

Definition at line 125 of file GenericSession.h.

Constructor & Destructor Documentation

CALITKO_TESTABLE Protocols::Generics::GenericSession::GenericSession ( const GenericSession & ) [private]

GenericSession::GenericSession ( Transport * transport_,

DataSerializer * serializer_,

DataQueue * queue_,

SessionStatus * status_

)

Constructs a GenericSession object.

Parameters:

transport_ is the already connected Transport to use.

serializer_ is the Data serialization helper object to use.

queue_ is the object implementing the Data queuing policy.

status_ is the object that should receive status notifications.

Precondition:
transport_ must already be connected.
None of the pointers is allowed to be 0.

Todo:
The underscore coding convention! Having underscore suffix in member variable names will make the implementation of the class ugly. Having the underscore suffix in the parameter names would make the docs ugly. If the "param" names are different than the actual parameter names Doxygen will print a warning. What to do!?

Definition at line 43 of file GenericSession.cpp.

GenericSession::~GenericSession ( )

Destroys a GenericSession object.

Definition at line 58 of file GenericSession.cpp.

Member Function Documentation

void GenericSession::abort ( ) [virtual]

Aborts the session by stopping data exchange and aborting the Transport.

Todo:
check whether Transport::abort() sends any status notifications. Make the behaviour of abort consistent for all layers (e.g. Session, ClientHttpSession, etc.)

Implements Protocols::Generics::Session.
Definition at line 100 of file GenericSession.cpp.

void GenericSession::close ( ) [virtual]

Closes the session by flusing the queue and disconnecting the Transport.
The session enters the Closing State - it will not allow any more Data to be sent using send(). It will wait that all Data already queued is written and will then disconnect the transport.
Implements Protocols::Generics::Session.
Definition at line 115 of file GenericSession.cpp.

void GenericSession::open ( ) [virtual]

Opens the session and start reading buffered data from Transport.
The session is opened first (internal state is changed) and then it will be attempted to read any Data that has already been buffered in the underlying transport->
Implements Protocols::Generics::Session.
Definition at line 68 of file GenericSession.cpp.

GenericSession& Protocols::Generics::GenericSession::operator= ( const GenericSession & ) [private]

void GenericSession::send ( const Data & data ) [virtual]

Sends a serialized Data object over the underlying Transport.

Parameters:

data is the Data object that should be serialized and written to the underlying transport->

The function will queue data and will try to write it to the underlying transport-> If that works, data will be removed from the queue, otherwise it will be queued until it is written. What happens if the queue is full depends on the queueing policy implemented by the DataQueue object passed to the ctor.
Implements Protocols::Generics::Session.
Definition at line 86 of file GenericSession.cpp.

void GenericSession::transportConnected ( Transport * ) [virtual]

Implements part of the TransportSession interface.

Precondition:
false
This function must never be called! GenericSession assumes that the Transport is already connected.
Implements Protocols::Generics::TransportStatus.
Definition at line 131 of file GenericSession.cpp.

void GenericSession::transportDisconnected ( Transport * ) [virtual]

Handles the TransportStatus notification and closes the session.

Implements Protocols::Generics::TransportStatus.
Definition at line 161 of file GenericSession.cpp.

void GenericSession::transportReadyRead ( Transport * ) [virtual]

Tries to read any Data objects buffered in Transport.

Implements Protocols::Generics::TransportStatus.
Definition at line 137 of file GenericSession.cpp.

void GenericSession::transportReadyWrite ( Transport * ) [virtual]

Tries to write to Transport as much queued Data objects as possible.

Implements Protocols::Generics::TransportStatus.
Definition at line 148 of file GenericSession.cpp.

Member Data Documentation

DataQueue* Protocols::Generics::GenericSession::dataQueue [private]

Definition at line 134 of file GenericSession.h.

DataSerializer* Protocols::Generics::GenericSession::dataSerializer [private]

Definition at line 133 of file GenericSession.h.

State Protocols::Generics::GenericSession::state [private]

Definition at line 136 of file GenericSession.h.

SessionStatus* Protocols::Generics::GenericSession::status [private]

Reimplemented in Protocols::BitTorrent::Transfers::PacketSession.
Definition at line 135 of file GenericSession.h.

Transport* Protocols::Generics::GenericSession::transport [private]

Reimplemented in Protocols::BitTorrent::Transfers::PacketSession.
Definition at line 132 of file GenericSession.h.

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

Protocols/Generics/GenericSession.h
Protocols/Generics/GenericSession.cpp


Public Member Functions
	GenericSession (Transport , DataSerializer , DataQueue , SessionStatus )
	Constructs a GenericSession object.
	~GenericSession ()
	Destroys a GenericSession object.
void	open ()
	Opens the session and start reading buffered data from Transport.
void	send (const Data &)
	Sends a serialized Data object over the underlying Transport.
void	close ()
	Closes the session by flusing the queue and disconnecting the Transport.
void	abort ()
	Aborts the session by stopping data exchange and aborting the Transport.
void	transportConnected (Transport *)
	Implements part of the TransportSession interface.
void	transportReadyRead (Transport *)
	Tries to read any Data objects buffered in Transport.
void	transportReadyWrite (Transport *)
	Tries to write to Transport as much queued Data objects as possible.
void	transportDisconnected (Transport *)
	Handles the TransportStatus notification and closes the session.
Private Types
enum	State { Closed, Opened, Closing }
Private Member Functions
CALITKO_TESTABLE	GenericSession (const GenericSession &)
GenericSession &	operator= (const GenericSession &)
Private Attributes
Transport *	transport
DataSerializer *	dataSerializer
DataQueue *	dataQueue
SessionStatus *	status
State	state