This is an automated email from the git hooks/post-receive script. tjaalton pushed a commit to branch master in repository jackson-annotations.
commit 41d9371c3d3b29798295c45b57b6e67b77eb35d9 Author: Artur Dryomov <[email protected]> Date: Mon Feb 11 17:43:24 2013 +0300 Use syntax highlighting in the readme file. --- README.md | 188 ++++++++++++++++++++++++++++++++++++-------------------------- 1 file changed, 110 insertions(+), 78 deletions(-) diff --git a/README.md b/README.md index 70cd703..b936ac3 100644 --- a/README.md +++ b/README.md @@ -26,11 +26,13 @@ In addition to regular usage (see below), there are couple of noteworthy improve All annotations are in Java package `com.fasterxml.core.annotation`. To use annotations, you need to use Maven dependency: - <dependency> - <groupId>com.fasterxml.jackson.core</groupId> - <artifactId>jackson-annotations</artifactId> - <version>2.1.1</version> - </dependency> +```xml +<dependency> + <groupId>com.fasterxml.jackson.core</groupId> + <artifactId>jackson-annotations</artifactId> + <version>2.1.1</version> +</dependency> +``` or download jars from Maven repository or [Download page](http://wiki.fasterxml.com/JacksonDownload) @@ -44,49 +46,65 @@ Note: while examples only show field properties, same annotations would work wit One of most common tasks is to change JSON name used for a property: for example: - public class Name { - @JsonProperty("firstName") - public String _first_name; - } +```java +public class Name { + @JsonProperty("firstName") + public String _first_name; +} +``` would result in JSON like: - { "firstName" : "Bob" } +```json +{ "firstName" : "Bob" } +``` instead of - { "_first_name" : "Bob" +```json +{ "_first_name" : "Bob" } +``` ### Annotations for Ignoring properties Sometimes POJOs contain properties that you do not want to write out, so you can do: - public class Value { - public int value; - @JsonIgnore public int internalValue; - } +```java +public class Value { + public int value; + @JsonIgnore public int internalValue; +} +``` and get JSON like: - { "value" : 42 } +```json +{ "value" : 42 } +``` or, you may get properties in JSON that you just want to skip: if so, you can use: - @JsonIgnoreProperties({ "extra", "uselessValue" }) - public class Value { - public int value; - } +```java +@JsonIgnoreProperties({ "extra", "uselessValue" }) +public class Value { + public int value; +} +``` which would be able to handle JSON like: - { "value" : 42, "extra" : "fluffy", "uselessValue" : -13 } +```json +{ "value" : 42, "extra" : "fluffy", "uselessValue" : -13 } +``` Finally, you may even want to just ignore any "extra" properties from JSON (ones for which there is no counterpart in POJO). This can be done by adding: - @JsonIgnoreProperties(ignoreUnknown=true) - public class PojoWithAny { - public int value; - } +```java +@JsonIgnoreProperties(ignoreUnknown=true) +public class PojoWithAny { + public int value; +} +``` ### Annotations for choosing more/less specific types @@ -97,17 +115,19 @@ Sometimes the type Jackson uses when reading or writing a property is not quite These cases can be handled by following annotations: - public class ValueContainer { - // although nominal type is 'Value', we want to read JSON as 'ValueImpl' - @JsonDeserialize(as=ValueImpl.class) - public Value value; +```java +public class ValueContainer { + // although nominal type is 'Value', we want to read JSON as 'ValueImpl' + @JsonDeserialize(as=ValueImpl.class) + public Value value; - // although runtime type may be 'AdvancedType', we really want to serialize - // as 'BasicType'; two ways to do this: - @JsonSerialize(as=BasicType.class) - // or could also use: @JsonSerialize(typing=Typing.STATIC) - public BasicType another; - } + // although runtime type may be 'AdvancedType', we really want to serialize + // as 'BasicType'; two ways to do this: + @JsonSerialize(as=BasicType.class) + // or could also use: @JsonSerialize(typing=Typing.STATIC) + public BasicType another; +} +``` ----- @@ -117,27 +137,32 @@ These cases can be handled by following annotations: By default, Jackson tries to use the "default" constructor (one that takes no arguments), when creating value instances. But you can also choose to use another constructor, or a static factory method to create instance. To do this, you will need to use annotation `@JsonCreator`, and possibly `@JsonProperty` annotations to bind names to arguments: - public class CtorPOJO { - private final int _x, _y; +```java +public class CtorPOJO { + private final int _x, _y; - @JsonCreator - public CtorPOJO(@JsonProperty("x") int x, @JsonProperty("y") int y) { - _x = x; - _y = y; - } - } + @JsonCreator + public CtorPOJO(@JsonProperty("x") int x, @JsonProperty("y") int y) { + _x = x; + _y = y; + } +} +``` `@JsonCreator` can be used similarly for static factory methods. But there is also an alternative usage, which is so-called "delegating" creator: - public class DelegatingPOJO { - private final int _x, _y; - - @JsonCreator - public DelegatingPOJO(Map<String,Object> delegate) { - _x = (Integer) delegate.get("x"); - _y = (Integer) delegate.get("y"); - } +```java +public class DelegatingPOJO { + private final int _x, _y; + + @JsonCreator + public DelegatingPOJO(Map<String,Object> delegate) { + _x = (Integer) delegate.get("x"); + _y = (Integer) delegate.get("y"); + } +} +``` the difference being that the creator method can only take one argument, and that argument must NOT have `@JsonProperty` annotation. @@ -146,29 +171,32 @@ the difference being that the creator method can only take one argument, and tha If you need to read and write values of Objects where there are multiple possible subtypes (i.e. ones that exhibit polymorphism), you may need to enable inclusion of type information. This is needed so that Jackson can read back correct Object type when deserializing (reading JSON into Objects). This can be done by adding `@JsonTypeInfo` annotation on ''base class'': - // Include Java class name ("com.myempl.ImplClass") as JSON property "class" - @JsonTypeInfo(use=Id.CLASS, include=As.PROPERTY, property="class") - public abstract class BaseClass { - } +```java +// Include Java class name ("com.myempl.ImplClass") as JSON property "class" +@JsonTypeInfo(use=Id.CLASS, include=As.PROPERTY, property="class") +public abstract class BaseClass { +} - public class Impl1 extends BaseClass { - public int x; - } - public class Impl2 extends BaseClass { - public String name; - } +public class Impl1 extends BaseClass { + public int x; +} +public class Impl2 extends BaseClass { + public String name; +} - public class PojoWithTypedObjects { - public List<BaseClass> items; - } +public class PojoWithTypedObjects { + public List<BaseClass> items; +} +``` and this could result in serialized JSON like: - { "items" : [ - { "class":"Impl2", "name":"Bob" }, - { "class":"Impl1", "x":13 } - ]) - +```json +{ "items" : [ + { "class":"Impl2", "name":"Bob" }, + { "class":"Impl1", "x":13 } +]} +``` Note that this annotation has lots of configuration possibilities: for more information check out: @@ -186,18 +214,22 @@ The default Jackson property detection rules will find: But if this does not work, you can change visibility levels by using annotation `@JsonAutoDetect`. If you wanted, for example, to auto-detect ALL fields (similar to how packages like GSON work), you could do: - @JsonAutoDetect(fieldVisibility=JsonAutoDetect.Visibility.ANY) - public class POJOWithFields { - private int value; - } +```java +@JsonAutoDetect(fieldVisibility=JsonAutoDetect.Visibility.ANY) +public class POJOWithFields { + private int value; +} +``` or, to disable auto-detection of fields altogether: - @JsonAutoDetect(fieldVisibility=JsonAutoDetect.Visibility.NONE) - public class POJOWithNoFields { - // will NOT be included, unless there is access 'getValue()' - public int value; - } +```java +@JsonAutoDetect(fieldVisibility=JsonAutoDetect.Visibility.NONE) +public class POJOWithNoFields { + // will NOT be included, unless there is access 'getValue()' + public int value; +} +``` ----- -- Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-java/jackson-annotations.git _______________________________________________ pkg-java-commits mailing list [email protected] http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/pkg-java-commits
