Bug: 199275786

Clone this repo:
  1. 2bf6642 Fix errorprone warnings that should be errors am: 6a791f63ce am: 4fd26e3017 am: 5f25573c1a by Cole Faust · 2 years, 2 months ago aml_hef_341811030 aml_rkp_341810000 android14-d2-release android14-d2-s1-release android14-d2-s2-release android14-d2-s3-release android14-d2-s4-release android14-d2-s5-release android14-dev android14-mainline-healthfitness-release android14-prebuilt-test android14-qpr1-automotiveos-release android14-qpr1-release android14-qpr1-s2-release android14-qpr2-release android14-qpr2-s1-release android14-qpr2-s2-release android14-qpr2-s3-release android14-qpr2-s4-release android14-qpr2-s5-release android14-qpr3-d1-release android14-qpr3-d1-s1-release android14-qpr3-d1-s2-release android14-qpr3-d1-s3-release android14-qpr3-release android14-qpr3-s10-release android14-qpr3-s11-release android14-qpr3-s12-release android14-qpr3-s13-release android14-qpr3-s14-release android14-qpr3-s15-release android14-qpr3-s2-release android14-qpr3-s3-release android14-qpr3-s4-release android14-qpr3-s5-release android14-qpr3-s6-release android14-qpr3-s7-release android14-qpr3-s8-release android14-qpr3-s9-release android15-automotiveos-dev android15-platform-release android15-prebuilt-test android15-qpr1-release android15-release android15-s1-release android15-security-release android15-tests-dev android15-tests-release main master aml_cfg_341510000 aml_cfg_351010000 aml_hef_341114030 aml_hef_341311010 aml_hef_341415040 aml_hef_341512030 aml_hef_341613000 aml_hef_341717050 aml_hef_341811030 aml_hef_350921160 aml_hef_351016140 aml_hef_351120040 aml_rkp_341012000 aml_rkp_341015010 aml_rkp_341114000 aml_rkp_341311000 aml_rkp_341510000 aml_rkp_341810000 aml_rkp_350910000 aml_rkp_351011000 aml_tz6_351010000 android-14.0.0_r16 android-14.0.0_r17 android-14.0.0_r18 android-14.0.0_r19 android-14.0.0_r20 android-14.0.0_r21 android-14.0.0_r22 android-14.0.0_r23 android-14.0.0_r24 android-14.0.0_r25 android-14.0.0_r26 android-14.0.0_r27 android-14.0.0_r29 android-14.0.0_r30 android-14.0.0_r31 android-14.0.0_r32 android-14.0.0_r33 android-14.0.0_r34 android-14.0.0_r35 android-14.0.0_r36 android-14.0.0_r37 android-14.0.0_r38 android-14.0.0_r39 android-14.0.0_r40 android-14.0.0_r41 android-14.0.0_r42 android-14.0.0_r43 android-14.0.0_r44 android-14.0.0_r45 android-14.0.0_r50 android-14.0.0_r51 android-14.0.0_r52 android-14.0.0_r53 android-14.0.0_r54 android-14.0.0_r55 android-14.0.0_r56 android-14.0.0_r57 android-14.0.0_r58 android-14.0.0_r59 android-14.0.0_r60 android-14.0.0_r61 android-14.0.0_r62 android-14.0.0_r63 android-14.0.0_r64 android-14.0.0_r65 android-14.0.0_r66 android-14.0.0_r67 android-14.0.0_r68 android-14.0.0_r69 android-14.0.0_r70 android-14.0.0_r71 android-14.0.0_r72 android-14.0.0_r73 android-14.0.0_r74 android-14.0.0_r75 android-15.0.0_r1 android-15.0.0_r2 android-15.0.0_r3 android-15.0.0_r4 android-15.0.0_r5 android-15.0.0_r6 android-15.0.0_r7 android-15.0.0_r8 android-15.0.0_r9 android-automotiveos-14.0.0_lts2 android-automotiveos-14.0.0_lts3 android-cts-15.0_r1 android-cts-15.0_r2 android-platform-15.0.0_r1 android-platform-15.0.0_r2 android-platform-15.0.0_r3 android-security-15.0.0_r1 android-security-15.0.0_r2 android-security-15.0.0_r3 android-vts-15.0_r1 android-vts-15.0_r2
  2. 5f25573 Fix errorprone warnings that should be errors am: 6a791f63ce am: 4fd26e3017 by Cole Faust · 2 years, 2 months ago android-u-beta-1-gpl
  3. 4fd26e3 Fix errorprone warnings that should be errors am: 6a791f63ce by Cole Faust · 2 years, 2 months ago main-16k-with-phones
  4. 6a791f6 Fix errorprone warnings that should be errors by Cole Faust · 2 years, 2 months ago
  5. 540b980 Update OWNERS am: c0d8ef9bea am: 951878e928 am: 5002b46743 am: 106f17e549 am: 485628b8f3 by Neil Fuller · 3 years, 2 months ago aml_tz4_332714010 android13-d2-release android13-d3-s1-release android13-d4-release android13-d4-s1-release android13-d4-s2-release android13-dev android13-frc-adbd-release android13-frc-art-release android13-frc-cellbroadcast-release android13-frc-conscrypt-release android13-frc-odp-release android13-mainline-adservices-release android13-mainline-appsearch-release android13-mainline-go-adbd-release android13-mainline-go-adservices-release android13-mainline-go-appsearch-release android13-mainline-go-media-swcodec-release android13-mainline-go-mediaprovider-release android13-mainline-go-networking-release android13-mainline-go-neuralnetworks-release android13-mainline-go-odp-release android13-mainline-go-os-statsd-release android13-mainline-go-permission-release android13-mainline-go-resolv-release android13-mainline-go-scheduling-release android13-mainline-go-sdkext-release android13-mainline-go-tethering-release android13-mainline-go-tzdata4-release android13-mainline-go-uwb-release android13-mainline-go-wifi-release android13-mainline-tzdata4-release android13-mainline-uwb-release android13-prebuilt-test android13-qpr1-release android13-qpr1-s1-release android13-qpr1-s2-release android13-qpr1-s3-release android13-qpr1-s4-release android13-qpr1-s5-release android13-qpr1-s6-release android13-qpr1-s7-release android13-qpr1-s8-release android13-qpr2-b-s1-release android13-qpr2-release android13-qpr2-s1-release android13-qpr2-s10-release android13-qpr2-s11-release android13-qpr2-s12-release android13-qpr2-s2-release android13-qpr2-s3-release android13-qpr2-s5-release android13-qpr2-s6-release android13-qpr2-s7-release android13-qpr2-s8-release android13-qpr2-s9-release android13-qpr3-c-s1-release android13-qpr3-c-s10-release android13-qpr3-c-s11-release android13-qpr3-c-s12-release android13-qpr3-c-s2-release android13-qpr3-c-s3-release android13-qpr3-c-s4-release android13-qpr3-c-s5-release android13-qpr3-c-s6-release android13-qpr3-c-s7-release android13-qpr3-c-s8-release android13-qpr3-release android13-qpr3-s1-release android13-qpr3-s10-release android13-qpr3-s11-release android13-qpr3-s12-release android13-qpr3-s13-release android13-qpr3-s14-release android13-qpr3-s2-release android13-qpr3-s3-release android13-qpr3-s4-release android13-qpr3-s5-release android13-qpr3-s6-release android13-qpr3-s7-release android13-qpr3-s8-release android13-qpr3-s9-release aml_ads_331131000 aml_ads_331418080 aml_ads_331511020 aml_ads_331611190 aml_ads_331710270 aml_ads_331814200 aml_ads_331920180 aml_ase_331011020 aml_ase_331112000 aml_ase_331311020 aml_go_adb_330913000 aml_go_ads_330913000 aml_go_ads_330915000 aml_go_ads_330915100 aml_go_ase_330913000 aml_go_mpr_330912000 aml_go_net_330913000 aml_go_neu_330912000 aml_go_odp_330912000 aml_go_odp_330913000 aml_go_per_330912000 aml_go_res_330912000 aml_go_sch_330911000 aml_go_sdk_330810000 aml_go_sta_330911000 aml_go_swc_330913000 aml_go_tet_330914010 aml_go_tz4_330912000 aml_go_uwb_330912000 aml_go_wif_330911000 aml_tz4_331012000 aml_tz4_331012040 aml_tz4_331012050 aml_tz4_331314010 aml_tz4_331314020 aml_tz4_331314030 aml_tz4_331910000 aml_tz4_332714010 aml_tz4_332714050 aml_tz4_332714070 aml_tz4_332714200 aml_uwb_330810010 aml_uwb_331015040 aml_uwb_331115000 aml_uwb_331310030 aml_uwb_331410010 aml_uwb_331611010 aml_uwb_331613010 aml_uwb_331820070 aml_uwb_331910010 android-13.0.0_r16 android-13.0.0_r17 android-13.0.0_r18 android-13.0.0_r19 android-13.0.0_r20 android-13.0.0_r21 android-13.0.0_r22 android-13.0.0_r23 android-13.0.0_r24 android-13.0.0_r27 android-13.0.0_r28 android-13.0.0_r29 android-13.0.0_r30 android-13.0.0_r32 android-13.0.0_r33 android-13.0.0_r34 android-13.0.0_r35 android-13.0.0_r36 android-13.0.0_r37 android-13.0.0_r38 android-13.0.0_r39 android-13.0.0_r40 android-13.0.0_r41 android-13.0.0_r42 android-13.0.0_r43 android-13.0.0_r44 android-13.0.0_r45 android-13.0.0_r46 android-13.0.0_r47 android-13.0.0_r48 android-13.0.0_r49 android-13.0.0_r50 android-13.0.0_r51 android-13.0.0_r52 android-13.0.0_r53 android-13.0.0_r54 android-13.0.0_r55 android-13.0.0_r56 android-13.0.0_r57 android-13.0.0_r58 android-13.0.0_r59 android-13.0.0_r60 android-13.0.0_r61 android-13.0.0_r62 android-13.0.0_r63 android-13.0.0_r64 android-13.0.0_r65 android-13.0.0_r66 android-13.0.0_r67 android-13.0.0_r68 android-13.0.0_r69 android-13.0.0_r70 android-13.0.0_r71 android-13.0.0_r72 android-13.0.0_r73 android-13.0.0_r74 android-13.0.0_r75 android-13.0.0_r76 android-13.0.0_r77 android-13.0.0_r78 android-13.0.0_r79 android-13.0.0_r80 android-13.0.0_r81 android-13.0.0_r82 android-13.0.0_r83 t_frc_adb_330444000 t_frc_art_330443060 t_frc_ase_330444010 t_frc_cbr_330443000 t_frc_con_330443020 t_frc_odp_330442000 t_frc_odp_330442040

