Contents
Jackson Release: 2.0
General
Version 2.0 is the first new major update for Jackson since the official 1.0 release. It was released March 25, 2012, about 5 months after 1.9 release
Since it is a major versions upgrade, it will not be plug-in backwards compatible with old code; instead, code using it must be recompiled. This incompatibility is explicit and intentional in that all code will move to new Java packages, and Maven group id will change as well. The reason for this is to both allow co-existence of Jackson 1.x and 2.x versions (which will allow potentially smooth, and always safe, upgrade): it will prevent "hidden" breakage that might occur when doing jar-only upgrades, and make need for recompilation (and hopefully limited source changes) explicit.
But the exact scope of all changes is not yet defined. This page, then, tries to organize all plans for changes.
Quicklinks
Since most of this page relate to bigger conceptual, packaging and development changes, parts of release notes are moved to separate pages:
Packaging, SCM, Build Changes
Changing Java packages
Jackson 1.x artifacts use following java packages:
core: org.codehaus.jackson (and some sub-packages)
mapper: org.codehaus.jackson.map mostly; also org.codehaus.jackson.node and org.codehaus.jackson.schema
jaxrs: org.codehaus.jackson.jaxrs
mrbean: org.codehaus.jackson.mrbean
smile: org.codehaus.jackson.smile
xc: org.codehaus.jackson.xc
These are divided in two separate groups: "core", which includes former 'core' and 'mapper' components; and then "other" that contains everything else.
For "core" group, changes are:
core: "core", "streaming" or "data" (data vs object): com.fasterxml.jackson.core
- While "streaming" would make sense otherwise, half of abstractions are not really for streaming, so "core" may be most approriate pkg name to use
NOTE: annotations need to be carved out -- maybe as com.fasterxml.jackson.annotation
mapper: "databind", "object" or "mapper"? So perhaps com.fasterxml.jackson.databind
Should "node" go under this level, or as sibling ('com.fasterxml.jackson.node')? Proposal: put under 'mapper': com.fasterxml.jackson.databind.node
How about 'schema' stuff? Probably similarly should go under: com.fasterxml.jackson.databind.schema
and others are be mapped as:
jaxrs: com.fasterxml.jackson.jaxrs.json (since we want to have providers for other formats as well)
mrbean: com.fasterxml.jackson.module.mrbean
smile: com.fasterxml.jackson.dataformat.smile
xc: com.fasterxml.jackson.module.jaxb
which also align with Maven group ids (see below). Idea is to generally use com.fasterxml.jackson as the ultimate root; but also divide functionality into sub-categories.
Extension modules (extensions that are registered using module interface) should use:
- "dataformat" for things that add support for other data formats than JSON using module in
- "datatype" for things that add support for 3rd party data types (like, say, Joda datetime lib)
- "jaxrs" for extensions related to JAX-RS (providers for dataformats)
- "module" for extension modules that do not belong under "dataformat", "datatype" or "jaxrs"
- "ext" for all other types of extensions
to use for other exte for non-module extension:
Changing Maven group id / artifact names
All Jackson 1.x Codehaus-originated artifacts use Maven group id of org.codehaus.jackson. Artifact names are as follows:
core: jackson-core-asl (and jackson-core-lgpl for LPGL licensed variant)
mapper: jackson-mapper-asl (and jackson-mapper-lgpl for LPGL licensed variant)
jaxrs: jackson-jaxrs
mrbean: jackson-mrbean
smile: jackson-smile
xc: jackson-xc
As mentioned above, Jackson 2.x uses Maven group and artifact ids that align with Java package name.
For core artifacts we will use group id com.fasterxml.jackson.core and artifact ids:
core: jackson-core -- and no separate ASL/LGPL artifacts or ids
annotations (that only depend on core): jackson-annotations
mapper: jackson-databind (including mapper-dependant annotations)
and for others use group ids using rules mentioned above:
jaxrs: com.fasterxml.jackson.jaxrs / jackson-jaxrs-json-provider (same group id for all JAX-RS providers; artifact ids differ)
mrbean: com.fasterxml.jackson.module / jackson-module-mrbean
smile: com.fasterxml.jackson.dataformat / jackson-dataformat-smile
xc: com.fasterxml.jackson.module / jackson-module-jaxb-annotations
Non-core packages should similar migrate to following Maven group ids as follows:
- "com.fasterxml.jackson.dataformat" for things that add support for other data formats than JSON using module interface
- "com.fasterxml.jackson.datatype" for things that add support for 3rd party data types (like, say, Joda datetime lib)
- "com.fasterxml.jackson.jaxrs" for extensions related to JAX-RS (providers for dataformats)
- "com.fasterxml.jackson.module" for extension modules that do not belong under "dataformat", "datatype" or "jaxrs"
- "com.fasterxml.jackson.ext" for all other types of extensions
Refactoring "non-core" jars out of core
Moving from Codehaus to Github
All source code has been moved to Github: Issue tracking (Jira) will remain at Codehaus, at least for now, since it is a superior system compared to issue tracker GH has.
New projects for Jackson 2.0 are:
- Core components:
- Data format modules:
- JAX-RS extensions:
- Language/3rd party lib datatypes:
- Other modules:
Afterburner (NEW with 2.0!)
Replacing Ant build with Maven
Done -- all new artifacts are built using Maven; this simplifies deployment of artifacts significantly.
API changes, misc.
This section lists other API-level changes from Jackson 1.x, in no particular order; both completed (if not mentioned) and potential (where explicitly noted)
ObjectMapper
registerModule: changed to return 'this' (ObjectMapper it is called on) -- this is binary-incompatible change so must be done with major version upgrade
- Other similar changes will be done where applicable, from 'void' to "this".
JsonSerializable
JsonSerializer now includes method 'serializeWithType()', which used to be in separate interface JsonSerializableWithType: by default, i
SerializationConfig.Feature, DeserializationConfig.Feature
Two main enumerations used for configuring serialization and deserialization settings have been refactored AND renamed, so that:
Features that were shared between the two, and which can NOT be changed on per-call basis, are now defined as MapperFeature: this includes fundamental annotation introspection settings
- Other features are included in two new Enums, with more convenient names:
DeserializationFeature (for former DeserializationConfig.Feature)
SerializationFeature (for former SerializationConfig.Feature)
Usage is otherwise similar, with respect to ObjectMapper, but it is now possible to reconfigure ObjectMapper and ObjectWriter as well, using:
ObjectWriter w = mapper.writer().with(SerializationFeature.INDENT_OUTPUT); ObjectReader r = mapper.reader().without(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);
More Immutability
One of half-done good ideas with 1.x is to try to make certain objects fully immutable, in somewhat functional style. This is a useful goal mostly for making multi-threaded operation simpler, safer and potentially slightly faster.
Completed changes:
Some objects that we probably won't/can't make fully immutable:
ObjectMapper: it seems impractical to try this, given both that we already have immutable "replacements" (ObjectReader, ObjectWriter), and because typically there has to be some small piece that is mutable to keep things easy to use (and often hide impl details of how immutable aspects work)
JsonFactory: we could probably get immutability working if ObjectMapper was the only user; but it may be difficult to get this to work for "direct" usage (i.e. Streaming Api use case)
Misc other API changes
Classes moved:
"TokenBuffer" is only used by mapper and was moved to 'jackson-databind' package from core: the main benefit is that this is 20kB less stuff in streaming-api package, and reduces/removes need for separate "mini" jar.
Classes removed:
CustomSerializerFactory, CustomDeserializerFactory removed: all functionality should be available through Module interface
Annotations moved:
JacksonInject, JsonFilter, JsonRootName JsonView moved to core annotations (since it has no dependencies to mapper package).
Functional changes
"Any setter" vs ignored properties
In 1.x, any properties defines as ignored using @JsonIgnore will also be blocked from being set using so-called "any setters". This only affects properties not passed via regular deserialization accessors (fields, setters, constructor parameters).
In 2.0, this will not be done; only properties defined using @JsonIgnoredProperties are excluded, but @JsonIgnore will not have any effect on things passed to any-setters.
Ideas for 1.x Compatibility features
It should be possible to create a module that implements AnnotationIntrospector (similar to JacksonAnnotationIntrospector), but one that uses Jackson 1.x annotations (which have mostly same names, but are located in different Java package). This could be called, say, Jackson1xAnnotationIntrospector.