Package org.spongepowered.asm.mixin.injection

Annotation Type Constant

@Documented
@Retention(RUNTIME)
public @interface Constant

The Constant annotation marks a single constant value which should be selected. This is used in accord with ModifyConstant, however the principles of this annotation are shared with At.args() when using the CONSTANT injection point.

Declaring multiple constant values within a single Constant annotation will not work and will cause the mixin to not apply.

Reminder: Micromixin-transformer (and any other transformer for that matter) can see which attributes of an annotation have been set and which have not. More specifically, the javac (TM) compiler does not include the default values of annotation attributes, which allows micromixin-transformer to infer that the absence of an attribute means that it has not been set (which in turn means that the attribute is ignored).

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
java.lang.Class<?>	classValue	Defines the Class constant values to match.
double	doubleValue	Specify a double constant value to match
float	floatValue	Specify a float constant value to match
int	intValue	Specify the integer constant value to match.
long	longValue	Specify a long constant value to match
boolean	nullValue	If true, null values are matched.
java.lang.String	slice	The id of the Slice that should be passed to the injection point to narrow down the amount of resulting matched instructions.
java.lang.String	stringValue	Defines the string constant values to match.

Element Detail

classValue

java.lang.Class<?> classValue

Defines the Class constant values to match.

Matches the LDC opcode.

Does not match GETSTATIC java/lang/Integer.TYPE or similar, which means that int.class or similar cannot be matched using this approach. This means that not primitive classes can be matched as "int.class" is represented using a GETSTATIC instruction in java bytecode. That being said, this behaviour could change in future versions of the spongeian mixin implementation or future versions of micromixin as this flaw is not directly documented in the spongeian documentation of this attribute.

Returns:

The Class constant to match.

Default:

void.class

doubleValue

double doubleValue

Specify a double constant value to match

Matches opcodes such as LDC or DCONST_0.

Returns:

The double constant to match

Default:

0.0

floatValue

float floatValue

Specify a float constant value to match

Matches opcodes such as LDC or FCONST_0.

Returns:

The float constant to match

Default:

0.0f

intValue

int intValue

Specify the integer constant value to match.

Matches opcodes such as LDC, BIPUSH or ICONST_0.

Due to how types work in java bytecode, this can also match booleans, bytes, shorts and chars, which do not have their own types and are always represented as integers.

The spongeian documentation does not explicitly guarantee matching booleans and chars - but the spongeian mixin implementation does permit it anyways and the current behaviour is unlikely to change.

Be careful, directives such as x == 0 or x <= 0 and other comparisons with the constant value 0 are compiled to their own dedicated opcodes, which means that this attribute cannot match 0 on it's own. HOWEVER, the spongeian mixin implementation provides tools to capture such constants anyways, but micromixin-transformer does not yet support these facilities.

Returns:

The integer constant to match

Default:

0

longValue

long longValue

Specify a long constant value to match

Matches opcodes such as LDC or LCONST_0. longValue() does not support matching ints, shorts, bytes, etc.

Returns:

The long constant to match

Default:

0L

nullValue

boolean nullValue

If true, null values are matched.

Matches the ACONST_NULL opcode.

Setting the attribute to false may result in undefined behaviour. It is rather recommended to plainly remove this attribute instead of defining it to false.

Matching null values is rather brittle due to the frequency of the null values. Aside from that the type of a null value is not well defined and must be inferred. This means that micromixin-transformer accepts any object types when paired with ModifyConstant. However, accepting and returning an object of type Object is still the recommended approach when capturing null values. That being said, other mixin implementations may behave differently and this property is not well tested.

Returns:

True to match null values, false otherwise.

Default:

false

slice

java.lang.String slice

The id of the Slice that should be passed to the injection point to narrow down the amount of resulting matched instructions. This should be the preferred way of selecting one specific instruction from a pool of otherwise similar instructions as this would be the least brittle option - provided the slices are not used carelessly.

Note that micromixin-transformer as well as the accompanying documentation only partly implements Slice.id() as well as slice(); significant derivations are to be expected between micromixin-transformer's behaviour (as well as the documented behaviour) and the spongeian transformer behaviour (as well as it's documentation). As such, usage of these attributes ought to be avoided in environments where usage of micromixin-transformer is expected and the spongeian documentation should be consulted before making use of this attribute.

Returns:

The id of the Slice to use, as per Slice.id().

Default:

""

stringValue

java.lang.String stringValue

Defines the string constant values to match.

Matches the LDC opcode.

The string value attribute must contain the entire string to match. Do note that smaller, more frequent, strings could be matched multiple times. If in doubt, you might want to make use of slice() to reduce the frequency in which a specific string is captured.

Returns:

The string constant to match

Default:

""