Poco::OSP::Web

class WebSession

Library: OSP/Web
Package: Web
Header: Poco/OSP/Web/WebSession.h

Description

A WebSession is used for tracking users between different HTTP(S) requests. WebSession objects are managed by a session manager (usually, an implementation of the WebSessionService).

The WebSession can also be used to store arbitrary data (attributes) in the form of key-value pairs between different requests. Poco::Any is used for storing values, so practically any object can be attached to a session.

A WebSession has a time out. If a WebSession instance is not accessed for a given time, it will be destroyed by the session manager.

Note that the iterator-based access methods (find(), begin(), end()) are not thread-safe.

When a new session is created, the session manager will generate a CSRF synchronizer token, which can be used in forms to prevent Cross-Site Request Forgery (CSRF) attacks. The name of the property is "#csrfToken". It can also be obtained by calling the csrfToken() member function.

Member Summary

Member Functions: access, accessImpl, begin, clear, clearImpl, clientAddress, created, csrfToken, end, erase, find, get, getExpiration, getValue, has, id, onBundleStopping, set, setValue, timeout, updateVersion, version

Types

Attributes

typedef std::map < std::string, Poco::Any > Attributes;

Ptr

typedef Poco::SharedPtr < WebSession > Ptr;

Constructors

WebSession

WebSession(
    const std::string & id,
    const std::string & csrfToken,
    Poco::Int64 version,
    int timeoutSeconds,
    const Poco::Net::IPAddress & clientAddress,
    Poco::AutoPtr < WebSessionStore > pStore,
    BundleContext::Ptr pContext
);

Creates a new WebSession with the given ID and time out.

WebSession

WebSession(
    const std::string & id,
    Poco::Int64 version,
    int timeoutSeconds,
    const Poco::Net::IPAddress & clientAddress,
    Poco::AutoPtr < WebSessionStore > pStore,
    BundleContext::Ptr pContext,
    Poco::Timestamp created,
    const Attributes & attrs
);

Creates a new WebSession with the given ID and time out.

Destructor

~WebSession virtual

virtual ~WebSession();

Fires a sessionEnds event and destroys the WebSession.

Member Functions

access

void access();

Updates the expiration time.

begin inline

Attributes::const_iterator begin() const;

Returns the begin iterator for attributes.

clear

void clear();

Erases all attributes.

clientAddress inline

const Poco::Net::IPAddress & clientAddress() const;

Returns the IP address of the client holding the session.

created inline

const Poco::Timestamp & created() const;

Returns the creation time of the session, i.e. the time the user sent the first request.

csrfToken inline

std::string csrfToken() const;

Returns the CSRF synchronizer token for this session.

end inline

Attributes::const_iterator end() const;

Returns the end iterator for attributes.

erase

void erase(
    const std::string & key
);

Erases an attribute value from the session.

find inline

Attributes::const_iterator find(
    const std::string & key
) const;

Searches for an attribute. Returns end() if not found.

get

const Poco::Any & get(
    const std::string & key
) const;

Returns the attribute with the given key.

Throws a Poco::NotFoundException if the attribute does not exist.

getExpiration inline

const Poco::Timestamp & getExpiration() const;

Return the time when the session will expire.

getValue inline

template < typename T > T getValue(
    const std::string & key
) const;

Convenience function that returns the attribute with the given key, casted to the desired type.

Throws a Poco::NotFoundException if the attribute does not exist. Throws a Poco::BadCastException if the cast is invalid.

getValue inline

template < typename T > T getValue(
    const std::string & key,
    T deflt
) const;

Convenience function that returns the attribute with the given key, casted to the desired type. If the attribute does not exist, the given default value is returned.

Throws a Poco::BadCastException if the cast is invalid.

has

bool has(
    const std::string & key
) const;

Returns true if and only if the session has an attribute with the given value.

id inline

const std::string & id() const;

The unique identifier of the session.

set

void set(
    const std::string & key,
    const Poco::Any & value
);

Sets/Overwrites an attribute value.

setValue inline

template < typename T > void setValue(
    const std::string & key,
    T value
);

Sets/Overwrites an attribute value.

timeout inline

int timeout() const;

Returns the timeout of the session in seconds.

version inline

Poco::Int64 version() const;

Returns the version number of the session.

accessImpl protected

void accessImpl();

Updates the expiration time.

clearImpl protected

void clearImpl();

Erases all attributes.

onBundleStopping protected

void onBundleStopping(
    const void * pSender,
    BundleEvent & ev
);

When the bundle owning the session is stopped, all attributes are cleared.

After the bundle owning the session has been stopped and its libraries have been unloaded, virtual destructors of objects stored in the session might no longer be available. Therefore all attributes must be removed while their object's destructors are still available.

updateVersion protected

void updateVersion(
    Poco::Int64 version
);

Updates the version if the new version is one higher than the current version.

Variables

CSRF_TOKEN static

static const std::string CSRF_TOKEN;

The name of the attribute storing the CSRF synchronizer token.

sessionEnds

Poco::BasicEvent < const WebSession * > sessionEnds;

Fired before the session object is destroyed.