RFR: jdk.classfile.transforms package cleanup + javadoc

[Brian Goetz]

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.)
  - 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.
  - Does CodeLocalsShifter::addLocal work in concert with the 
local-allocation feature of BlockBuilder?
  - Should explain why fork() exists

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.


On 9/12/2022 1:06 PM, Adam Sotona wrote:
>
> Hi,
>
> I’ve performed some cleanup, renaming and API unification in 
> jdk.classfile.transforms package.
>
> Plus added Javadoc with code snippets.
>
> Please let me know your comments:
>
> https://github.com/openjdk/jdk-sandbox/pull/36
>
> Thanks,
>
> Adam
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/classfile-api-dev/attachments/20220912/4a379cd5/attachment.htm>