JSTEP-6: "Big Rename" for Jackson 3.0

[Tatu Saloranta]

As some of you may recall, I have mentioned that a few core entities
will be renamed for Jackson 3.0. I have expanded the scope of these
changes over time, but have not done a good job documenting them --
there are Github issues, but even their coverage is a bit spotty.
So I decided I should write down some more details of changes.

So, here it is:

https://github.com/FasterXML/jackson-future-ideas/wiki/JSTEP-6

I will try to outline logic behind changes, to have some sort of
general idea; and will also include both completed work and further
plans.

I would be happy to get feedback on some specific naming choices too,
if anybody is interested, but I am not sure what would be a good way
to do that.
If you would like to participate, let me know -- we can have
discussions on this mailing list; create github issue(s) on particular
cases, whatever.

Also: alongside entity (class), method renaming, I will probably
tackle Maven/Java module/Java package renaming in near future as well.
My basic suggestion would be to just change ".jackson." with
".jackson3." and that'd be it, mostly -- more details on
https://github.com/FasterXML/jackson-future-ideas/wiki/JSTEP-1 .

But before commencing that, I will send another notification. It will
also probably not happen before releasing Jackson 2.12.2 (there are a
couple of important fixes to still release).

-+ Tatu +-

[Anbu Sampath]

Hi Tatu,

Today only I came to know about Google groups for Jackson. If it's too late for the proposal, please ignore my mail. 

While reading JSTEP-1, I noticed there is proposal for big name change with V3 as "org.jackson". So, Instead of adding version number in maven and package(".jackson." with ".jackson3."), Can we go with bigger name change mentioned in the proposal as "org.jackson" or something similar like "io.jackson" or "com.jackson". It clearly indicate and  different three generations of jackson.

• 1st gen  (2009-13) - org.codehaus.jackson 
• 2nd gen (2012-22) - com.fasterxml.jackson 
• 3rd -gen (2002+)   -  org.jackson

I understand the special case with jackson-annotations, but still one time of big change is acceptable instead of mix matching with versions. I feel like tools such as OpenWrite can help the developers to automate these changes down the line. So in future it might become usual to integrate such as tool as part of CI for library upgrade to fix breaking changes.

Regards

Anbu

[Tatu Saloranta]

On Wed, Jun 15, 2022 at 8:59 AM Anbu Sampath <anbu...@gmail.com> wrote:
>
> Hi Tatu,
>
> Today only I came to know about Google groups for Jackson. If it's too late for the proposal, please ignore my mail.
>
> While reading JSTEP-1, I noticed there is proposal for big name change with V3 as "org.jackson". So, Instead of adding version number in maven and package(".jackson." with ".jackson3."), Can we go with bigger name change mentioned in the proposal as "org.jackson" or something similar like "io.jackson" or "com.jackson". It clearly indicate and different three generations of jackson.
>
> 1st gen (2009-13) - org.codehaus.jackson
> 2nd gen (2012-22) - com.fasterxml.jackson
> 3rd -gen (2002+) - org.jackson
>
> I understand the special case with jackson-annotations, but still one time of big change is acceptable instead of mix matching with versions. I feel like tools such as OpenWrite can help the developers to automate these changes down the line. So in future it might become usual to integrate such as tool as part of CI for library upgrade to fix breaking changes.

Hi Anbu! Thank you for bringing this up -- I was about to send a
question to this list but hadn't figured out what all to ask.

How do others feel about this? I was thinking of going with

com.fasterxml.jackson3

as both Maven group id and Java package, but I guess it is a fair
point -- although techmocally (wrt how tools work) even one letter
difference is enough for namespacing, would it make more sense to make
a more visible change?
And if so, what should we use?

Couple of considerations:

- With Maven namespace other than "com.fasterxml." I'll need to
request access from Sonatype for their OSS repo. Not a big deal just
need to make sure not to select something someone else has control
over
- What about artifact ids? Should "jackson-databind" be re-used? v1.x
and v2.x happened to have different artifact ids because I felt 1.x
ones were not as good as they should but ones in 2.x are fine as they
are, I feel

-+ Tatu +-