Overview

This project contains general purpose annotations for Jackson Data Processor, used on value and handler types. The only annotations not included are ones that require dependency to the Databind package.

Project contains versions 2.0 and above: source code for earlier (1.x) versions is available from Jackson-1 SVN repository. Note that with version 1.x these annotations were part of the ‘core jar’.

Full Listing of Jackson Annotations details all available annotations; Project Wiki gives more details.

Project is licensed under Apache License 2.0.

Build Status Maven Central Javadoc


Usage, general

Improvements over typical Java annotations

In addition to regular usage (see below), there are couple of noteworthy improvements Jackson does:

  • Mix-in annotations allow associating annotations on third-party classes ‘‘without modifying classes’’.
  • Jackson annotations support full inheritance: meaning that you can ‘‘override annotation definitions’’, and not just class annotations but also method/field annotations!

Maven, Java package

All annotations are in Java package com.fasterxml.jackson.annotation. To use annotations, you need to use Maven dependency:

<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-annotations</artifactId>
  <version>${jackson-annotations-version}</version>
</dependency>

or download jars from Maven repository (or via quick links on Wiki)

Usage, simple

Let's start with simple use cases: renaming or ignoring properties, and modifying types that are used.

Note: while examples only show field properties, same annotations would work with method (getter/setter) properties.

