acl/lib_acl_cpp/include/acl_cpp/session/session.hpp

#pragma once
#include "../acl_cpp_define.hpp"
#include <map>
#include "../stdlib/dbuf_pool.hpp"
#include "../stdlib/string.hpp"

#ifndef ACL_CLIENT_ONLY

namespace acl {

// 用来存储属性值的缓冲区对象定义，这主要是为了兼容属性值
// 可以为二进制的情形而增加的结构类型
typedef enum
{
	TODO_NUL,
	TODO_SET,
	TODO_DEL
} todo_t;

class ACL_CPP_API session_string : public string
{
public:
	session_string(size_t n = 64) : string(n), todo_(TODO_NUL) {}
	session_string(const session_string& ss)
		: string(ss)
	{
		todo_ = ss.todo_;
	}
	session_string(const string& s) : string(s), todo_(TODO_NUL) {}
	session_string(const char* s) : string(s), todo_(TODO_NUL) {}
	~session_string() {}
	todo_t todo_;
};

/**
 * session 类，该类使用 memcached 存储 session 数据
 */
class ACL_CPP_API session : public dbuf_obj
{
public:
	/**
	 * 当构造函数的参数 sid 非空时，则该 session 对象使用该
	 * sid；否则内部会自动生成一个 sid，用户应该通过 get_sid()
	 * 获得这个自动生成的 sid 以便于每次查询该 sid 对应的数据
	 * @param ttl {time_t} 指定 session 的生存周期(秒)
	 * @param sid {const char*} 非空时，则 session 的 sid 使
	 *  该值，否则内部会产生一个随机的 session sid，该随机的
	 *  sid 可以通过调用 get_sid() 获得；当然在使用过程中，用户
	 *  也可以通过 set_sid() 修改本对象的 session sid；
	 *  此外，如果该 sid 为空，则如果用户查查找某个 sid 对应的
	 *  数据，则用户必须先调用 set_sid()
	 */
	session(time_t ttl = 0, const char* sid = NULL);
	virtual ~session(void);
	
	/**
	 * 重置内部状态，清理掉一些临时数据
	 */
	void reset(void);

	/**
	 * 获得本 session 对象的唯一 ID 标识
	 * @return {const char*} 非空
	 */
	virtual const char* get_sid(void) const
	{
		return sid_.c_str();
	}

	/**
	 * 设置本 session 对象的唯一 ID 标识
	 * @param sid {const char*} 非空
	 * 注：调用本函数后，会自动清除之前的中间缓存数据
	 */
	void set_sid(const char* sid);

	/**
	 * 当调用 session 类的 set/set_ttl 时，如果最后一个参数 delay 为 true，
	 * 则必须通过调用本函数将数据真正进行更新
	 * @return {bool} 数据更新是否成功
	 */
	virtual bool flush();

	/**
	 * 向 session 中添加新的字符串属性，同时设置该
	 * session 的过期时间间隔(秒)
	 * @param name {const char*} session 名，非空
	 * @param value {const char*} session 值，非空
	 * @return {bool} 返回 false 表示出错
	 */
	virtual bool set(const char* name, const char* value);

	/**
	 * 向 session 中添加新的属性对象并设置该 session 的过期时间间隔(秒)，
	 * @param name {const char*} session 属性名，非空
	 * @param value {const char*} session 属性值，非空
	 * @param len {size_t} value 值长度
	 * @return {bool} 返回 false 表示出错
	 */
	virtual bool set(const char* name, const void* value, size_t len);

	/**
	 * 延迟向 session 中添加新的属性对象并设置该 session 的过期时间间隔(秒)，
	 * 当用户调用了 session::flush 后再进行数据更新， 这样可以提高传输效率
	 * @param name {const char*} session 属性名，非空
	 * @param value {const char*} session 属性值，非空
	 * @param len {size_t} value 值长度
	 * @return {bool} 返回 false 表示出错
	 */
	virtual bool set_delay(const char* name, const void* value, size_t len);
	
