Jackson Data-binding: Did I mention it can do YAML as well?
Note: as useful earlier articles, consider reading "Jackson 2.0: CSV-compatible as well" and "Jackson 2.0: now with XML, too!"
1. Inspiration
Before jumping into the actual beef -- the new module -- I want to mention my inspiration for this extension: the Greatest New Thing to hit Java World Since JAX-RS called DropWizard.
For those who have not yet tried it out and are unaware of its Kung-Fu Panda like Awesomeness, please go and check it out. You won't be disappointed.
DropWizard is a sort of mini-framework that combines great Java
libraries (I may be biased, as it does use Jackson), starting with
trusty JAX-RS/Jetty8 combination, building with Jackson for JSON, jDBI
for DB/JDBC/SQL, Java Validation API (impl from Hibernate project) for
data validation, and logback for logging; adding bit of Jersey-client
for client-building and optional FreeMarker plug-in for UI, all bundled
up in a nice, modular and easily understandable packet.
Most
importantly, it "Just Works" and comes with intuitive configuration and
bootstrapping system. It also builds easily into a single deployable jar
file that contains all the code you need, with just a bit of Maven
setup; all of which is well documented. Oh, and the documentation is
very accessible, accurate and up-to-date. All in all, a very rare
combination of things -- and something that would give RoR and other
"easier than Java" frameworks good run for their money, if hipsters ever
decided to check out the best that Java has to offer.
The most relevant part here is the configuration system. Configuration can use either basic JSON or full YAML. And as I mentioned earlier, I am beginning to appreciate YAML for configuring things.
1.1. The Specific inspirational nugget: YAML converter
The way DropWizard uses YAML is to parse it using SnakeYAML library, then convert resulting document into JSON tree and then using Jackson for data binding. This is useful since it allows one to use full power of Jackson configuration including annotations and polymorphic type handling.
But this got me thinking -- given that the whole converter implementation about dozen lines or so (to work to degree needed for configs), wouldn't it make sense to add "full support" for YAML into Jackson family of plug-ins?
I thought it would.
2. And Then There Was One More Backend for Jackson
Turns out that implementation was, indeed, quite easy. I was able to improve certain things -- for example, module can use lower level API to keep performance bit better; and output side also works, not just reader -- but in a way, there isn't all that much to do since all module has to do is to convert YAML events into JSON events, and maybe help with some conversions.
Some of more advanced things include:
- Format auto-detection works, thanks to "---" document prefix (that generator also produces by default)
- Although YAML itself exposes all scalars as text (unless type hints are enabled, which adds more noise in content), module uses heuristics to make parser implementation bit more natural; so although data-binding can also coerce types, this should usually not be needed
- Configuration includes settings to change output style, to allow use of more aesthetically pleasing output (for those who prefer "wiki look", for example)
At this point, functionality has been tested with a broad if shallow set of unit tests; but because data-binding used is 100% same as with JSON, testing is actually sufficient to use module for some work.
3. Usage? So boring I tell you
Oh. And you might be interested in knowing how to use the module. This is the boring part, since.... there isn't really much to it.
You just use "YAMLFactory" wherever you would normally use "JsonFactory"; and then under the hood you get "YAMLParser" and "YAMLGenerator" instances, instead of JSON equivalents. And then you either use parser/generator directly, or, more commonly, construct an "ObjectMapper" with "YAMLFactory" like so (code snippet itself is from test "SimpleParseTest.java")
ObjectMapper mapper = new ObjectMapper(new YAMLFactory());
User user = mapper.readValue("firstName: Billy\n"
+"lastName: Baggins\n"
+"gender: MALE\n"
+"userImage: AQIDBAY=",
User.class);
and to get the functionality itself, Maven dependency is:
<dependency> <groupId>com.fasterxml.jackson.dataformat</groupId> <artifactId>jackson-dataformat-yaml</artifactId> <version>2.0.0</version> </dependency>
4. That's all Folks -- until you give us some Feedback!
That's it for now. I hope some of you will try out this new backend, and help us further make Jackson 2.0 the "Universal Java Data Processor"
