Repository files navigation

This is a multi-module umbrella project forJacksonmodules needed to support Java 8 features, especially with Jackson 2.x that onlyrequires Java 7 for running (and until 2.7 only Java 6).

When used with Jackson 2.x, Java 8 support is provided via 3 separate modules:

• Parameter names: support for detecting constructor and factory method ("creator") parameters without having to use@JsonProperty annotation
  • providescom.fasterxml.jackson.module.paramnames.ParameterNamesModule
• Java 8 Date/time: support for Java 8 date/time types (specified in JSR-310 specification)
  • providescom.fasterxml.jackson.datatype.jsr310.JavaTimeModule
  • ALSO provides legacy variantcom.fasterxml.jackson.datatype.jsr310.JSR310TimeModule
  • difference between 2 modules is that of configuration defaults: use ofJavaTimeModule strongly recommended for new code
• Java 8 Datatypes: support for other new Java 8 datatypes outside of date/time: most notablyOptional,OptionalLong,OptionalDouble
  • providescom.fasterxml.jackson.datatype.jdk8.Jdk8Module

all of which are built from this repository, and accessed and used as separate Jackson modules(with separate Maven artifacts).

Jackson 3.0 changes things as it requires Java 8 to work and can thereby directly supported features.

Because of this, all 3 modules are merged intojackson-databindand need not be registered (as of Jacksson3.0.0-rc3)

All modules are licensed underApache License 2.0.

To include modules, you use some or all of:

<!-- parameter names--><dependency>    <groupId>com.fasterxml.jackson.module</groupId>    <artifactId>jackson-module-parameter-names</artifactId></dependency><!-- Java 8 Date/time--><dependency>    <groupId>com.fasterxml.jackson.datatype</groupId>    <artifactId>jackson-datatype-jsr310</artifactId></dependency><!-- Java 8 Datatypes--><dependency>    <groupId>com.fasterxml.jackson.datatype</groupId>    <artifactId>jackson-datatype-jdk8</artifactId></dependency>

and either include versions directly, OR, preferably, importJackson BOM that will specify consistent version set.

Note that the parent project --jackson-modules-java8 -- is ONLY used as parent pom byindividual "child" modules, and DOES NOT have dependencies on them. This means that you should not depend on itas that will not include child modules.

The most common mechanism (and one recommended by Jackson team) is to explicitly register modules you want.This is done by code like:

// Up to Jackson 2.9: (but not with 3.0)ObjectMappermapper =newObjectMapper()   .registerModule(newParameterNamesModule())   .registerModule(newJdk8Module())   .registerModule(newJavaTimeModule());// new module, NOT JSR310Module// with 3.0 (or with 2.10 as alternative)ObjectMappermapper =JsonMapper.builder()// or different mapper for other format   .addModule(newParameterNamesModule())   .addModule(newJdk8Module())   .addModule(newJavaTimeModule())// and possibly other configuration, modules, then:   .build();

Alternatively, you can also auto-discover these modules with:

ObjectMappermapper =newObjectMapper();mapper.findAndRegisterModules();

Regardless of registration mechanism, after registration all functionality is available for all normal Jackson operations.

But do note that you should only either explicit OR automatic registration: DO NOT combine explicitand auto-registration. If you use both, only one of registrations will have effect.And selection of which one varies by module and settings:

• IfMapperFeature.IGNORE_DUPLICATE_MODULE_REGISTRATIONS is defined, the FIRST registration succeeds, rest ignored
  • Duplicates are detected using id provided byModule.getTypeId(); duplicate-detection requires that Module provides same for all instances (true for Modules provided by this repo)
• Otherwise all registrations are processed by the LAST one has effect as it has precedence over earlier registrations.

Also note that before Jackson 2.10, auto-registration would only register olderJSR310Module, and not newerJavaTimeModule -- this is due to backwards compatibility. This was changed in Jackson 2.10.

If you want "the other" version of the module but also use auto-registration, make sure toregister "other" module explicitly AFTER callingmapper.findAndRegisterModules().Call after works becausegetTypeId() provided by modules differs so they are not considered duplicates.

Following developers have committer access to this project.

• Authors
  • Nick Williams (beamerblvd@github) contributed Java 8 date/time module; still helps issues from time to time
  • Tatu Saloranta (@cowtowncoder) wrote the other 2 modules and maintains them for 2.x (in 3.0, integrated into corejackson-databind)
• Maintainers:
  • Michael O'Keeffe (kupci@github) is the current maintainer of Java 8 date/time module

SeeWiki for more information (javadocs).