Using Blobs
This chapter will describe the use of flip::Blob with the Flip framework.
In the following, we will show the step by step construction of an hypothetic MyClass class.
This chapter will assume that your company is called ACME making the application “Product”.
Why Use a Blob ?
The Flip framework offers a flip::Blob class that holds arbitrary opaque data.
When deciding whether to use an flip::Array of objects representing bytes or a Blob , the following features should be considered :
- an flip::Array holding more than 10000 value will have an impact on performance, where as a 10K bytes flip::Blob is quite a small blob
- accessing individual elements in the array is possible, whereas a change of the blob will send the whole blob. In particular this ensure that blobs cannot be concurrently merged, which would occur with arrays
The flip::Blob class also offers character string facilities : it can be assigned a std::string and can be casted to a std::string using the method to_string
ListingUsing a flip::Blob to hold a character string
std::string str ("Some text"); |
_my_blob.set (str); |
std::string text = _my_blob.to_string (); |
WARNING:The to_string method returns the string by value, not by reference.
Encoders
The Flip framework offers a number of encoders for Blob . The encoders do not modify the Blob itself, but only how it is encoded for the back-end document writer.
Encoder are used in the following use cases :
- The data is opaque (non human readable) and can get quite voluminous
- The data is not opaque and shall be displayed in the document in a human readable format if possible
For the first case, Flip supports compression through the zlib deflate compression through Encoder_DEFLATE .
For the second case, Flip supports a limited number of human readable format :
- Encoder_ESCAPED_ASCII is usually used to encode strings in a format which match string literals representation. In particular carriage return, line feed and tabular characters are mapped to \r , \n and \t respectively.
- Encoder_HEXADECIMAL is usually when representing the data as hexadecimal yield better readability.
Inline Property
The inline property available through set_inline do not modify the Blob itself, but only how it is encoded for the back-end document writer.
When inlining is not used (which is the default), the blob member is written in a two stage in the document. The attribute description just mark the reference number of the blob, and the blob is written later. The following listing illutrates this :
ListingNon-inlined blob
57 obj << |
/ClassName ohm.studio.ClientData |
/AttributeName _user_name /Type /Blob /Ref 58 |
>> |
endobj |
58 obj << |
/Blob |
/Length 6 |
/Filter [ /EscapedAsciiDecode ] |
>> |
stream |
raphael |
endstream |
endobj |
When inlining is used (by the way of set_inline , the blob member is written directly on the attribute line. The following listing illutrates this :
ListingInlined blob
57 obj << |
/ClassName ohm.studio.ClientData |
/AttributeName _user_name /Type /Blob /Inline /Length 6 /Filter [ /EscapedAsciiDecode ] raphael |
>> |
endobj |
In particular for the Encoder_ESCAPED_ASCII and Encoder_HEXADECIMAL encoders, this can lead to better overall readibility, as well as a substantial smaller file size.