RFR: jdk.classfile.transforms package cleanup + javadoc

[Adam Sotona]

From: Brian Goetz <brian.goetz at oracle.com>
Date: Monday, 12 September 2022 20:17
To: Adam Sotona <adam.sotona at oracle.com>, classfile-api-dev at openjdk.org <classfile-api-dev at openjdk.org>
Subject: Re: RFR: jdk.classfile.transforms package cleanup + javadoc
This is a good improvement.  I have a few additional suggestions and questions:

 - The ClassRemapper spec talks about what it _doesn't_ map, rather than what it does.  We should characterize what it does do (e.g., for every ClassEntry referenced by an instruction, attribute, or metadata, map it to a new ClassEntry as per the contents of the map...)  It should also give a plain explanation of when you would use it (e.g., package renaming.)
Right, thanks, I’ll fix it.

 - You might want to give some example code for how to remap _all_ classes in package com.foo to com.bar -- this involves writing a Function that looks at prefixes.
There is such example “Sample use with map function”, however not enough described and highlighted. I’ll fix it.

 - Does CodeLocalsShifter::addLocal work in concert with the local-allocation feature of BlockBuilder?
Good point :)
It does not yet, however I’ll try to reimplement it to do so. We may get rid of counting the method arguments, local counting of “next”, use BlockBuilders instead of the “fork”, etc...

 - Should explain why fork() exists
Maybe it doesn’t need to exist :)

There is some question about what package these should go in.  I think the current package "transforms" is probably not optimal.

 - We could put these in the jdk.classfile package.  There's only a handful of them, I think this would be OK.
 - We could put these in some package that suggests these are reusable components that are not part of the classfile API.  But if so, "transform" is probably a little too specific, since one can imagine reusable components for other things (e.g., a pedantic verifying builder wrapper, an AttributeBuilder for foreign but common attributes, if such a thing existed, etc.)  "Util" is a little general (plus it has the feeling of a "dumping ground") but might be OK.  ASM also has "commons", which has the suggestion of "stuff contributed from the community", but that's also not a great name.

The ASM "util" package contains: Trace/CheckClassAdapter and friends, ClassPrinter, etc.  This feels in roughly the same category -- stuff you may want to use, but which are "components" rather than framework.
I think “commons” was not the best choice for ASM, as it represent common (the bottom) parts of complex APIs in many external Java libraries.
And I agree “transform” is too specific and “util” is probably too general.
My personal preference would be “components”.

Thanks,
Adam

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/classfile-api-dev/attachments/20220913/05255e77/attachment.htm>