# Data Transfer Object (DTO)

DTO is any object of the class which extends oatpp::DTO. It is a special object which can be Serialized and Deserialized with the help of oatpp::data::mapping::ObjectMapper.

DTO objects are generated within DTO-code-gen section. DTO code generation section must begin with

#include OATPP_CODEGEN_BEGIN(DTO) and must be closed with #include OATPP_CODEGEN_END(DTO) . Do not forget to close code generation section in order to avoid macro conflicts later in the code!

# include "oatpp/core/Types.hpp" # include "oatpp/core/macro/codegen.hpp" # include OATPP_CODEGEN_BEGIN(DTO) class User : public oatpp :: DTO { DTO_INIT ( User , DTO ) DTO_FIELD ( String , name ) ; DTO_FIELD ( Int32 , age ) ; } ; # include OATPP_CODEGEN_END(DTO)

# Field Name Qualifier

DTO_FIELD ( String , name , "user-name" ) ;

# Default Value

By default all values are set to nullptr . You can override default values by assigning values to DTO fields.

DTO_FIELD ( String , name ) = "Ivan" ;

# Additional Field Info

DTO_FIELD_INFO ( name ) { info -> description = "user first name" ; } DTO_FIELD ( String , name ) = "Ivan" ;

# Declare Field As Object

DTO_FIELD ( Object < User > , user ) ;

# Declare Field As List

List of primitives:

DTO_FIELD ( List < Int32 > , colors ) ;

List of Objects:

DTO_FIELD ( List < Object < MyObject >> , colors ) ;

# Declare Field As Map

Map String --> Int32 :

DTO_FIELD ( Fields < Int32 > , colors ) ;

Map String --> Object :

DTO_FIELD ( Fields < Object < MyObject >> , colors ) ;

# Core Types

Types defined in oatpp/core/Types.hpp .

Type Underlying Type Default Value Int8 v_int8 nullptr UInt8 v_uint8 nullptr Int16 v_int16 nullptr UInt16 v_uint16 nullptr Int32 v_int32 nullptr UInt32 v_uint32 nullptr Int64 v_int64 nullptr UInt64 v_uint64 nullptr Float32 v_float32 nullptr Float64 v_float64 nullptr Boolean bool nullptr

oatpp :: Int32 a = 32 ; v_int32 va = * a ;

Type Underlying Collection Default Value Vector<T> std::vector<T> nullptr List<T> std::list<T> nullptr UnorderedSet<T> std::unordered_set<T> nullptr Fields<T> std::list<std::pair<Key, Value>> nullptr UnorderedFields<T> std::unordered_map<Key, Value> nullptr

oatpp :: Vector < oatpp :: String > porridges = { "Owsianka" , "Stirabout" , "Zabkása" } ; for ( auto & porridge : * porridges ) { . . . }

# Special Types

Type Underlying Type Default Value String oatpp::base::StrBuffer nullptr Object<T> class which extends oatpp::DTO nullptr Enum<T> enum declared via ENUM nullptr Any any other mapping-enabled type nullptr

oatpp :: Object < MyDto > dto = MyDto :: createShared ( ) ; oatpp :: Any any = dto ; . . . auto dto = any . retrieve < oatpp :: Object < MyDto >> ( ) ;

# Custom Mapping-Enabled Types

Please note that one can define a custom type to be used in custom ObjectMapper.

This section is not documented yet. For information about custom object mapping contact us in dev-chat

# Serialize / Deserialize

# Define DTO

# include "oatpp/core/Types.hpp" # include "oatpp/core/macro/codegen.hpp" # include OATPP_CODEGEN_BEGIN(DTO) class User : public oatpp :: DTO { DTO_INIT ( User , DTO ) DTO_FIELD ( String , name , "First-Name" ) ; DTO_FIELD ( String , surname , "Family-Name" ) ; DTO_FIELD ( Int32 , age ) ; DTO_FIELD ( Fields < List < Object < User >> > , familyMembers ) ; DTO_FIELD ( Fields < String > , additionalNotes ) ; } ; # include OATPP_CODEGEN_END(DTO)

# Create object and set fields

auto user = User :: createShared ( ) ; user -> name = "Ivan" ; user -> surname = "Ovsyanochka" ; user -> age = 24 ; user -> familyMembers = { } ; user -> additionalNotes = { } ; auto brother = User :: createShared ( ) ; brother -> name = "Yuriy" ; brother -> surname = "Ovsyanochka" ; brother -> age = 30 ; auto sister = User :: createShared ( ) ; sister -> name = "Kate" ; sister -> surname = "Ovsyanochka" ; sister -> age = 20 ; oatpp :: List < oatpp :: Object < User >> siblings = { brother , sister } ; user -> familyMembers -> insert ( { "siblings" , siblings } ) ; user -> additionalNotes -> insert ( { "Education" , "Master of Computer Science" } ) ;

# Create JSON object mapper

# include "oatpp/parser/json/mapping/ObjectMapper.hpp" . . . auto jsonObjectMapper = oatpp :: parser :: json :: mapping :: ObjectMapper :: createShared ( ) ;

# Serialize user to json

oatpp :: String json = jsonObjectMapper -> writeToString ( user ) ; OATPP_LOGD ( "json" , "value='%s'" , json -> c_str ( ) ) ;

output:

{ "First-Name" : "Ivan" , "Family-Name" : "Ovsyanochka" , "age" : 24 , "familyMembers" : { "siblings" : [ { "First-Name" : "Yuriy" , "Family-Name" : "Ovsyanochka" , "age" : 30 , "familyMembers" : null , "additionalNotes" : null } , { "First-Name" : "Kate" , "Family-Name" : "Ovsyanochka" , "age" : 20 , "familyMembers" : null , "additionalNotes" : null } ] } , "additionalNotes" : { "Education" : "Master of Computer Science" } }

Please note: example of above output is beautified with oatpp::parser::json::Beautifier.

# Deserizalize from String

auto cloneOfUser = jsonObjectMapper -> readFromString < oatpp :: Object < User >> ( json ) ;

# Use JSON Beautifier

Without the use of beautifier the json serializer output will contain no spaces nor newline character:

{ "First-Name" : "Ivan" , "Family-Name" : "Ovsyanochka" , "age" : 24 ...

In order to beautify json output set useBeautifier = true in serializer config:

auto config = oatpp :: parser :: json :: mapping :: Serializer :: Config :: createShared ( ) ; config -> useBeautifier = true ; auto jsonObjectMapper = oatpp :: parser :: json :: mapping :: ObjectMapper :: createShared ( config ) ;

More about json object mapper configuration see:

# Examples of code

https://github.com/oatpp/oatpp-consul/blob/master/src/oatpp-consul/rest/DTOs.hpp