/*!
\page oess_1_4_0__custom_type_serialization	oess_1.4.0. Ручная сериализация пользовательских типов

\section oess_1_4_0__custom_type_serialization__intro Введение

В некоторых случаях бывает необходимо сериализовать уже существующий
пользовательский тип, который не является производным от
oess_1::stdsn::serializable_t. Например, тип ACE_Date_Time, с которым
возникают сразу две сложности:
- во-первых, этот тип не производен от oess_1::stdsn::serializable_t, поэтому
его нельзя непосредственно указать в DDL в качестве типа атрибута;
- во-вторых, для представления ACE_Date_Time в ОП используется весьма
расточительная схема (каждый атрибут имеет тип long), которую хотелось бы
оптимизировать при сохранении объекта ACE_Date_Time в двоичном виде
(например, год можно хранить как oess_1::short_t, месяц, день, час, минуты
и секунды -- как oess_1::char_t).

Для преодоления данных сложностей в ObjESSty v.1.4.0 была добавлена
возможность использования ручной (custom) сериализации пользовательских
типов.

\section oess_1_4_0__custom_type_serialization__idea Идея

Для сериализации объекта
пользовательского типа во вспомогательном коде генерируется объект:
\code
oess_1::stdsn::oobj_t< User_Type > oobj( ... );
\endcode
а для десериализации:
\code
oess_1::stdsn::iobj_t< User_Type > iobj( ... );
\endcode

По умолчанию, шаблоны oess_1::stdsn::oobj_t<> и oess_1::stdsn::iobj_t<>
вызывают сгенерированные вспомогательные методы для типа User_Type. Но для
всех примитивных типов и для некоторых внутренних ObjESSty типов созданы
специализации этих шаблонов.

Идея ручной сериализации состоит в том, что пользователь может
самостоятельно реализовать специализацию шаблонов oess_1::stdsn::oobj_t<> и
oess_1::stdsn::iobj_t<> для своего типа. Естественно, что располагаться
эта специализация должна в пространстве имен oess_1::stdsn. Например:

\code
namespace Some_User_NS
{

class Some_User_Class { ... };

}

// Теперь делаем специализацию ObjESSty шаблонов для Some_User_NS::Some_User_Class.
namespace oess_1
{

namespace stdsn
{

template<>
class oobj_t< Some_User_NS::Some_User_Class >
	{
	... // Реализация.
	};

template<>
class iobj_t< Some_User_NS::Some_User_Class >
	{
	... // Реализация.
	};

}
}
\endcode

\section oess_1_4_0__custom_type_serialization__practice Ручная сериализация на практике

Явная специализация шаблонов oobj_t<> и iobj_t<> -- это не самое простое
занятие. Кроме того, эта специализация может привязать прикладной код к
текущей версии ObjESSty и, если в следующих версиях ObjESSty интерфейс oobj_t<> и iobj_t<> изменится, то предется изменять и реализацию сериализации. Что бы
избежать лишних сложностей ObjESSty предлагает использовать на практике
более простой путь.

\subsection oess_1_4_0__custom_type_serialization__practice__stream Реализация операторов сдвига в oess_1::io::*stream_t

Для начала необходимо реализовать для своего типа операторы сдвига в
oess_1::io::ostream_t и oess_1::io::istream_t. Например, вот так:
\code
inline oess_1::io::ostream_t &
operator<<( oess_1::io::ostream_t & out, const Some_User_NS::Some_User_Class & d )
	{
		... // Код по сдвигу объекта в out.
		return out;
	}

inline oess_1::io::istream_t &
operator>>( oess_1::io::istream_t & in, Some_User_NS::Some_User_Class & d )
	{
		... // Код по сдвигу объекта из in.
		return in;
	}
\endcode

Такие операторы сдвига автоматически позволяют сохранять/извлекать
объекты пользовательского типа в любой поток из oess_1::io (что может
оказаться полезным не только для stdsn-сериализации).

\subsection oess_1_4_0__custom_type_serialization__practice__specialization Использование макроса OESS_1_STDSN_SPECIALIZE_CUSTOM_TYPE

После того, как операторы сдвига в ObjESSty-потоки определены, достаточно
воспользоваться макросом OESS_1_STDSN_SPECIALIZE_CUSTOM_TYPE(). Нужно только
помнить, что использовать данный макрос нужно в глобальном пространстве
имен.

\code
OESS_1_STDSN_SPECIALIZE_CUSTOM_TYPE( Some_User_NS::Some_User_Class )
\endcode

\note Нужно помнить, что в месте использования макроса
OESS_1_STDSN_SPECIALIZE_CUSTOM_TYPE() должны быть видны операторы сдвига
в ObjESSty-потоки.

*/

