Library: OSP/Web
Package: Web
Header: Poco/OSP/Web/WebSession.h
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.
Member Functions: access, begin, clear, clientAddress, created, end, erase, find, get, getExpiration, getValue, has, id, onBundleStopping, set, setValue, timeout
typedef std::map < std::string, Poco::Any > Attributes;
typedef Poco::SharedPtr < WebSession > Ptr;
WebSession(
const std::string & id,
int timeoutSeconds,
const Poco::Net::IPAddress & clientAddress,
BundleContext::Ptr pContext
);
Creates a new WebSession with the given ID and time out.
virtual ~WebSession();
Fires a sessionEnds event and destroys the WebSession.
void access();
Updates the expiration time.
Attributes::const_iterator begin() const;
Returns the begin iterator for attributes.
void clear();
Erases all attributes.
const Poco::Net::IPAddress & clientAddress() const;
Returns the IP address of the client holding the session.
const Poco::Timestamp & created() const;
Returns the creation time of the session, i.e. the time the user sent the first request.
Attributes::const_iterator end() const;
Returns the end iterator for attributes.
void erase(
const std::string & key
);
Erases an attribute value from the session.
Attributes::const_iterator find(
const std::string & key
) const;
Searches for an attribute. Returns end() if not found.
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.
const Poco::Timestamp & getExpiration() const;
Return the time when the session will expire.
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.
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.
bool has(
const std::string & key
) const;
Returns true if and only if the session has an attribute with the given value.
const std::string & id() const;
The unique identifier of the session.
void set(
const std::string & key,
const Poco::Any & value
);
Sets/Overwrites an attribute value.
template < typename T > void setValue(
const std::string & key,
T value
);
Sets/Overwrites an attribute value.
int timeout() const;
Returns the timeout of the session in seconds.
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.
Poco::BasicEvent < const WebSession * > sessionEnds;
Fired before the session object is destroyed.