Using Jackson with Smile format
Starting with Jackson 1.6 (see Project Smile), it is possible to read and write Smile encoded data, identical to how JSON encoded data is handled.
Simple usage
This is achieved simply by using SmileFactory for creating parser and generator instances instead of standard JsonFactory:
1 ObjectMapper mapper = new ObjectMapper(new SmileFactory());
2 // now 'mapper' will read and write Smile-encoded data instead of JSON!
and that should be the only change you need.
Configuration
SmileFactory exposes settings for fine-tuning way Smile encoding is used, by additional SmileParser and SmileGenerator features. Both are enabled/disabled either through SmileFactory.configure() method, or directly with SmileParser.enable() / SmileGenerator.enable (and related methods)
SmileParser.Feature
REQUIRE_HEADER (default: false): Whether Smile header is mandatory or not; if disabled, will accept optional header; if enabled, will throw an exception if no header is found. If header is not required and not found, default settings will apply.
SmileGenerator.Feature
CHECK_SHARED_NAMES (default: true): Whether generator should check for repeated names, and use a compact back-reference instead of full name. Enabling this feature reduces encoded data size when property names are repeated, and can make parsing faster; it can also add overhead for writing due to additional checks needed.
CHECK_SHARED_STRING_VALUES (default: false): Whether generator should check for repeated String values (for short strings, byte length of 64 or less) -- if enabled, can use numeric back-references instead of embedding String value. Enabling this feature reduces encoded data size when there are repeated String values, and can make parsing faster; it can also add overhead for writing due to additional checks needed.
ENCODE_BINARY_AS_7BIT (default: true): Whether binary data is encoded with 7-bits per byte (to avoid using certain high-order bytes that can be used for framing); or as straight bytes. If enabled, encoding is done using 8 output bytes to encode 7 input bytes; if disabled, bytes are embedded as is. The reason for using encoding (which takes 14% more space and adds processing overhead) is to avoid using certain high-order bytes which can be used as external frame markers (by code that does not need to understand Smile encoding). If such avoidance is not needed, use of encoding does not make sense.
WRITE_END_MARKER (default: false): Whether an end marker (byte 0xFF) is to be written after end of logical document or not. If enabled, such byte is written, and can be used for framing purposes (and/or as replacement for header marker to indicate logical document boundary in physical stream); if disabled, no marker is written.
WRITE_HEADER (default: ) Whether to write 4-byte header sequence when starting output or not. Header includes 3 marker bytes ("magic cookie") for format identification purposes; a 4-bit version marker, and 3 configuration bits (shared name backrefs allowed; shared string value back refs allowed; non-encoded binary allowed). Use of header is optional but highly recommended; writing of header can be disabled to save 4 bytes of overhead for small messages. If header is missing, it is not possible to use non-default settings for back-references or non-encoded binary data.
Enum Constant Summary
- Whether generator should check if it can "share" field names during generating content or not. Whether generator should check if it can "share" short (at most 64 bytes encoded) String value during generating content or not. Whether to use simple 7-bit per byte encoding for binary content when output.
Whether write byte marker that signifies end of logical content segment (SmileConstants.BYTE_MARKER_END_OF_CONTENT) when SmileGenerator.close() is called or not.