	/**
	 * 从 session 中取得字符串类型属性值
	 * @param name {const char*} session 属性名，非空
	 * @return {const char*} session 属性值，返回的指针地址永远非空，用户
	 *  可以通过判断返回的是否是空串(即: "\0")来判断出错或不存在
	 *  注：该函数返回非空数据后，用户应该立刻保留此返回值，因为下次
	 *      的其它函数调用可能会清除该临时返回数据
	 */
	const char* get(const char* name);

	/**
	 * 从 session 中取得二进制数据类型的属性值
	 * @param name {const char*} session 属性名，非空
	 * @return {const session_string*} session 属性值，返回空时
	 *  表示出错或不存在
	 *  注：该函数返回非空数据后，用户应该立刻保留此返回值，因为下次
	 *      的其它函数调用可能会清除该临时返回数据
	 */
	virtual const session_string* get_buf(const char* name);

	/**
	 * 从 session 中删除指定属性值，当所有的变量都删除
	 * 时会将整个对象从 memcached 中删除
	 * @param name {const char*} session 属性名，非空
	 * @return {bool} true 表示成功(含不存在情况)，false 表示删除失败
	 *  注：当采用延迟方式删除某个属性时，则延迟发送更新指令到后端的
	 *  缓存服务器，当用户调用了 session::flush 后再进行数据更新，这
	 *  样可以提高传输效率；否则，则立刻更新数据
	 */
	virtual bool del_delay(const char* name);
	virtual bool del(const char* name);

	/**
	 * 重新设置 session 在缓存服务器上的缓存时间
	 * @param ttl {time_t} 生存周期(秒)
	 * @param delay {bool} 当为 true 时，则延迟发送更新指令到后端的
	 *  缓存服务器，当用户调用了 session::flush 后再进行数据更新，这
	 *  样可以提高传输效率；当为 false 时，则立刻更新数据
	 * @return {bool} 设置是否成功
	 */
	bool set_ttl(time_t ttl, bool delay);

	/**
	 * 获得本 session 对象中记录的 session 生存周期；该值有可能
	 * 与真正存储在缓存服务器的时间不一致，因为有可能其它的实例
	 * 重新设置了 session 在缓存服务器上的生存周期
	 * @return {time_t}
	 */
	time_t get_ttl(void) const
	{
		return ttl_;
	}

	/**
	 * 使 session 从服务端的缓存中删除即使 session 失效
	 * @return {bool} 是否使 session 失效
	 */
	virtual bool remove(void) = 0;

	/**
	 * 从后端缓存中获得对应 sid 的属性对象集合
	 * @param attrs {std::map<string, session_string>&}
	 * @return {bool}
	 */
	virtual bool get_attrs(std::map<string, session_string>& attrs) = 0;

	/**
	 * 从后端缓存中获得对应 sid 的指定属性集合
	 * @param names {const std::vector<string>&} 属性名集合
	 * @param values {std::vector<session_string>&} 存储对应的属性值结果集
	 * @return {bool} 操作是否成功
	 */
	virtual bool get_attrs(const std::vector<string>& names,
		std::vector<session_string>& values);

	/**
	 * 向后端缓存写入对应 sid 的属性对象集合
	 * @param attrs {std::map<string, session_string>&}
	 * @return {bool}
	 */
	virtual bool set_attrs(const std::map<string, session_string>& attrs) = 0;

protected:
	// 设置对应 sid 数据的过期时间
	virtual bool set_timeout(time_t ttl) = 0;

protected:
	// 将 session 数据序列化
	static void serialize(const std::map<string, session_string>& attrs,
		string& out);

	// 将 session 数据反序列化
	static void deserialize(string& buf,
		std::map<string, session_string>& attrs);

	// 清空 session 属性集合
	static void attrs_clear(std::map<string, session_string>& attrs);

protected:
	session_string sid_;
	time_t ttl_;

	// 该变量主要用在 set_ttl 函数中，如果推测该 sid_ 只是新产生的
	// 且还没有在后端 cache 服务端存储，则 set_ttl 不会立即更新后端
	// 的 cache 服务器
	bool sid_saved_;
	bool dirty_;
	std::map<string, session_string> attrs_;
	std::map<string, session_string> attrs_cache_;
};

} // namespace acl

#endif // ACL_CLIENT_ONLY