Annotations for renaming properties

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;
}

would result in JSON like:

{ "firstName" : "Bob" }

instead of

{ "_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;
}

and get JSON like:

{ "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;
}

which would be able to handle JSON like:

{ "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;
}

Annotations for choosing more/less specific types

Sometimes the type Jackson uses when reading or writing a property is not quite what you want:

  • When reading (deserializing), declared type may be a general type, but you know which exact implementation type to use
  • 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.

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;

  // 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;
}

Usage, intermediate

Using constructors or factory methods

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;

   @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");
   }
}

the difference being that the creator method can only take one argument, and that argument must NOT have @JsonProperty annotation.

Handling polymorphic types

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 {
}

public class Impl1 extends BaseClass {
  public int x;
}
public class Impl2 extends BaseClass {
  public String name;
}

public class PojoWithTypedObjects {
  public List<BaseClass> items;
}

and this could result in serialized JSON like:

{ "items" : [
  { "class":"Impl2", "name":"Bob" },
  { "class":"Impl1", "x":13 }
]}

Note that this annotation has lots of configuration possibilities: for more information check out Intro to polymorphic type handling

Changing property auto-detection

The default Jackson property detection rules will find:

  • All ‘‘public’’ fields
  • All ‘‘public’’ getters (‘getXxx()’ methods)
  • All setters (‘setXxx(value)’ methods), ‘‘regardless of visibility’’)

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;
}

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;
}

Further reading

Project-specific documentation:

Usage:

Related: