README.md
1# Overview
2
3This project contains general purpose annotations for
4Jackson Data Processor, used on value and handler types.
5The only annotations not included are ones that require dependency
6to the [Databind package](../../../jackson-databind).
7
8Project contains versions 2.0 and above: source code for earlier (1.x) versions is available from [Jackson-1](../../../jackson-1) SVN repository.
9Note that with version 1.x these annotations were part of the 'core jar'.
10
11[Full Listing of Jackson Annotations](../../wiki/Jackson-Annotations) details all available annotations;
12[Project Wiki](../../wiki) gives more details.
13
14Project is licensed under [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0).
15
16
17[![Build Status](https://travis-ci.org/FasterXML/jackson-annotations.png?branch=master)](https://travis-ci.org/FasterXML/jackson-annotations) [![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.fasterxml.jackson.core/jackson-annotations/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.fasterxml.jackson.core/jackson-annotations)
18[![Javadoc](https://javadoc-emblem.rhcloud.com/doc/com.fasterxml.jackson.core/jackson-annotations/badge.svg)](http://www.javadoc.io/doc/com.fasterxml.jackson.core/jackson-annotations)
19
20-----
21
22## Usage, general
23
24### Improvements over typical Java annotations
25
26In addition to regular usage (see below), there are couple of noteworthy improvements Jackson does:
27
28* [Mix-in annotations](../../wiki/Mixin-Annotations) allow associating annotations on third-party classes ''without modifying classes''.
29* Jackson annotations support full inheritance: meaning that you can ''override annotation definitions'', and not just class annotations but also method/field annotations!
30
31### Maven, Java package
32
33All annotations are in Java package `com.fasterxml.jackson.annotation`.
34To use annotations, you need to use Maven dependency:
35
36```xml
37<dependency>
38 <groupId>com.fasterxml.jackson.core</groupId>
39 <artifactId>jackson-annotations</artifactId>
40 <version>${jackson-annotations-version}</version>
41</dependency>
42```
43
44or download jars from Maven repository (or via quick links on [Wiki](../../wiki))
45
46## Usage, simple
47
48Let's start with simple use cases: renaming or ignoring properties, and modifying types that are used.
49
50Note: while examples only show field properties, same annotations would work with method (getter/setter) properties.
51
52### Annotations for renaming properties
53
54One of most common tasks is to change JSON name used for a property: for example:
55
56```java
57public class Name {
58 @JsonProperty("firstName")
59 public String _first_name;
60}
61```
62
63would result in JSON like:
64
65```json
66{ "firstName" : "Bob" }
67```
68
69instead of
70
71```json
72{ "_first_name" : "Bob" }
73```
74
75### Annotations for Ignoring properties
76
77Sometimes POJOs contain properties that you do not want to write out, so you can do:
78
79```java
80public class Value {
81 public int value;
82 @JsonIgnore public int internalValue;
83}
84```
85
86and get JSON like:
87
88```json
89{ "value" : 42 }
90```
91
92or, you may get properties in JSON that you just want to skip: if so, you can use:
93
94```java
95@JsonIgnoreProperties({ "extra", "uselessValue" })
96public class Value {
97 public int value;
98}
99```
100
101which would be able to handle JSON like:
102
103```json
104{ "value" : 42, "extra" : "fluffy", "uselessValue" : -13 }
105```
106
107Finally, 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:
108
109```java
110@JsonIgnoreProperties(ignoreUnknown=true)
111public class PojoWithAny {
112 public int value;
113}
114```
115
116### Annotations for choosing more/less specific types
117
118Sometimes the type Jackson uses when reading or writing a property is not quite what you want:
119
120* When reading (deserializing), declared type may be a general type, but you know which exact implementation type to use
121* When writing (serializing), Jackson will by default use the specific runtime type; but you may not want to include all information from that type but rather just contents of its supertype.
122
123These cases can be handled by following annotations:
124
125```java
126public class ValueContainer {
127 // although nominal type is 'Value', we want to read JSON as 'ValueImpl'
128 @JsonDeserialize(as=ValueImpl.class)
129 public Value value;
130
131 // although runtime type may be 'AdvancedType', we really want to serialize
132 // as 'BasicType'; two ways to do this:
133 @JsonSerialize(as=BasicType.class)
134 // or could also use: @JsonSerialize(typing=Typing.STATIC)
135 public BasicType another;
136}
137```
138
139-----
140
141## Usage, intermediate
142
143### Using constructors or factory methods
144
145By 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:
146
147```java
148public class CtorPOJO {
149 private final int _x, _y;
150
151 @JsonCreator
152 public CtorPOJO(@JsonProperty("x") int x, @JsonProperty("y") int y) {
153 _x = x;
154 _y = y;
155 }
156}
157```
158
159`@JsonCreator` can be used similarly for static factory methods.
160But there is also an alternative usage, which is so-called "delegating" creator:
161
162```java
163public class DelegatingPOJO {
164 private final int _x, _y;
165
166 @JsonCreator
167 public DelegatingPOJO(Map<String,Object> delegate) {
168 _x = (Integer) delegate.get("x");
169 _y = (Integer) delegate.get("y");
170 }
171}
172```
173
174the difference being that the creator method can only take one argument, and that argument must NOT have `@JsonProperty` annotation.
175
176### Handling polymorphic types
177
178If 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).
179This can be done by adding `@JsonTypeInfo` annotation on ''base class'':
180
181```java
182// Include Java class name ("com.myempl.ImplClass") as JSON property "class"
183@JsonTypeInfo(use=Id.CLASS, include=As.PROPERTY, property="class")
184public abstract class BaseClass {
185}
186
187public class Impl1 extends BaseClass {
188 public int x;
189}
190public class Impl2 extends BaseClass {
191 public String name;
192}
193
194public class PojoWithTypedObjects {
195 public List<BaseClass> items;
196}
197```
198
199and this could result in serialized JSON like:
200
201```json
202{ "items" : [
203 { "class":"Impl2", "name":"Bob" },
204 { "class":"Impl1", "x":13 }
205]}
206```
207
208Note that this annotation has lots of configuration possibilities: for more information check out
209[Intro to polymorphic type handling](http://www.cowtowncoder.com/blog/archives/2010/03/entry_372.html)
210
211### Changing property auto-detection
212
213The default Jackson property detection rules will find:
214
215* All ''public'' fields
216* All ''public'' getters ('getXxx()' methods)
217* All setters ('setXxx(value)' methods), ''regardless of visibility'')
218
219But if this does not work, you can change visibility levels by using annotation `@JsonAutoDetect`.
220If you wanted, for example, to auto-detect ALL fields (similar to how packages like GSON work), you could do:
221
222```java
223@JsonAutoDetect(fieldVisibility=JsonAutoDetect.Visibility.ANY)
224public class POJOWithFields {
225 private int value;
226}
227```
228
229or, to disable auto-detection of fields altogether:
230
231```java
232@JsonAutoDetect(fieldVisibility=JsonAutoDetect.Visibility.NONE)
233public class POJOWithNoFields {
234 // will NOT be included, unless there is access 'getValue()'
235 public int value;
236}
237```
238
239-----
240
241# Further reading
242
243Project-specific documentation:
244
245* [Full Listing of Jackson Annotations](../../wiki/Jackson-Annotations) details all available annotations.
246* [Other documentation](../../wiki)
247
248Usage:
249
250* You can make Jackson 2 use Jackson 1 annotations with [jackson-legacy-introspector](https://github.com/Laures/jackson-legacy-introspector)
251
252Related:
253
254* [Databinding](https://github.com/FasterXML/jackson-databind) module has more documentation, since it is the main user of annotations.
255In addition, here are other useful links:
256* [Jackson Project Home](http://wiki.fasterxml.com/JacksonHome)
257 * [Annotation documentation at FasterXML Wiki](http://wiki.fasterxml.com/JacksonAnnotations) covers 1.x annotations as well as 2.0
258
259
260