JacksonInFiveMinutes
来源:互联网 发布:x mirage for mac 编辑:程序博客网 时间:2024/06/05 20:31
Inspired by the quality and variety of XML tooling available for the Java platform (StAX, JAXB, etc.), theJackson is a multi-purpose Java library for processingJSON. Jackson aims to be the best possible combination of fast, correct, lightweight, and ergonomic for developers.
This page gives an overview of Jackson's capabilities.
目录
- JSON Three Ways
- Examples
- Full Data Binding (POJO) Example
- "Raw" Data Binding Example
- Data Binding with Generics
- Tree Model Example
- Streaming API Example
- Streaming API Example 2: arrays
- Next Steps
JSON Three Ways
Jackson offers three alternative methods (one with two variants) for processing JSON:
Streaming API (aka "Incremental parsing/generation") reads and writes JSON content as discrete events.
org.codehaus.jackson.JsonParser reads,org.codehaus.jackson.JsonGenerator writes.
Inspired by the StAX API.
Tree Model provides a mutable in-memory tree representation of a JSON document.
org.codehaus.jackson.map.ObjectMapper can build trees; trees consist ofJsonNode nodes.
- The tree model is similar to the XML DOM.
Data Binding converts JSON to and from POJOs based either on property accessor conventions or annotations.
There are two variants: simple and full data binding
Simple data binding means converting to and from Java Maps, Lists, Strings, Numbers, Booleans and nulls
Full data binding means converting to and from any Java bean type (as well as "simple" types mentioned above)
org.codehaus.jackson.map.ObjectMapper performs the marshalling (writing JSON) and unmarshalling (reading JSON) for both variants.
Inspired by the annotation-based (code-first) variant of JAXB.
From usage perspective, one way to summarize these 3 methods is:
Streaming API is best performing (lowest overhead, fastest read/write; other 2 methods build on it)
Data Binding is often most convenient
Tree Model is most flexible
Given these properties, let's consider these in the reverse order, starting with what is usually the most natural and convenient method for Java developers:Jackson Data Binding API.
Examples
Full Data Binding (POJO) Example
Jackson's org.codehaus.jackson.map.ObjectMapper "just works" for mapping JSON data into plain old Java objects ("POJOs"). For example, given JSON data
{ "name" : { "first" : "Joe", "last" : "Sixpack" }, "gender" : "MALE", "verified" : false, "userImage" : "Rm9vYmFyIQ=="}
It takes two lines of Java to turn it into a User instance:
1 ObjectMapper mapper = new ObjectMapper(); // can reuse, share globally 2 User user = mapper.readValue(new File("user.json"), User.class);
Where the User class looks something like this (from anentry on Tatu's blog):
1 public class User { 2 public enum Gender { MALE, FEMALE }; 3 4 public static class Name { 5 private String _first, _last; 6 7 public String getFirst() { return _first; } 8 public String getLast() { return _last; } 9 10 public void setFirst(String s) { _first = s; } 11 public void setLast(String s) { _last = s; } 12 } 13 14 private Gender _gender; 15 private Name _name; 16 private boolean _isVerified; 17 private byte[] _userImage; 18 19 public Name getName() { return _name; } 20 public boolean isVerified() { return _isVerified; } 21 public Gender getGender() { return _gender; } 22 public byte[] getUserImage() { return _userImage; } 23 24 public void setName(Name n) { _name = n; } 25 public void setVerified(boolean b) { _isVerified = b; } 26 public void setGender(Gender g) { _gender = g; } 27 public void setUserImage(byte[] b) { _userImage = b; } 28 }
Marshalling back to JSON is similarly straightforward:
mapper.writeValue(new File("user-modified.json"), user);
For fancier data binding (e.g., unmarshalling formatted dates intojava.util.Date), Jackson provides annotations to customize the marshalling and unmarshalling process.
"Raw" Data Binding Example
(also known as "Untyped", or sometimes "simple" data binding)
In cases where you do not have (and don't want to create) specific Java classes to bind JSON to/from, "Untyped data binding" may be a better approach. It is used same way as full data binding, except that the formal binding type is specified simply as Object.class (or Map.class, List.class, String[].class if more specific typing is wanted). So the earlier binding of JSON that represent User data could have been done by:
Map<String,Object> userData = mapper.readValue(new File("user.json"), Map.class);
and userData would be like one we would explicit construct by:
1 Map<String,Object> userData = new HashMap<String,Object>(); 2 Map<String,String> nameStruct = new HashMap<String,String>(); 3 nameStruct.put("first", "Joe"); 4 nameStruct.put("last", "Sixpack"); 5 userData.put("name", nameStruct); 6 userData.put("gender", "MALE"); 7 userData.put("verified", Boolean.FALSE); 8 userData.put("userImage", "Rm9vYmFyIQ==");
This obviously works both ways: if you did construct such a Map (or bind from JSON and modify), you could write out just as before, by:
mapper.writeValue(new File("user-modified.json"), userData);
How does this work? By specifying Map.class, we do not specify generic key/value types. ButObjectMapper does know how to bind JSON data to and from Maps (and Lists, arrays, wrapper types), and does just that. Fundamentally JSON data has no "real" type as far as Jackson is concerned -- if it can be properly mapped to a type you give, it will be mapped.
Concrete Java types that Jackson will use for simple data binding are:
JSON Type
Java Type
object
LinkedHashMap<String,Object>
array
ArrayList<Object>
string
String
number (no fraction)
Integer, Long or BigInteger (smallest applicable)
number (fraction)
Double (configurable to use BigDecimal)
true|false
Boolean
null
null
Data Binding with Generics
In addition to binding to POJOs and "simple" types, there is one additional variant: that of binding to generic (typed) containers.This case requires special handling due to so-called Type Erasure (used by Java to implement generics in somewhat backwards compatible way), which prevents you from using something likeCollection<String>.class (which does not compile).
So if you want to bind data into a Map<String,User> you will need to use:
Map<String,User> result = mapper.readValue(src, new TypeReference<Map<String,User>>() { });
where TypeReference is only needed to pass generic type definition (via anynomous inner class in this case): the important part is<Map<String,User>> which defines type to bind to.
If you don't do this (and just pass Map.class), call is equivalent to binding toMap<?,?> (i.e. "untyped" Map), as explained above.
UPDATE: As an alternative, version 1.3 also allows programmatic construction of types by using TypeFactory.
Tree Model Example
Yet another way to get Objects out of JSON is to build a tree. This is similar to DOM trees for XML. The way Jackson builds trees is to use basicJsonNode base class, which exposes read access that is usually needed. Actual node types used are sub-classes; but the sub-type only needs to be used when modifying trees.
Trees can be read and written using either Streaming API (see below), or usingObjectMapper.
With ObjectMapper, you will do something like:
1 ObjectMapper m = new ObjectMapper(); 2 // can either use mapper.readTree(source), or mapper.readValue(source, JsonNode.class); 3 JsonNode rootNode = m.readTree(new File("user.json")); 4 // ensure that "last name" isn't "Xmler"; if is, change to "Jsoner" 5 JsonNode nameNode = rootNode.path("name"); 6 String lastName = nameNode.path("last").getTextValue(). 7 if ("xmler".equalsIgnoreCase(lastName)) { 8 ((ObjectNode)nameNode).put("last", "Jsoner"); 9 } 10 // and write it out: 11 m.writeValue(new File("user-modified.json"), rootNode);
Or if you want to construct a Tree (for the User example) from scratch, you can do:
1 TreeMapper treeMapper = new TreeMapper(); 2 ObjectNode userOb = treeMapper.objectNode(); 3 Object nameOb = userRoot.putObject("name"); 4 nameOb.put("first", "Joe"); 5 nameOb.put("last", "Sixpack"); 6 userOb.put("gender", User.Gender.MALE.toString()); 7 userOb.put("verified", false); 8 byte[] imageData = getImageData(); // or wherever it comes from 9 userOb.put("userImage", imageData);
(NOTE: with Jackson 1.2 you can use ObjectMapper directly, using ObjectMapper.createObjectNode() to create userOb -- above example will work with JAckson 1.0 and 1.1)
Streaming API Example
And finally, there is the third way: turbo-charged, high-performance method known as Streaming API (aka incremental mode, since content is read and written incrementally).
Just for fun, let's implement the writing functionality (equivalent to earlier examples) using "raw" Streaming API: WriteJSON.java
1 JsonFactory f = new JsonFactory(); 2 JsonGenerator g = f.createJsonGenerator(new File("user.json")); 3 4 g.writeStartObject(); 5 g.writeObjectFieldStart("name"); 6 g.writeStringField("first", "Joe"); 7 g.writeStringField("last", "Sixpack"); 8 g.writeEndObject(); // for field 'name' 9 g.writeStringField("gender", Gender.MALE); 10 g.writeBooleanField("verified", false); 11 g.writeFieldName("userImage"); // no 'writeBinaryField' (yet?) 12 byte[] binaryData = ...; 13 g.writeBinary(binaryData); 14 g.writeEndObject(); 15 g.close(); // important: will force flushing of output, close underlying output stream
Not horribly bad (esp. compared to amount of work needed for writing, say, equivalent XML content), but certainly more laborious than basic Object mapping.
On the other hand, you do have full control over each and every detail. And overhead is minimal: this is still a bit faster than usingObjectMapper; not a whole lot (perhaps 20-30% faster in common cases), but still. And perhaps most importantly, output is done in streaming manner: except for some buffering, all content will be written out right away. This means that memory usage is also minimal.
How about parsing, then? Code could look something like:
1 JsonFactory f = new JsonFactory(); 2 JsonParser jp = f.createJsonParser(new File("user.json")); 3 User user = new User(); 4 jp.nextToken(); // will return JsonToken.START_OBJECT (verify?) 5 while (jp.nextToken() != JsonToken.END_OBJECT) { 6 String fieldname = jp.getCurrentName(); 7 jp.nextToken(); // move to value, or START_OBJECT/START_ARRAY 8 if ("name".equals(fieldname)) { // contains an object 9 Name name = new Name(); 10 while (jp.nextToken() != JsonToken.END_OBJECT) { 11 String namefield = jp.getCurrentName(); 12 jp.nextToken(); // move to value 13 if ("first".equals(namefield)) { 14 name.setFirst(jp.getText()); 15 } else if ("last".equals(namefield)) { 16 name.setLast(jp.getText()); 17 } else { 18 throw new IllegalStateException("Unrecognized field '"+fieldname+"'!"); 19 } 20 } 21 user.setName(name); 22 } else if ("gender".equals(fieldname)) { 23 user.setGender(User.Gender.valueOf(jp.getText())); 24 } else if ("verified".equals(fieldname)) { 25 user.setVerified(jp.getCurrentToken() == JsonToken.VALUE_TRUE); 26 } else if ("userImage".equals(fieldname)) { 27 user.setUserImage(jp.getBinaryValue()); 28 } else { 29 throw new IllegalStateException("Unrecognized field '"+fieldname+"'!"); 30 } 31 } 32 jp.close(); // ensure resources get cleaned up timely and properly
which is quite a bit more than you'll use with data binding.
One final trick: it is also possible to use data binding and tree model directly fromJsonParser and JsonGenerator. To do this, have a look at methods:
JsonParser.readValueAs()
JsonParser.readValueAsTree()
JsonGenerator.writeObject()
JsonGenerator.writeTree()
which do about what you might expect them to do.
The only (?) trick is that you MUST make sure you use org.codehaus.jackson.map.MappingJsonFactory for constructing "data-binding capable" parser and generator instances (instead of basicorg.codehaus.jackson.JsonFactory).
Streaming API Example 2: arrays
(as contributed by Ransom Briggs)
Let's consider following POJO:
1 public class Foo { 2 public String foo; 3 }
and sample JSON stream of:
String json = [{\"foo\": \"bar\"},{\"foo\": \"biz\"}]";
while there are convenient ways to work on this with databinding (seeObjectReader.readValues() for details), you can easily use streaming to iterate over stream, bind individual elements as well:
1 JsonFactory f = new JsonFactory(); 2 JsonParser jp = f.createJsonParser(json); 3 // advance stream to START_ARRAY first: 4 jp.nextToken(); 5 // and then each time, advance to opening START_OBJECT 6 while (jp.nextToken() == JsonToken.START_OBJECT)) { 7 Foo foobar = mapper.readValue(jp, Foo.class); 8 // process 9 // after binding, stream points to closing END_OBJECT 10 }
Next Steps
You may want to check out rest of JacksonDocumentation for more inspiration.
CategoryJackson
- JacksonInFiveMinutes
- JacksonInFiveMinutes
- 《C Primer Plus》 学习笔记系列之(二)
- POJ 3267 DP
- Java学习之道:详解Java解析XML的四种方法
- 虚拟化(三):vsphere套件的安装注意及使用
- SGU 126 Boxes
- JacksonInFiveMinutes
- 最小路径覆盖 hdu 1151 hdu 3335
- 蟠桃记(杭电2013)
- 小白学jquery Mobile《构建跨平台APP:jQuery Mobile移动应用实战》连载五(给按钮加图标)
- HibernateTemplate、HibernateDaoSupport两种方法实现增删改查Good
- PHP、JSP间的比较
- hbase安装配置
- 字符对齐
- uva 11248 网络流 【扩一条边的容量至某一指定值】