OverMapped

OverMapped copied to clipboard

OverMapped - Allows a project to map methods, fields, or classes to new names.

Inspired by Java's inability to have two methods with same name but unique return types at compile-time.

A list of parameters follows in the format of 'pom parameter' - 'property'. A property is used as a command parameter, like `-Dmapping.maps=./maps.yml', while the parameter name is used in the pom's plugin-configuration.

maps - mapping.maps This is yaml file containing mapping changes. The top-level structure should be a list of relational arrays, or a single relational array. Each relational array can have four processed keys, members', classes', flags', and regex'. Relational arrays are processed in order of appearance. In each relational array, sections are processed in the order of classes', then members', then flags', then regex'. Each consecutive entry (as the set of previously described keys) is processed as if every entry is being applied on top of any previous entry.

MEMBERS (Fields / Methods)

A member entry requires a fully qualified name (delimited by slashes or
`/' ), the previous name, and a descriptor. Methods will use parenthesis
around the parameter list, with a trailing return type, to define their
description. Fields simply use their type as a descriptor. This
information is interpreted from the structure of the yaml. Member entries
are contained in a relational array. Each member entry may be a variety
of styles.

To map a method similarly-defined in multiple
classes, where some class may implement / extend said classes, but the
classes do not extend or implement each other, a multi-class mapping
needs to be used. The mappings should have a relational key of some
sequence. Each mapping should have a relational value of the new string-
name of the member. The relational key can be a relational pair of
strings, or a single-string with a (single) space-delimitation.

An example mapping both Runnable.run() and Thread.run()
* Note, in a real application, mapping Runnable.run() would automatically
  map Thread.run() as well, because Thread implements/extends Runnable.
  This would not work if the only definition was Thread.run(), as maps are
  only applied to classes that extend or implement the method's class.

members:
  [ java/lang/Runnable, java/lang/Thread ]:
    "run ()V": go

The above example is equally valid to using a relational pair in this
example:

members:
  [ java/lang/Runnable, java/lang/Thread ]:
    { "run": "()V" }: go

In a real application, it would be appropriate to only define the mapping
from Runnable, so only providing a single class-name as the relational
key to the maps is also correct, like in these two examples:

members:
  java/lang/Runnable:
    "run ()V": go

members:
  java/lang/Runnable:
    { "run": "()V" }: go

Similarly, the same styles will also work for fields (only when a
single-class is provided). These examples demonstrate renaming
ByteArrayInputStream.buf to buffer:

members:
  java/io/ByteArrayInputStream:
    "buf [B": buffer

members:
  java/io/ByteArrayInputStream:
    { buf: "[B" }: buffer

Specifically for fields, the description may be ommitted if there is only
a single field with the same name in the class:

members:
  java/io/ByteArrayInputStream:
    buf: buffer

members:
  java/io/ByteArrayInputStream:
    { buf: }: buffer

For situations that multiple fields in a particular style need to be
renamed, the relational key can be a relational pair of sequence to
starting name, where the relational value is a sequence of values to map
each respective entry, starting from the defined value. This style
follows the same behavior from omitting descriptions, such that all the
specified names need to be unique.

This example shows the general syntax:

members:
  java/package/Class:
    { [ FIELD_1, FIELD_2, FIELD_3, FIELD_4 ]: FIELD_2 }:
    - OTHER_FIELD_2
    - OTHER_FIELD_3

Assuming the appropriate Class existed, this would map the fields of
FIELD_2 and FIELD_3 to OTHER_FIELD_2 and OTHER_FIELD_3 respectively. If
FIELD_1 or FIELD_4 existed, they would not be affected. For repetitive
uses of these lists, anchors and aliases can be helpful.

CLASS NAMES

Classes are mapped simply by making the previous name a relational key
with the new name the relational value. An example mapping Runnable to
GoTime:

classes:
  "java/lang/Runnable": "java/lang/GoTime"

MEMBER FLAGS

Flags are changed by using the fully qualified description (see above) as
the relational key, with an integer as the relational value. These must be
exact matches to the members. An example flagging Thread.run() as
synthetic (this doesn't affect sub-classes!):

flags:
  "java/lang/Thread run ()V": 1001

REGEX (Class names)

Regex replacements are applied to class names. For every class name, the
given name has all matching sequences replaced with the specified
replacement string. Backslash ( \ ) and dollar-sign ( $ ) carry unique
meaning for escaping and matching groups respectively. Standard java
convention is used. An example that renames all classes in java.lang to
start with an underscore:

regex:
  "^java/lang/([^/]+)$": "java/lang/_$1"

Required

input - mapping.input This is the jar (or zip) file to read from.

Required

output - mapping.output This is the jar file to write to.

Default - the input file

original - mapping.original The file to copy the original input to, intended for usage when overwriting the input file.

Default - does not copy the original

cores - mapping.cores The number of cores to use. This must be at least 1 (intended to start no extra threads). Extra threads are used to process classes and perform some file-IO.

Default - 2

missing - mapping.missing This value dictates behavior when a class or member specified in the maps is not found. Valid options include:

IGNORE - takes no action.
WARN - outputs a message in the log.
FAIL - throws an exception, causing the goal to enter a 'failed' state.
VERBOSE - outputs detailed information when reading in classes and state
  information when a value is not found. This information is helpful for
  users to debug their maps.

Default - WARN

findParents - mapping.findParents This value indicates should attempt to detect when a mapped methods loses inheritance to a parent's (implemented interface or extended class) method. If a parent class has a method with the same signature, OverMapped will print a message indicating the method that is no longer overridden.

Default - false

correctEnums - mapping.correctEnums This value indicates that when the field-name of an Enum is changed, it should also change the internal "String" used to identify the Enum. No specific configuration is used, as all internal names will mirror that of the field used to store the enum.

This value changes the behavior of the static method in Enum,
Enum.valueOf(Class<T> enumType, String name), and in turn affects
serialization of the enum values (which is performed by internal-names).

Default - true