> --
> You received this message because you are subscribed to the Google Groups "jackson-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to jackson-dev...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/jackson-dev/d490fec2-8262-4338-8f41-cae1e82ddd8an%40googlegroups.com.

[Tatu Saloranta]

Ok, here's some new developments wrt my thinking of Jackson 3 Big Renaming!
I updated the doc;

https://github.com/FasterXML/jackson-future-ideas/wiki/JSTEP-1

but basically after some discussions I became convinced that a
distinct new Maven Group Id / Java package name makes sense.
And of various .TLD's

jackson.tools

makes most sense to me; so much so that I registered it. For now:

http://jackson.tools

simply redirects to main Jackson github repo.

Anyway, at minimum this would mean that:

* Streaming would have Maven coordinates of "tools.jackson.core:jackson-core"
* Java package for core would be "tools.jackson.core.JsonParser" etc

with the exception that Jackson Annotations will continue to live at
their old address: while this can look
confusing it will avoid the hassle that we had with Jackson 1.x->2.x
wherein users had to duplicate annotations,
or, worse, would sometimes try using 1.x annotations instead of 2.x
(because Annotation class names were identical
and IDE auto-completion offered wrong ones).

This still leaves open the question of naming of actual Maven artifact
ids (jar names): should we:

1. Keep 2.x names -- why fix something that is not broken
("jackson-databind" works fine)
2. Make 3.x names unique to support use cases where jar names must be
unique (since 2.x and 3.x can otherwise co-exist).
So, "jackson-databind" would become "jackson3-databind"

I would like to hear from anyone who thinks that (2) is required: for
Jackson 1.x -> 2.x transition renaming was done for many (but not all)
artifacts due to 1.x names being sub-optimal ("jackson-mapper-asl" ->
"jackson-databind", "jackson-core-asl" -> "jackson-core"). We don't
have that issue any more.

-+ Tatu +-

[Michel Krämer]

Hi Tatu,

I like http://jackson.tools and the package name very much! Great idea! :-)

Regarding your open question. I'm not sure a unique package name (e.g. jackson-databind3) is necessary. If you manage your dependencies manually, you can always rename the jar. If you're using a build tool such as Gradle, the build tool should be able to handle artifacts with equal names. For example, I just had a look at the `lib` folder of one of my applications built with the gradle application plugin. It always appends the version number to the jar name, so jackson-databind.jar would become jackson-databind-3.0.0.jar anyway. I assume that other build tools do the same.

Cheers,
Michel

> To view this discussion on the web visit https://groups.google.com/d/msgid/jackson-dev/CAL4a10jRhG0CRXO7xShFYD2t%2B9Fwak1pWWkw23kq-HmQyVYWuw%40mail.gmail.com.

[Tatu Saloranta]

On Wed, Jun 29, 2022 at 9:04 PM 'Michel Krämer' via jackson-dev
<jacks...@googlegroups.com> wrote:
>
> Hi Tatu,
>
> I like http://jackson.tools and the package name very much! Great idea! :-)

Good! I am glad the idea was shared with me (now I need to check who
originally suggested it over at twitter :) ).

> Regarding your open question. I'm not sure a unique package name (e.g. jackson-databind3) is necessary. If you manage your dependencies manually, you can always rename the jar. If you're using a build tool such as Gradle, the build tool should be able to handle artifacts with equal names. For example, I just had a look at the `lib` folder of one of my applications built with the gradle application plugin. It always appends the version number to the jar name, so jackson-databind.jar would become jackson-databind-3.0.0.jar anyway. I assume that other build tools do the same.

Right, I think most robust general-purpose build/dependency management
tools use scoping by group-id correctly.
Maven and Gradle for sure.
And come to think of that, since version ranges will not overlap, even
just jar+version would remain unique for this purpose.

My concern I guess is whether there are significant outliers, or usage
patterns, where jar name uniqueness (without group id
or version) would be needed -- or put another way, 2.x and 3.x jars
could conflict.
But unless I hear from developers with such systems I should not
assume it is a general pattern.

-+ Tatu +-

> To view this discussion on the web visit https://groups.google.com/d/msgid/jackson-dev/8E4E68AC-CE95-4A68-84D1-060B12599AB7%40googlemail.com.