Package edu.internet2.middleware.grouperClientExt.com.fasterxml.jackson.annotation

Annotation Interface JsonFormat

@Target({ANNOTATION_TYPE,FIELD,METHOD,PARAMETER,TYPE}) @Retention(RUNTIME) public @interface JsonFormat
General-purpose annotation used for configuring details of how values of properties are to be serialized. Unlike most other Jackson annotations, annotation does not have specific universal interpretation: instead, effect depends on datatype of property being annotated (or more specifically, deserializer and serializer being used).

Common uses include choosing between alternate representations -- for example, whether Date is to be serialized as number (Java timestamp) or String (such as ISO-8601 compatible time value) -- as well as configuring exact details with pattern() property.

As of Jackson 2.6, known special handling includes:

  • Date: Shape can be JsonFormat.Shape.STRING or JsonFormat.Shape.NUMBER; pattern may contain SimpleDateFormat-compatible pattern definition.
  • Can be used on Classes (types) as well, for modified default behavior, possibly overridden by per-property annotation
  • Enums: Shapes JsonFormat.Shape.STRING and JsonFormat.Shape.NUMBER can be used to change between numeric (index) and textual (name or toString()); but it is also possible to use JsonFormat.Shape.OBJECT to serialize (but not deserialize) Enums as JSON Objects (as if they were POJOs). NOTE: serialization as JSON Object only works with class annotation; will not work as per-property annotation.
  • Collections can be serialized as (and deserialized from) JSON Objects, if JsonFormat.Shape.OBJECT is used. NOTE: can ONLY be used as class annotation; will not work as per-property annotation.
  • Number subclasses can be serialized as full objects if JsonFormat.Shape.OBJECT is used. Otherwise the default behavior of serializing to a scalar number value will be preferred. NOTE: can ONLY be used as class annotation; will not work as per-property annotation.
Since:
2.0

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    JsonFormat.Feature
    Set of features that can be enabled/disabled for property annotated.
    static class 
    JsonFormat.Features
    Helper class that encapsulates information equivalent to Boolean valued EnumMap.
    static enum 
    JsonFormat.Shape
    Value enumeration used for indicating preferred Shape; translates loosely to JSON types, with some extra values to indicate less precise choices (i.e.
    static class 
    JsonFormat.Value
    Helper class used to contain information from a single JsonFormat annotation.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    OptBoolean
    lenient
    Property that indicates whether "lenient" handling should be enabled or disabled.
    String
    locale
    Locale to use for serialization (if needed).
    String
    pattern
    Datatype-specific additional piece of configuration that may be used to further refine formatting aspects.
    JsonFormat.Shape
    shape
    Structure to use for serialization: definition of mapping depends on datatype, but usually has straight-forward counterpart in data format (JSON).
    String
    timezone
    TimeZone to use for serialization (if needed).
    JsonFormat.Feature[]
    with
    Set of JsonFormat.Features to explicitly enable with respect to handling of annotated property.
    JsonFormat.Feature[]
    without
    Set of JsonFormat.Features to explicitly disable with respect to handling of annotated property.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    DEFAULT_LOCALE
    Value that indicates that default Locale (from deserialization or serialization context) should be used: annotation does not define value to use.
    static final String
    DEFAULT_TIMEZONE
    Value that indicates that default TimeZone (from deserialization or serialization context) should be used: annotation does not define value to use.

  • Field Details

    • DEFAULT_LOCALE

      static final String DEFAULT_LOCALE
      Value that indicates that default Locale (from deserialization or serialization context) should be used: annotation does not define value to use.
      See Also:

    • DEFAULT_TIMEZONE

      static final String DEFAULT_TIMEZONE
      Value that indicates that default TimeZone (from deserialization or serialization context) should be used: annotation does not define value to use.

      NOTE: default here does NOT mean JVM defaults but Jackson databindings default, usually UTC, but may be changed on ObjectMapper.

      See Also:

  • Element Details

    • pattern

      String pattern
      Datatype-specific additional piece of configuration that may be used to further refine formatting aspects. This may, for example, determine low-level format String used for Date serialization; however, exact use is determined by specific JsonSerializer
      Default:
      ""

    • shape

      JsonFormat.Shape shape
      Structure to use for serialization: definition of mapping depends on datatype, but usually has straight-forward counterpart in data format (JSON). Note that commonly only a subset of shapes is available; and if 'invalid' value is chosen, defaults are usually used.
      Default:
      ANY

    • locale

      String locale
      Locale to use for serialization (if needed). Special value of DEFAULT_LOCALE can be used to mean "just use the default", where default is specified by the serialization context, which in turn defaults to system defaults (Locale.getDefault()) unless explicitly set to another locale.
      Default:
      "##default"

    • timezone

      String timezone
      TimeZone to use for serialization (if needed). Special value of DEFAULT_TIMEZONE can be used to mean "just use the default", where default is specified by the serialization context, which in turn defaults to system default (UTC) unless explicitly set to another timezone.
      Default:
      "##default"

    • lenient

      OptBoolean lenient
      Property that indicates whether "lenient" handling should be enabled or disabled. This is relevant mostly for deserialization of some textual datatypes, especially date/time types.

      Note that underlying default setting depends on datatype (or more precisely deserializer for it): for most date/time types, default is for leniency to be enabled.

      Since:
      2.9
      Default:
      DEFAULT

    • with

      JsonFormat.Feature[] with
      Set of JsonFormat.Features to explicitly enable with respect to handling of annotated property. This will have precedence over possible global configuration.
      Since:
      2.6
      Default:
      {}

    • without

      JsonFormat.Feature[] without
      Set of JsonFormat.Features to explicitly disable with respect to handling of annotated property. This will have precedence over possible global configuration.
      Since:
      2.6
      Default:
      {}