diff --git a/checkstyle.xml b/checkstyle.xml index e6297003..95d53e93 100644 --- a/checkstyle.xml +++ b/checkstyle.xml @@ -49,6 +49,10 @@ + + + + diff --git a/src/ap/java/org/spongepowered/tools/obfuscation/AnnotatedMixin.java b/src/ap/java/org/spongepowered/tools/obfuscation/AnnotatedMixin.java index 5f9dae2f..3ae8662d 100644 --- a/src/ap/java/org/spongepowered/tools/obfuscation/AnnotatedMixin.java +++ b/src/ap/java/org/spongepowered/tools/obfuscation/AnnotatedMixin.java @@ -60,7 +60,8 @@ import org.spongepowered.tools.obfuscation.validation.IMixinValidator; class AnnotatedMixin { /** - * Convenience class to store information about an {@link org.spongepowered.asm.mixin.Shadow}ed member's names + * Convenience class to store information about an + * {@link org.spongepowered.asm.mixin.Shadow}ed member's names */ class ShadowElementName { private final boolean hasPrefix; @@ -295,8 +296,10 @@ class AnnotatedMixin { } /** - * Validate method for {@link org.spongepowered.asm.mixin.Shadow} and {@link org.spongepowered.asm.mixin.Overwrite} registrations to check that - * only a single target is registered. Mixins containing annotated methods with these annotations cannot be multi-targetted. + * Validate method for {@link org.spongepowered.asm.mixin.Shadow} and + * {@link org.spongepowered.asm.mixin.Overwrite} registrations to check that + * only a single target is registered. Mixins containing annotated methods + * with these annotations cannot be multi-targetted. */ private boolean validateSingleTarget(String annotation, Element element) { if (this.targetRef == null || this.targets.size() > 1) { @@ -412,7 +415,8 @@ class AnnotatedMixin { } /** - * Register a {@link org.spongepowered.asm.mixin.injection.At} annotation and process the references + * Register a {@link org.spongepowered.asm.mixin.injection.At} annotation + * and process the references */ public void registerInjectionPoint(Element element, AnnotationMirror inject, AnnotationMirror at) { if (!AnnotatedMixins.getRemapValue(at)) { diff --git a/src/ap/java/org/spongepowered/tools/obfuscation/AnnotatedMixins.java b/src/ap/java/org/spongepowered/tools/obfuscation/AnnotatedMixins.java index ac8e6d2f..216f2553 100644 --- a/src/ap/java/org/spongepowered/tools/obfuscation/AnnotatedMixins.java +++ b/src/ap/java/org/spongepowered/tools/obfuscation/AnnotatedMixins.java @@ -60,7 +60,8 @@ import net.minecraftforge.srg2source.rangeapplier.SrgContainer; /** - * Mixin info manager, stores all of the mixin info during processing and also manages access to the srgs + * Mixin info manager, stores all of the mixin info during processing and also + * manages access to the srgs */ class AnnotatedMixins implements Messager { @@ -124,7 +125,8 @@ class AnnotatedMixins implements Messager { private SrgContainer srgs; /** - * True once we've tried to initialise the srgs, initially false so that we can do srg init lazily + * True once we've tried to initialise the srgs, initially false so that we + * can do srg init lazily */ private boolean initDone; @@ -158,7 +160,8 @@ class AnnotatedMixins implements Messager { } /** - * Lazy initialisation for srgs, so that we only initialise the srgs if they're actually required. + * Lazy initialisation for srgs, so that we only initialise the srgs if + * they're actually required. */ private boolean initSrgs() { if (!this.initDone) { @@ -365,7 +368,8 @@ class AnnotatedMixins implements Messager { * * @param mixinType Mixin class * @param method Injector method - * @param inject {@link org.spongepowered.asm.mixin.injection.Inject} annotation + * @param inject {@link org.spongepowered.asm.mixin.injection.Inject} + * annotation */ public void registerInjector(TypeElement mixinType, ExecutableElement method, AnnotationMirror inject) { AnnotatedMixin mixinClass = this.getMixin(mixinType); @@ -457,7 +461,8 @@ class AnnotatedMixins implements Messager { } /** - * Get a TypeElement representing another type in the current processing environment + * Get a TypeElement representing another type in the current processing + * environment */ public TypeElement getTypeElement(String name) { return this.processingEnv.getElementUtils().getTypeElement(name); diff --git a/src/ap/java/org/spongepowered/tools/obfuscation/InjectionObfuscationProcessor.java b/src/ap/java/org/spongepowered/tools/obfuscation/InjectionObfuscationProcessor.java index d300c2bf..8b2214f4 100644 --- a/src/ap/java/org/spongepowered/tools/obfuscation/InjectionObfuscationProcessor.java +++ b/src/ap/java/org/spongepowered/tools/obfuscation/InjectionObfuscationProcessor.java @@ -45,7 +45,8 @@ import org.spongepowered.asm.mixin.injection.Redirect; import org.spongepowered.tools.MirrorUtils; /** - * Annotation processor which finds {@link Inject} and {@link At} annotations in mixin classes and generates SRG mappings + * Annotation processor which finds {@link Inject} and {@link At} annotations in + * mixin classes and generates SRG mappings */ @SupportedSourceVersion(SourceVersion.RELEASE_6) @SupportedAnnotationTypes({ @@ -58,7 +59,9 @@ import org.spongepowered.tools.MirrorUtils; public class InjectionObfuscationProcessor extends MixinProcessor { /* (non-Javadoc) - * @see javax.annotation.processing.AbstractProcessor#process(java.util.Set, javax.annotation.processing.RoundEnvironment) + * @see javax.annotation.processing.AbstractProcessor + * #process(java.util.Set, + * javax.annotation.processing.RoundEnvironment) */ @Override public boolean process(Set annotations, RoundEnvironment roundEnv) { @@ -81,7 +84,8 @@ public class InjectionObfuscationProcessor extends MixinProcessor { } /** - * Searches for {@link Inject} annotations and registers them with their parent mixins + * Searches for {@link Inject} annotations and registers them with their + * parent mixins */ private void processInjectors(RoundEnvironment roundEnv, Class injectorClass) { for (Element elem : roundEnv.getElementsAnnotatedWith(injectorClass)) { diff --git a/src/ap/java/org/spongepowered/tools/obfuscation/MixinProcessor.java b/src/ap/java/org/spongepowered/tools/obfuscation/MixinProcessor.java index 6085825c..92b34eb7 100644 --- a/src/ap/java/org/spongepowered/tools/obfuscation/MixinProcessor.java +++ b/src/ap/java/org/spongepowered/tools/obfuscation/MixinProcessor.java @@ -42,7 +42,8 @@ public abstract class MixinProcessor extends AbstractProcessor { protected AnnotatedMixins mixins; /* (non-Javadoc) - * @see javax.annotation.processing.AbstractProcessor#init(javax.annotation.processing.ProcessingEnvironment) + * @see javax.annotation.processing.AbstractProcessor + * #init(javax.annotation.processing.ProcessingEnvironment) */ @Override public synchronized void init(ProcessingEnvironment processingEnv) { diff --git a/src/ap/java/org/spongepowered/tools/obfuscation/TargetObfuscationProcessor.java b/src/ap/java/org/spongepowered/tools/obfuscation/TargetObfuscationProcessor.java index d01a37d7..a8b7c232 100644 --- a/src/ap/java/org/spongepowered/tools/obfuscation/TargetObfuscationProcessor.java +++ b/src/ap/java/org/spongepowered/tools/obfuscation/TargetObfuscationProcessor.java @@ -44,7 +44,8 @@ import org.spongepowered.asm.mixin.Shadow; import org.spongepowered.tools.MirrorUtils; /** - * Annotation processor which finds {@link Shadow} and {@link Overwrite} annotations in mixin classes and generates SRG mappings + * Annotation processor which finds {@link Shadow} and {@link Overwrite} + * annotations in mixin classes and generates SRG mappings */ @SupportedSourceVersion(SourceVersion.RELEASE_6) @SupportedAnnotationTypes({ "org.spongepowered.asm.mixin.Mixin", "org.spongepowered.asm.mixin.Shadow", "org.spongepowered.asm.mixin.Overwrite" }) @@ -52,7 +53,9 @@ import org.spongepowered.tools.MirrorUtils; public class TargetObfuscationProcessor extends MixinProcessor { /* (non-Javadoc) - * @see javax.annotation.processing.AbstractProcessor#process(java.util.Set, javax.annotation.processing.RoundEnvironment) + * @see javax.annotation.processing.AbstractProcessor + * #process(java.util.Set, + * javax.annotation.processing.RoundEnvironment) */ @Override public boolean process(Set annotations, RoundEnvironment roundEnv) { @@ -74,7 +77,8 @@ public class TargetObfuscationProcessor extends MixinProcessor { } /** - * Searches for {@link Shadow} annotations and registers them with their parent mixins + * Searches for {@link Shadow} annotations and registers them with their + * parent mixins */ private void processShadows(RoundEnvironment roundEnv) { for (Element elem : roundEnv.getElementsAnnotatedWith(Shadow.class)) { @@ -97,7 +101,8 @@ public class TargetObfuscationProcessor extends MixinProcessor { } /** - * Searches for {@link Overwrite} annotations and registers them with their parent mixins + * Searches for {@link Overwrite} annotations and registers them with their + * parent mixins */ private void processOverwrites(RoundEnvironment roundEnv) { for (Element elem : roundEnv.getElementsAnnotatedWith(Overwrite.class)) { diff --git a/src/main/java/org/spongepowered/asm/launch/MixinTweaker.java b/src/main/java/org/spongepowered/asm/launch/MixinTweaker.java index 25578e0f..b3bc881c 100644 --- a/src/main/java/org/spongepowered/asm/launch/MixinTweaker.java +++ b/src/main/java/org/spongepowered/asm/launch/MixinTweaker.java @@ -41,8 +41,9 @@ import net.minecraft.launchwrapper.LaunchClassLoader; /** - * TweakClass for running mixins in production. Being a tweaker ensures that we get injected into the AppClassLoader but does mean that we will - * need to inject the FML coremod by hand if running under FML. + * TweakClass for running mixins in production. Being a tweaker ensures that we + * get injected into the AppClassLoader but does mean that we will need to + * inject the FML coremod by hand if running under FML. */ public class MixinTweaker implements ITweaker { @@ -52,17 +53,21 @@ public class MixinTweaker implements ITweaker { private final File container; /** - * If running under FML, we will attempt to inject any coremod specified in the metadata, FML's CoremodManager returns an ITweaker instance - * which is the "handle" to the injected mod, we will need to proxy calls through to the wrapper. If initialisation fails (for example if we are - * not running under FML or if an FMLCorePlugin key is not specified in the metadata) then this handle will be NULL and the tweaker will attempt - * to start the Mixin subsystem automatically by looking for a MixinConfigs key in the jar metadata, this should be a comma-separated list of - * mixin config JSON file names. + * If running under FML, we will attempt to inject any coremod specified in + * the metadata, FML's CoremodManager returns an ITweaker instance which is + * the "handle" to the injected mod, we will need to proxy calls through to + * the wrapper. If initialisation fails (for example if we are not running + * under FML or if an FMLCorePlugin key is not specified in the metadata) + * then this handle will be NULL and the tweaker will attempt to start the + * Mixin subsystem automatically by looking for a MixinConfigs key in the + * jar metadata, this should be a comma-separated list of mixin config JSON + * file names. */ private final ITweaker fmlWrapper; /** - * If FML init fails the tweaker will look for configs, if it finds any then it will set this flag to signify that it needs to inject the - * transformer + * If FML init fails the tweaker will look for configs, if it finds any then + * it will set this flag to signify that it needs to inject the transformer */ private boolean injectTransformer; @@ -119,7 +124,8 @@ public class MixinTweaker implements ITweaker { } /* (non-Javadoc) - * @see net.minecraft.launchwrapper.ITweaker#acceptOptions(java.util.List, java.io.File, java.io.File, java.lang.String) + * @see net.minecraft.launchwrapper.ITweaker#acceptOptions(java.util.List, + * java.io.File, java.io.File, java.lang.String) */ @Override public void acceptOptions(List args, File gameDir, File assetsDir, String profile) { @@ -139,7 +145,8 @@ public class MixinTweaker implements ITweaker { } /* (non-Javadoc) - * @see net.minecraft.launchwrapper.ITweaker#injectIntoClassLoader(net.minecraft.launchwrapper.LaunchClassLoader) + * @see net.minecraft.launchwrapper.ITweaker#injectIntoClassLoader( + * net.minecraft.launchwrapper.LaunchClassLoader) */ @Override public void injectIntoClassLoader(LaunchClassLoader classLoader) { diff --git a/src/main/java/org/spongepowered/asm/mixin/Implements.java b/src/main/java/org/spongepowered/asm/mixin/Implements.java index 5820c459..dc0612d9 100644 --- a/src/main/java/org/spongepowered/asm/mixin/Implements.java +++ b/src/main/java/org/spongepowered/asm/mixin/Implements.java @@ -30,7 +30,8 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Pseudo-implements decorator for Mixins with conflicting methods in a superclass to soft-implement an interface + * Pseudo-implements decorator for Mixins with conflicting methods in a + * superclass to soft-implement an interface */ @Target(ElementType.TYPE) @Retention(RetentionPolicy.CLASS) diff --git a/src/main/java/org/spongepowered/asm/mixin/Interface.java b/src/main/java/org/spongepowered/asm/mixin/Interface.java index e2f337e1..c3f13551 100644 --- a/src/main/java/org/spongepowered/asm/mixin/Interface.java +++ b/src/main/java/org/spongepowered/asm/mixin/Interface.java @@ -37,13 +37,15 @@ import java.lang.annotation.Target; public @interface Interface { /** - * Interface that the parent {@link Implements} indicates the mixin implements. The interface will be hot-patched onto the target class as part - * of the mixin application. + * Interface that the parent {@link Implements} indicates the mixin + * implements. The interface will be hot-patched onto the target class as + * part of the mixin application. */ public Class iface(); /** - * [Required] prefix for implementing interface methods. Works similarly to {@link Shadow} prefixes, but must end with a dollar sign ($) + * [Required] prefix for implementing interface methods. Works similarly to + * {@link Shadow} prefixes, but must end with a dollar sign ($) */ public String prefix(); diff --git a/src/main/java/org/spongepowered/asm/mixin/Mixin.java b/src/main/java/org/spongepowered/asm/mixin/Mixin.java index ab2cfd90..ada11fe3 100644 --- a/src/main/java/org/spongepowered/asm/mixin/Mixin.java +++ b/src/main/java/org/spongepowered/asm/mixin/Mixin.java @@ -42,24 +42,34 @@ public @interface Mixin { public Class[] value() default { }; /** - * Since specifying targets in {@link #value} requires that the classes be publicly visible, this property is provided to allow package-private, - * anonymous innner, and private inner classes to be referenced. Referencing an otherwise public class using this property is an error condition - * and will throw an exception at runtime. It is completely fine to specify both public and private targets for the same mixin however. + * Since specifying targets in {@link #value} requires that the classes be + * publicly visible, this property is provided to allow package-private, + * anonymous innner, and private inner classes to be referenced. Referencing + * an otherwise public class using this property is an error condition and + * will throw an exception at runtime. It is completely fine to specify both + * public and private targets for the same mixin however. */ public String[] targets() default { }; /** - * Priority for the mixin, relative to other mixins targetting the same classes + * Priority for the mixin, relative to other mixins targetting the same + * classes */ public int priority() default 1000; /** - * By default, the annotation processor will attempt to locate an obfuscation mapping for all {@link Shadow} and - * {@link org.spongepowered.asm.mixin.injection.Inject} annotated members since it is anticipated that in general the target of a {@link Mixin} - * will be an obfuscated class and all annotated members will need to be added to the obfuscation table. However since it is possible to also - * apply mixins to non-obfuscated targets it may be desirable to suppress the compiler warnings which would otherwise be generated. This can be - * done on an individual member basis by setting remap to false on the individual annotations, or disabled for the entire - * mixin by setting the value here to false. Doing so will cause the annotation processor to skip all annotations in this mixin when + * By default, the annotation processor will attempt to locate an + * obfuscation mapping for all {@link Shadow} and + * {@link org.spongepowered.asm.mixin.injection.Inject} annotated members + * since it is anticipated that in general the target of a {@link Mixin} + * will be an obfuscated class and all annotated members will need to be + * added to the obfuscation table. However since it is possible to also + * apply mixins to non-obfuscated targets it may be desirable to suppress + * the compiler warnings which would otherwise be generated. This can be + * done on an individual member basis by setting remap to + * false on the individual annotations, or disabled for the entire + * mixin by setting the value here to false. Doing so will cause + * the annotation processor to skip all annotations in this mixin when * building the obfuscation table. */ public boolean remap() default true; diff --git a/src/main/java/org/spongepowered/asm/mixin/Overwrite.java b/src/main/java/org/spongepowered/asm/mixin/Overwrite.java index f0b455ad..70bff267 100644 --- a/src/main/java/org/spongepowered/asm/mixin/Overwrite.java +++ b/src/main/java/org/spongepowered/asm/mixin/Overwrite.java @@ -30,17 +30,25 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - *

Annotation used to indicate a mixin class member which must overwrite an obfuscated method in the target class.

+ *

Annotation used to indicate a mixin class member which must overwrite an + * obfuscated method in the target class.

* - *

The default behaviour of mixin classes when merging mixin methods is to replace methods in the target class which already exist, and simply add - * any other methods to the target class body as new members. This default behaviour allows methods in the target class to be easily overwritten by - * simply creating a method in the mixin with a signature matching the member to be overwritten.

+ *

The default behaviour of mixin classes when merging mixin methods is to + * replace methods in the target class which already exist, and simply add any + * other methods to the target class body as new members. This default behaviour + * allows methods in the target class to be easily overwritten by simply + * creating a method in the mixin with a signature matching the member to be + * overwritten.

* - *

This is not sufficient for obfuscated methods however, since as mixins traverse the obfuscation boundary, this association with the target - * method is lost because the method name will change. The {@link Overwrite} annotation is used to indicate to the annotation processor that this - * method is intended to overwrite a member in the target class, and should therefore be added to the obfuscation table.

+ *

This is not sufficient for obfuscated methods however, since as mixins + * traverse the obfuscation boundary, this association with the target method is + * lost because the method name will change. The {@link Overwrite} annotation is + * used to indicate to the annotation processor that this method is intended to + * overwrite a member in the target class, and should therefore be added to the + * obfuscation table.

* - *

Adding this annotation to a non-obfuscated method will cause the annotation processor to raise an error at compile time.

+ *

Adding this annotation to a non-obfuscated method will cause the + * annotation processor to raise an error at compile time.

*/ @Target({ ElementType.METHOD }) @Retention(RetentionPolicy.RUNTIME) diff --git a/src/main/java/org/spongepowered/asm/mixin/Shadow.java b/src/main/java/org/spongepowered/asm/mixin/Shadow.java index 7694fa42..f2283cb2 100644 --- a/src/main/java/org/spongepowered/asm/mixin/Shadow.java +++ b/src/main/java/org/spongepowered/asm/mixin/Shadow.java @@ -30,23 +30,31 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Used to indicate a Mixin class member which is acting as a placeholder for a method or field in the target class + * Used to indicate a Mixin class member which is acting as a placeholder for a + * method or field in the target class */ @Target({ ElementType.METHOD, ElementType.FIELD }) @Retention(RetentionPolicy.RUNTIME) public @interface Shadow { + // CHECKSTYLE:OFF /** - *

In general, shadow methods can be declared using their name in the target class as you would expect, however we run into a problem when we - * want to mix in a method with the same name and arguments, but a different return type to the shadow method. While the JVM itself will happily - * support methods with signatures that differ only on return type, the compiler itself does not. This poses a problem, since we have no way to + *

In general, shadow methods can be declared using their name in the + * target class as you would expect, however we run into a problem when we + * want to mix in a method with the same name and arguments, but a different + * return type to the shadow method. While the JVM itself will happily + * support methods with signatures that differ only on return type, the + * compiler itself does not. This poses a problem, since we have no way to * leverage this behaviour since our mixin class will not compile.

* - *

To circumvent this compiler limitation, the prefix option can be used. By specifying a prefix for the shadow method, it is subsequently - * possible to compile the mixin class, the specified prefix will then be stripped from the method name prior to applying the mixin, and - * everything will work as expected. You may either use the default prefix: "shadow$", or you may specify your own. It is good practice to - * specify the prefix if you are using it, regardless of whether you use the default or not. For example consider the intrinsic readability of - * the following snippets

: + *

To circumvent this compiler limitation, the prefix option can be used. + * By specifying a prefix for the shadow method, it is subsequently possible + * to compile the mixin class, the specified prefix will then be stripped + * from the method name prior to applying the mixin, and everything will + * work as expected. You may either use the default prefix: "shadow$", or + * you may specify your own. It is good practice to specify the prefix if + * you are using it, regardless of whether you use the default or not. For + * example consider the intrinsic readability of the following snippets

: * *
      *     @Shadow abstract void someMethod(int arg1, int arg2);
@@ -55,22 +63,34 @@ public @interface Shadow {
      *     @Shadow(prefix = "foo$") abstract void foo$someMethod(int arg1, int arg2);
      * 
* - *

All of these declarations are semantically equivalent, however the third and fourth are the most expressive in terms of making their - * intentions clear, and thus specifying prefix is recommended, since it aids readability and maintainability.

+ *

All of these declarations are semantically equivalent, however the + * third and fourth are the most expressive in terms of making their + * intentions clear, and thus specifying prefix is recommended, since it + * aids readability and maintainability.

* - *

Note that specifying a prefix does not enforce use of the prefix, the behaviour of prefix is such that the prefix - * will be stripped from the start of the method name as long as the method name actually starts with the prefix! This has important - * repercussions since if the annotation value does not match the method prefix then no renaming will take place likey resulting in - * a failure state indicated by an {@link InvalidMixinException} at run time.

+ *

Note that specifying a prefix does not enforce use of + * the prefix, the behaviour of prefix is such that the prefix will + * be stripped from the start of the method name as long as the method + * name actually starts with the prefix! This has important + * repercussions since if the annotation value does not match the method + * prefix then no renaming will take place likey resulting in a + * failure state indicated by an {@link InvalidMixinException} at run + * time.

*/ public String prefix() default "shadow$"; + // CHECKSTYLE:ON /** - * By default, the annotation processor will attempt to locate an obfuscation mapping for all {@link Shadow} methods since it is anticipated that - * in general the target of a {@link Shadow} annotation will be an obfuscated field or method in the target class. However since it is possible - * to also apply mixins to non-obfuscated targets (or non-obfuscated methods in obfuscated targets, such as methods added by Forge) it may be - * desirable to suppress the compiler warning which would otherwise be generated. Setting this value to false will cause the annotation - * processor to skip this annotation when attempting to build the obfuscation table for the mixin. + * By default, the annotation processor will attempt to locate an + * obfuscation mapping for all {@link Shadow} methods since it is + * anticipated that in general the target of a {@link Shadow} annotation + * will be an obfuscated field or method in the target class. However since + * it is possible to also apply mixins to non-obfuscated targets (or non- + * obfuscated methods in obfuscated targets, such as methods added by Forge) + * it may be desirable to suppress the compiler warning which would + * otherwise be generated. Setting this value to false will cause + * the annotation processor to skip this annotation when attempting to build + * the obfuscation table for the mixin. */ public boolean remap() default true; } diff --git a/src/main/java/org/spongepowered/asm/mixin/extensibility/IMixinConfigPlugin.java b/src/main/java/org/spongepowered/asm/mixin/extensibility/IMixinConfigPlugin.java index c38d961d..8e31119e 100644 --- a/src/main/java/org/spongepowered/asm/mixin/extensibility/IMixinConfigPlugin.java +++ b/src/main/java/org/spongepowered/asm/mixin/extensibility/IMixinConfigPlugin.java @@ -30,14 +30,19 @@ import java.util.Set; import org.objectweb.asm.tree.ClassNode; /** - *

A companion plugin for a mixin configuration object. Objects implementing this interface get some limited power of veto over the mixin load - * process as well as an opportunity to apply their own transformations to the target class pre- and post-transform. Since all methods in this class - * are called indirectly from the transformer, the same precautions as for writing class transformers should be taken. Implementors should take care - * to not reference any game classes, and avoid referencing other classes in their own mod except those specificially designed to be available at - * early startup, such as coremod classes or other standalone bootstrap objects.

+ *

A companion plugin for a mixin configuration object. Objects implementing + * this interface get some limited power of veto over the mixin load process as + * well as an opportunity to apply their own transformations to the target class + * pre- and post-transform. Since all methods in this class are called + * indirectly from the transformer, the same precautions as for writing class + * transformers should be taken. Implementors should take care to not reference + * any game classes, and avoid referencing other classes in their own mod except + * those specificially designed to be available at early startup, such as + * coremod classes or other standalone bootstrap objects.

* - *

Instances of plugins are created by specifying the "plugin" key in the mixin config JSON as the fully-qualified class name of a class - * implementing this interface.

+ *

Instances of plugins are created by specifying the "plugin" key in the + * mixin config JSON as the fully-qualified class name of a class implementing + * this interface.

*/ public interface IMixinConfigPlugin { @@ -49,41 +54,53 @@ public interface IMixinConfigPlugin { public abstract void onLoad(String mixinPackage); /** - * Called only if the "referenceMap" key in the config is not set. This allows the refmap file name to be supplied by the plugin - * programatically if desired. Returning null will revert to the default behaviour of using the default refmap json file. + * Called only if the "referenceMap" key in the config is not set. + * This allows the refmap file name to be supplied by the plugin + * programatically if desired. Returning null will revert to + * the default behaviour of using the default refmap json file. * * @return Path to the refmap resource or null to revert to the default */ public abstract String getRefMapperConfig(); /** - * Called during mixin intialisation, allows this plugin to control whether a specific will be applied to the specified target. Returning false - * will remove the target from the mixin's target set, and if all targets are removed then the mixin will not be applied at all. + * Called during mixin intialisation, allows this plugin to control whether + * a specific will be applied to the specified target. Returning false will + * remove the target from the mixin's target set, and if all targets are + * removed then the mixin will not be applied at all. * * @param targetClassName Fully qualified class name of the target class * @param mixinClassName Fully qualified class name of the mixin - * @return True to allow the mixin to be applied, or false to remove it from target's mixin set + * @return True to allow the mixin to be applied, or false to remove it from + * target's mixin set */ public abstract boolean shouldApplyMixin(String targetClassName, String mixinClassName); /** - * Called after all configurations are initialised, this allows this plugin to observe classes targetted by other mixin configs and optionally - * remove targets from its own set. The set myTargets is a direct view of the targets collection in this companion config and keys may be removed - * from this set to suppress mixins in this config which target the specified class. Adding keys to the set will have no effect. + * Called after all configurations are initialised, this allows this plugin + * to observe classes targetted by other mixin configs and optionally remove + * targets from its own set. The set myTargets is a direct view of the + * targets collection in this companion config and keys may be removed from + * this set to suppress mixins in this config which target the specified + * class. Adding keys to the set will have no effect. * * @param myTargets Target class set from the companion config - * @param otherTargets Target class set incorporating targets from all other configs, read-only + * @param otherTargets Target class set incorporating targets from all other + * configs, read-only */ public abstract void acceptTargets(Set myTargets, Set otherTargets); /** - * After mixins specified in the configuration have been processed, this method is called to allow the plugin to add any additional mixins to - * load. It should return a list of mixin class names or return null if the plugin does not wish to append any mixins of its own. + * After mixins specified in the configuration have been processed, this + * method is called to allow the plugin to add any additional mixins to + * load. It should return a list of mixin class names or return null if the + * plugin does not wish to append any mixins of its own. */ public abstract List getMixins(); /** - * Called immediately before a mixin is applied to a target class, allows any pre-application transformations to be applied + * Called immediately before a mixin is applied to a target class, + * allows any pre-application transformations to be applied. * * @param targetClassName Transformed name of the target class * @param targetClass Target class tree @@ -93,7 +110,8 @@ public interface IMixinConfigPlugin { public abstract void preApply(String targetClassName, ClassNode targetClass, String mixinClassName, IMixinInfo mixinInfo); /** - * Called immediately after a mixin is applied to a target class, allows any post-application transformations to be applied + * Called immediately after a mixin is applied to a target class, + * allows any post-application transformations to be applied. * * @param targetClassName Transformed name of the target class * @param targetClass Target class tree diff --git a/src/main/java/org/spongepowered/asm/mixin/extensibility/IMixinInfo.java b/src/main/java/org/spongepowered/asm/mixin/extensibility/IMixinInfo.java index 9d33ac0e..71d9518d 100644 --- a/src/main/java/org/spongepowered/asm/mixin/extensibility/IMixinInfo.java +++ b/src/main/java/org/spongepowered/asm/mixin/extensibility/IMixinInfo.java @@ -51,7 +51,8 @@ public interface IMixinInfo { public abstract byte[] getClassBytes(); /** - * True if the superclass of the mixin is not the direct superclass of one or more targets + * True if the superclass of the mixin is not the direct superclass + * of one or more targets. */ public abstract boolean isDetachedSuper(); diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/At.java b/src/main/java/org/spongepowered/asm/mixin/injection/At.java index a0e9763a..d2985e15 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/At.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/At.java @@ -28,12 +28,18 @@ import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; /** - * Annotation for specifying the type of {@link InjectionPoint} to use to perform an {@link Inject} process. This annotation allows the - * {@link InjectionPoint} class to be specified, as well as arguments to be passed to the {@link InjectionPoint} instance to configure it. The data - * contained in the annotation are wrapped into a {@link org.spongepowered.asm.mixin.injection.struct.InjectionInfo InjectionInfo} object before - * being passed to the {@link InjectionPoint} for parsing. All values are optional apart from {@link #value}, which specifies the type of - * {@link InjectionPoint} to use. All other parameters depend on the InjectionPoint chosen, and the javadoc for each {@link InjectionPoint} class - * should be consulted for the meaning of the argument to that particular class. A general description of each parameter is provided below. + * Annotation for specifying the type of {@link InjectionPoint} to use to + * perform an {@link Inject} process. This annotation allows the + * {@link InjectionPoint} class to be specified, as well as arguments to be + * passed to the {@link InjectionPoint} instance to configure it. The data + * contained in the annotation are wrapped into a + * {@link org.spongepowered.asm.mixin.injection.struct.InjectionInfo + * InjectionInfo} object before being passed to the {@link InjectionPoint} for + * parsing. All values are optional apart from {@link #value}, which specifies + * the type of {@link InjectionPoint} to use. All other parameters depend on the + * InjectionPoint chosen, and the javadoc for each {@link InjectionPoint} class + * should be consulted for the meaning of the argument to that particular class. + * A general description of each parameter is provided below. */ @Retention(RetentionPolicy.RUNTIME) public @interface At { @@ -48,67 +54,87 @@ public @interface At { } /** - *

Type of {@link InjectionPoint} to use. Can be a built-in class or the fully-qualified name of a custom class which extends + *

Type of {@link InjectionPoint} to use. Can be a built-in class or the + * fully-qualified name of a custom class which extends * {@link InjectionPoint}.

* - *

Built-in types are {@link org.spongepowered.asm.mixin.injection.points.MethodHead HEAD}, + *

Built-in types are + * {@link org.spongepowered.asm.mixin.injection.points.MethodHead HEAD}, * {@link org.spongepowered.asm.mixin.injection.points.BeforeReturn RETURN}, * {@link org.spongepowered.asm.mixin.injection.points.BeforeInvoke INVOKE}, - * {@link org.spongepowered.asm.mixin.injection.points.BeforeFieldAccess FIELD}, + * {@link org.spongepowered.asm.mixin.injection.points.BeforeFieldAccess + * FIELD}, * {@link org.spongepowered.asm.mixin.injection.points.BeforeNew NEW}, - * {@link org.spongepowered.asm.mixin.injection.points.BeforeStringInvoke INVOKE_STRING} and - * {@link org.spongepowered.asm.mixin.injection.points.JumpInsnPoint JUMP}. See the javadoc for each type for more details on the scheme used by - * each injection point.

+ * {@link org.spongepowered.asm.mixin.injection.points.BeforeStringInvoke + * INVOKE_STRING} and + * {@link org.spongepowered.asm.mixin.injection.points.JumpInsnPoint JUMP}. + * See the javadoc for each type for more details on the scheme used by each + * injection point.

*/ public String value(); /** - * Shift type for returned opcodes. For example use {@link At.Shift#AFTER AFTER} with an INVOKE InjectionPoint to move the returned opcodes to - * after the invoation. Use {@link At.Shift#BY BY} in conjunction with the {@link #by} parameter to shift by an arbitrary number of + * Shift type for returned opcodes. For example use {@link At.Shift#AFTER + * AFTER} with an INVOKE InjectionPoint to move the returned opcodes to + * after the invoation. Use {@link At.Shift#BY BY} in conjunction + * with the {@link #by} parameter to shift by an arbitrary number of * opcodes. */ public Shift shift() default Shift.NONE; /** - * If {@link #shift} is specified as {@link At.Shift#BY BY}, specifies the number of opcodes to shift by (negative numbers are allowed). + * If {@link #shift} is specified as {@link At.Shift#BY BY}, specifies the + * number of opcodes to shift by (negative numbers are allowed). */ public int by() default 0; /** - *

The named arguments list is used to expand the scope of the annotation beyond the fixed values below in order to accommodate the + *

The named arguments list is used to expand the scope of the + * annotation beyond the fixed values below in order to accommodate the * needs of custom injection point classes. */ public String[] args() default { }; /** - * Target member used by INVOKE, INVOKE_STRING and FIELD. This must be specified as a fully-qualified member path including the class name - * and signature. Failing to fully-qualify the target member will result in an error at obfuscation time. + * Target member used by INVOKE, INVOKE_STRING and FIELD. This must be + * specified as a fully-qualified member path including the class name + * and signature. Failing to fully-qualify the target member will result in + * an error at obfuscation time. * * @return target reference for supported InjectionPoint types */ public String target() default ""; /** - * Ordinal offset. Many InjectionPoints will return every opcode matching their criteria, specifying ordinal allows a particular opcode - * to be identified from the returned list. The default value of -1 does not alter the behaviour and returns all matching opcodes. Specifying a - * value of 0 or higher returns only the requested opcode (if one exists: for example specifying an ordinal of 4 when only 2 opcodes are - * matched by the InjectionPoint is not going to work particularly well!) + * Ordinal offset. Many InjectionPoints will return every opcode matching + * their criteria, specifying ordinal allows a particular opcode to + * be identified from the returned list. The default value of -1 does not + * alter the behaviour and returns all matching opcodes. Specifying a value + * of 0 or higher returns only the requested opcode (if one exists: + * for example specifying an ordinal of 4 when only 2 opcodes are matched by + * the InjectionPoint is not going to work particularly well!) * * @return ordinal value for supported InjectionPoint types */ public int ordinal() default -1; /** - * Target opcode for FIELD and JUMP InjectionPoints. See the javadoc for the relevant injection point for more details. + * Target opcode for FIELD and JUMP InjectionPoints. See the javadoc for the + * relevant injection point for more details. */ public int opcode() default -1; /** - * By default, the annotation processor will attempt to locate an obfuscation mapping for the {@link #target} member and any other {@link #args} - * known to contain potentially obfuscated references, since it is anticipated that in general the target of an {@link At} annotation will be an - * obfuscated method or field. However since it is also possible that the target is a non-obfuscated reference it may be necessary to suppress the - * compiler error which would otherwise be generated. Setting this value to false will cause the annotation processor to skip this - * annotation when attempting to build the obfuscation table for the mixin. + * By default, the annotation processor will attempt to locate an + * obfuscation mapping for the {@link #target} member and any other + * {@link #args} known to contain potentially obfuscated references, since + * it is anticipated that in general the target of an {@link At} annotation + * will be an obfuscated method or field. However since it is also possible + * that the target is a non-obfuscated reference it may be necessary to + * suppress the compiler error which would otherwise be generated. Setting + * this value to false will cause the annotation processor to skip + * this annotation when attempting to build the obfuscation table for the + * mixin. */ public boolean remap() default true; } diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/Inject.java b/src/main/java/org/spongepowered/asm/mixin/injection/Inject.java index f4925168..e4b03a87 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/Inject.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/Inject.java @@ -30,42 +30,56 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Specifies that this mixin method should inject a callback (or callbacks) to itself in the target method(s) identified by {@link #method}. + * Specifies that this mixin method should inject a callback (or + * callbacks) to itself in the target method(s) identified by + * {@link #method}. */ @Target({ ElementType.METHOD }) @Retention(RetentionPolicy.RUNTIME) public @interface Inject { /** - * String representation of a {@link org.spongepowered.asm.mixin.injection.struct.MemberInfo MemberInfo} which identifies the target method. + * String representation of a + * {@link org.spongepowered.asm.mixin.injection.struct.MemberInfo + * MemberInfo} which identifies the target method. */ public String method(); /** - * Array of {@link At} annotations which describe the {@link InjectionPoint}s in the target method. Allows one or more callbacks to be injected in - * the target method + * Array of {@link At} annotations which describe the + * {@link InjectionPoint}s in the target method. Allows one or more + * callbacks to be injected in the target method. */ public At[] at(); /** - * Setting an injected callback to cancellable allows the injected callback to inject optional RETURN opcodes into the target method, the - * return behaviour can then be controlled from within the callback by interacting with the supplied - * {@link org.spongepowered.asm.mixin.injection.callback.CallbackInfo} object. + * Setting an injected callback to cancellable allows the injected + * callback to inject optional RETURN opcodes into the target method, the + * return behaviour can then be controlled from within the callback by + * interacting with the supplied + * {@link org.spongepowered.asm.mixin.injection.callback.CallbackInfo} + * object. */ public boolean cancellable() default false; /** - * Set to true to allow local variables to be captured from the target method as well as method parameters. + * Set to true to allow local variables to be captured from the target + * method as well as method parameters. */ // public boolean captureLocals() default false; /** - * By default, the annotation processor will attempt to locate an obfuscation mapping for all {@link Inject} methods since it is anticipated that - * in general the target of a {@link Inject} annotation will be an obfuscated method in the target class. However since it is possible to also - * apply mixins to non-obfuscated targets (or non-obfuscated methods in obfuscated targets, such as methods added by Forge) it may be necessary - * to suppress the compiler error which would otherwise be generated. Setting this value to false will cause the annotation processor - * to skip this annotation when attempting to build the obfuscation table for the mixin. + * By default, the annotation processor will attempt to locate an + * obfuscation mapping for all {@link Inject} methods since it is + * anticipated that in general the target of a {@link Inject} annotation + * will be an obfuscated method in the target class. However since it is + * possible to also apply mixins to non-obfuscated targets (or non- + * obfuscated methods in obfuscated targets, such as methods added by Forge) + * it may be necessary to suppress the compiler error which would otherwise + * be generated. Setting this value to false will cause the + * annotation processor to skip this annotation when attempting to build the + * obfuscation table for the mixin. */ public boolean remap() default true; } diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/InjectionPoint.java b/src/main/java/org/spongepowered/asm/mixin/injection/InjectionPoint.java index 2e264aed..4367b127 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/InjectionPoint.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/InjectionPoint.java @@ -49,26 +49,37 @@ import com.google.common.base.Joiner; import com.google.common.collect.ImmutableList; /** - *

Base class for injection point discovery classes. Each subclass describes a strategy for locating code injection points within a method, with - * the {@link #find} method populating a collection with insn nodes from the method which satisfy its strategy.

+ *

Base class for injection point discovery classes. Each subclass describes + * a strategy for locating code injection points within a method, with the + * {@link #find} method populating a collection with insn nodes from the method + * which satisfy its strategy.

* - *

This base class also contains composite strategy factory methods such as {@link #and} and {@link #or} which allow strategies to be combined - * using intersection (and) or union (or) relationships to allow multiple strategies to be easily combined.

+ *

This base class also contains composite strategy factory methods such as + * {@link #and} and {@link #or} which allow strategies to be combined using + * intersection (and) or union (or) relationships to allow multiple strategies + * to be easily combined.

* - *

You are free to create your own injection point subclasses, but take note that it is allowed for a single InjectionPoint instance to be - * used for multiple injections and thus implementing classes MUST NOT cache the insn list, event, or nodes instance passed to the {@link #find} - * method, as each call to {@link #find} must be considered a separate functional contract and the InjectionPoint's lifespan is not linked to the - * discovery lifespan, therefore it is important that the InjectionPoint implementation is fully stateless.

+ *

You are free to create your own injection point subclasses, but take note + * that it is allowed for a single InjectionPoint instance to be used for + * multiple injections and thus implementing classes MUST NOT cache the insn + * list, event, or nodes instance passed to the {@link #find} method, as each + * call to {@link #find} must be considered a separate functional contract and + * the InjectionPoint's lifespan is not linked to the discovery lifespan, + * therefore it is important that the InjectionPoint implementation is fully + * stateless.

*/ public abstract class InjectionPoint { /** * Find injection points in the supplied insn list * - * @param desc Method descriptor, supplied to allow return types and arguments etc. to be determined - * @param insns Insn list to search in, the strategy MUST ONLY add nodes from this list to the {@code nodes} collection - * @param nodes Collection of nodes to populate. Injectors should NOT make any assumptions about the state of this collection and should only call - * the add() method + * @param desc Method descriptor, supplied to allow return types and + * arguments etc. to be determined + * @param insns Insn list to search in, the strategy MUST ONLY add nodes + * from this list to the {@code nodes} collection + * @param nodes Collection of nodes to populate. Injectors should NOT make + * any assumptions about the state of this collection and should only + * call the add() method * @return true if one or more injection points were found */ public abstract boolean find(String desc, InsnList insns, Collection nodes); @@ -106,7 +117,8 @@ public abstract class InjectionPoint { } /** - * Intersection of several injection points, returns common nodes that appear in all children + * Intersection of several injection points, returns common nodes that + * appear in all children */ static final class Intersection extends InjectionPoint.CompositeInjectionPoint { @@ -150,7 +162,8 @@ public abstract class InjectionPoint { } /** - * Union of several injection points, returns all insns returned from all injections + * Union of several injection points, returns all insns returned from all + * injections */ static final class Union extends InjectionPoint.CompositeInjectionPoint { @@ -173,7 +186,8 @@ public abstract class InjectionPoint { } /** - * Shift injection point, takes an input injection point and shifts all returned nodes by a fixed amount + * Shift injection point, takes an input injection point and shifts all + * returned nodes by a fixed amount */ static final class Shift extends InjectionPoint { @@ -217,7 +231,8 @@ public abstract class InjectionPoint { } /** - * Returns a composite injection point which returns the intersection of nodes from all component injection points + * Returns a composite injection point which returns the intersection of + * nodes from all component injection points * * @param operands injection points to perform intersection */ @@ -226,7 +241,8 @@ public abstract class InjectionPoint { } /** - * Returns a composite injection point which returns the union of nodes from all component injection points + * Returns a composite injection point which returns the union of nodes from + * all component injection points * * @param operands injection points to perform union */ @@ -235,7 +251,8 @@ public abstract class InjectionPoint { } /** - * Returns an injection point which returns all insns immediately following insns from the supplied injection point + * Returns an injection point which returns all insns immediately following + * insns from the supplied injection point * * @param point injection points to perform shift */ @@ -244,7 +261,8 @@ public abstract class InjectionPoint { } /** - * Returns an injection point which returns all insns immediately prior to insns from the supplied injection point + * Returns an injection point which returns all insns immediately prior to + * insns from the supplied injection point * * @param point injection points to perform shift */ @@ -253,7 +271,8 @@ public abstract class InjectionPoint { } /** - * Returns an injection point which returns all insns offset by the specified "count" from insns from the supplied injection point + * Returns an injection point which returns all insns offset by the + * specified "count" from insns from the supplied injection point * * @param point injection points to perform shift */ @@ -269,7 +288,8 @@ public abstract class InjectionPoint { } /** - * Parse an InjectionPoint from the supplied {@link At} annotation supplied as an AnnotationNode instance + * Parse an InjectionPoint from the supplied {@link At} annotation supplied + * as an AnnotationNode instance */ public static InjectionPoint parse(MixinData mixin, AnnotationNode node) { String at = ASMHelper.getAnnotationValue(node, "value"); @@ -288,7 +308,8 @@ public abstract class InjectionPoint { } /** - * Parse and instantiate an InjectionPoint from the supplied information. Returns null if an InjectionPoint could not be created. + * Parse and instantiate an InjectionPoint from the supplied information. + * Returns null if an InjectionPoint could not be created. */ public static InjectionPoint parse(MixinData mixin, String at, At.Shift shift, int by, List args, String target, int ordinal, int opcode) { diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/ModifyArg.java b/src/main/java/org/spongepowered/asm/mixin/injection/ModifyArg.java index f48f4d0f..ada9aa04 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/ModifyArg.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/ModifyArg.java @@ -30,38 +30,51 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Specifies that this mixin method should inject an argument modifier to itself in the target method(s) identified by {@link #method}. + * Specifies that this mixin method should inject an argument modifier to itself + * in the target method(s) identified by {@link #method}. */ @Target({ ElementType.METHOD }) @Retention(RetentionPolicy.RUNTIME) public @interface ModifyArg { /** - * String representation of a {@link org.spongepowered.asm.mixin.injection.struct.MemberInfo MemberInfo} which identifies the target method. + * String representation of a + * {@link org.spongepowered.asm.mixin.injection.struct.MemberInfo + * MemberInfo} which identifies the target method. */ public String method(); /** - * An {@link At} annotation which describes the {@link InjectionPoint} in the target method. The specified {@link InjectionPoint} must only - * return nodes of type {@link org.objectweb.asm.tree.MethodInsnNode} and an exception will be thrown if this is not the case. + * An {@link At} annotation which describes the {@link InjectionPoint} in + * the target method. The specified {@link InjectionPoint} must only + * return nodes of type {@link org.objectweb.asm.tree.MethodInsnNode} and an + * exception will be thrown if this is not the case. */ public At at(); /** - *

Gets the argument index on the target to set. It is not necessary to set this value if there is only one argument of the modifier type in - * the hooked method's signature. For example if the target method accepts a boolean, an integer and a String, and the modifier method accepts - * and returns an integer, then the integer parameter will be automatically selected.

+ *

Gets the argument index on the target to set. It is not necessary to + * set this value if there is only one argument of the modifier type in the + * hooked method's signature. For example if the target method accepts a + * boolean, an integer and a String, and the modifier method accepts and + * returns an integer, then the integer parameter will be automatically + * selected.

* *

The index is zero-based.

*/ public int index() default -1; /** - * By default, the annotation processor will attempt to locate an obfuscation mapping for all {@link ModifyArg} methods since it is anticipated - * that in general the target of a {@link ModifyArg} annotation will be an obfuscated method in the target class. However since it is possible to - * also apply mixins to non-obfuscated targets (or non-obfuscated methods in obfuscated targets, such as methods added by Forge) it may be - * necessary to suppress the compiler error which would otherwise be generated. Setting this value to false will cause the annotation - * processor to skip this annotation when attempting to build the obfuscation table for the mixin. + * By default, the annotation processor will attempt to locate an + * obfuscation mapping for all {@link ModifyArg} methods since it is + * anticipated that in general the target of a {@link ModifyArg} annotation + * will be an obfuscated method in the target class. However since it is + * possible to also apply mixins to non-obfuscated targets (or non- + * obfuscated methods in obfuscated targets, such as methods added by Forge) + * it may be necessary to suppress the compiler error which would otherwise + * be generated. Setting this value to false will cause the + * annotation processor to skip this annotation when attempting to build the + * obfuscation table for the mixin. */ public boolean remap() default true; } diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/Redirect.java b/src/main/java/org/spongepowered/asm/mixin/injection/Redirect.java index 3cbe9e1e..926e1d04 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/Redirect.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/Redirect.java @@ -30,29 +30,39 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Specifies that this mixin method should redirect the specified {@link #method} call to the method decorated with this annotation. + * Specifies that this mixin method should redirect the specified + * {@link #method} call to the method decorated with this annotation. */ @Target({ ElementType.METHOD }) @Retention(RetentionPolicy.RUNTIME) public @interface Redirect { /** - * String representation of a {@link org.spongepowered.asm.mixin.injection.struct.MemberInfo MemberInfo} which identifies the target method. + * String representation of a + * {@link org.spongepowered.asm.mixin.injection.struct.MemberInfo + * MemberInfo} which identifies the target method. */ public String method(); /** - * An {@link At} annotation which describes the {@link InjectionPoint} in the target method. The specified {@link InjectionPoint} must only - * return nodes of type {@link org.objectweb.asm.tree.MethodInsnNode} and an exception will be thrown if this is not the case. + * An {@link At} annotation which describes the {@link InjectionPoint} in + * the target method. The specified {@link InjectionPoint} must only + * return nodes of type {@link org.objectweb.asm.tree.MethodInsnNode} and an + * exception will be thrown if this is not the case. */ public At at(); /** - * By default, the annotation processor will attempt to locate an obfuscation mapping for all {@link ModifyArg} methods since it is anticipated - * that in general the target of a {@link ModifyArg} annotation will be an obfuscated method in the target class. However since it is possible to - * also apply mixins to non-obfuscated targets (or non-obfuscated methods in obfuscated targets, such as methods added by Forge) it may be - * necessary to suppress the compiler error which would otherwise be generated. Setting this value to false will cause the annotation - * processor to skip this annotation when attempting to build the obfuscation table for the mixin. + * By default, the annotation processor will attempt to locate an + * obfuscation mapping for all {@link Redirect} methods since it is + * anticipated that in general the target of a {@link Redirect} annotation + * will be an obfuscated method in the target class. However since it is + * possible to also apply mixins to non-obfuscated targets (or non- + * obfuscated methods in obfuscated targets, such as methods added by Forge) + * it may be necessary to suppress the compiler error which would otherwise + * be generated. Setting this value to false will cause the + * annotation processor to skip this annotation when attempting to build the + * obfuscation table for the mixin. */ public boolean remap() default true; } diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/callback/CallbackInfo.java b/src/main/java/org/spongepowered/asm/mixin/injection/callback/CallbackInfo.java index 0efbc99c..b8121274 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/callback/CallbackInfo.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/callback/CallbackInfo.java @@ -27,8 +27,10 @@ package org.spongepowered.asm.mixin.injection.callback; import org.objectweb.asm.Type; /** - * CallbackInfo instances are passed to callbacks in order to provide information and handling opportunities to the callback to interact with the - * callback itself. For example by allowing the callback to be "cancelled" and return from a method prematurely. + * CallbackInfo instances are passed to callbacks in order to provide + * information and handling opportunities to the callback to interact with the + * callback itself. For example by allowing the callback to be "cancelled" and + * return from a method prematurely. */ public class CallbackInfo implements Cancellable { @@ -36,7 +38,8 @@ public class CallbackInfo implements Cancellable { protected static final String OBJECT = "Ljava/lang/Object;"; /** - * Method name being injected into, this is useful if a single callback is injecting into multiple methods + * Method name being injected into, this is useful if a single callback is + * injecting into multiple methods. */ private final String name; @@ -73,17 +76,11 @@ public class CallbackInfo implements Cancellable { return String.format("CallbackInfo[TYPE=%s,NAME=%s,CANCELLABLE=%s]", this.getClass().getSimpleName(), this.name, this.cancellable); } - /* (non-Javadoc) - * @see org.spongepowered.asm.mixin.injection.callback.Cancellable#isCancellable() - */ @Override public final boolean isCancellable() { return this.cancellable; } - /* (non-Javadoc) - * @see org.spongepowered.asm.mixin.injection.callback.Cancellable#isCancelled() - */ @Override public final boolean isCancelled() { return this.cancelled; diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/callback/CallbackInfoReturnable.java b/src/main/java/org/spongepowered/asm/mixin/injection/callback/CallbackInfoReturnable.java index b7f1b4f1..aa90b111 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/callback/CallbackInfoReturnable.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/callback/CallbackInfoReturnable.java @@ -27,8 +27,9 @@ package org.spongepowered.asm.mixin.injection.callback; import org.objectweb.asm.Type; /** - * For callbacks with a non-void return type, a CallbackInfoReturnable is passed to the callback instead to allow the callback to interact with the - * method return value. + * For callbacks with a non-void return type, a CallbackInfoReturnable is passed + * to the callback instead to allow the callback to interact with the method + * return value. * * @param Return type */ @@ -95,7 +96,8 @@ public class CallbackInfoReturnable extends CallbackInfo { } /** - * Sets a return value for this callback and cancels the callback (required in order to return the new value) + * Sets a return value for this callback and cancels the callback (required + * in order to return the new value) * * @param returnValue */ diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/callback/CallbackInjector.java b/src/main/java/org/spongepowered/asm/mixin/injection/callback/CallbackInjector.java index 712844a7..e7a43b7c 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/callback/CallbackInjector.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/callback/CallbackInjector.java @@ -72,7 +72,8 @@ public class CallbackInjector extends Injector { } /* (non-Javadoc) - * @see org.spongepowered.asm.mixin.injection.callback.BytecodeInjector#sanityCheck(org.spongepowered.asm.mixin.injection.callback.Target, + * @see org.spongepowered.asm.mixin.injection.callback.BytecodeInjector + * #sanityCheck(org.spongepowered.asm.mixin.injection.callback.Target, * java.util.List) */ @Override @@ -92,7 +93,8 @@ public class CallbackInjector extends Injector { } /* (non-Javadoc) - * @see org.spongepowered.asm.mixin.injection.callback.BytecodeInjector#inject(org.spongepowered.asm.mixin.injection.callback.Target, + * @see org.spongepowered.asm.mixin.injection.callback.BytecodeInjector + * #inject(org.spongepowered.asm.mixin.injection.callback.Target, * org.objectweb.asm.tree.AbstractInsnNode) */ @Override diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/callback/Cancellable.java b/src/main/java/org/spongepowered/asm/mixin/injection/callback/Cancellable.java index 3a416a74..7e07e38b 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/callback/Cancellable.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/callback/Cancellable.java @@ -40,11 +40,12 @@ public interface Cancellable { public abstract boolean isCancelled(); /** - * If the object is cancellable, cancels the object, implementors may throw an EventCancellationException if the object is not actually - * cancellable. + * If the object is cancellable, cancels the object, implementors may throw + * an EventCancellationException if the object is not actually cancellable. * - * @throws CancellationException (optional) may be thrown if the object is not actually cancellable. Contractually, this object may not throw the - * exception if isCancellable() returns true. + * @throws CancellationException (optional) may be thrown if the object is + * not actually cancellable. Contractually, this object may not throw + * the exception if isCancellable() returns true. */ public abstract void cancel() throws CancellationException; } \ No newline at end of file diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/code/ReadOnlyInsnList.java b/src/main/java/org/spongepowered/asm/mixin/injection/code/ReadOnlyInsnList.java index 91f5dcf2..eb18dec5 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/code/ReadOnlyInsnList.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/code/ReadOnlyInsnList.java @@ -30,8 +30,9 @@ import org.objectweb.asm.tree.AbstractInsnNode; import org.objectweb.asm.tree.InsnList; /** - * Read-only wrapper for InsnList, defensively passed to InjectionPoint instances so that custom InjectionPoint implementations cannot modify the insn - * list whilst inspecting it. + * Read-only wrapper for InsnList, defensively passed to InjectionPoint + * instances so that custom InjectionPoint implementations cannot modify the + * insn list whilst inspecting it. */ class ReadOnlyInsnList extends InsnList { @@ -48,7 +49,9 @@ class ReadOnlyInsnList extends InsnList { /* * (non-Javadoc) * - * @see org.objectweb.asm.tree.InsnList#set(org.objectweb.asm.tree.AbstractInsnNode, org.objectweb.asm.tree.AbstractInsnNode) + * @see org.objectweb.asm.tree.InsnList + * #set(org.objectweb.asm.tree.AbstractInsnNode, + * org.objectweb.asm.tree.AbstractInsnNode) */ @Override public void set(AbstractInsnNode location, AbstractInsnNode insn) { @@ -58,7 +61,8 @@ class ReadOnlyInsnList extends InsnList { /* * (non-Javadoc) * - * @see org.objectweb.asm.tree.InsnList#add(org.objectweb.asm.tree.AbstractInsnNode) + * @see org.objectweb.asm.tree.InsnList + * #add(org.objectweb.asm.tree.AbstractInsnNode) */ @Override public void add(AbstractInsnNode insn) { @@ -78,7 +82,8 @@ class ReadOnlyInsnList extends InsnList { /* * (non-Javadoc) * - * @see org.objectweb.asm.tree.InsnList#insert(org.objectweb.asm.tree.AbstractInsnNode) + * @see org.objectweb.asm.tree.InsnList + * #insert(org.objectweb.asm.tree.AbstractInsnNode) */ @Override public void insert(AbstractInsnNode insn) { @@ -88,7 +93,8 @@ class ReadOnlyInsnList extends InsnList { /* * (non-Javadoc) * - * @see org.objectweb.asm.tree.InsnList#insert(org.objectweb.asm.tree.InsnList) + * @see org.objectweb.asm.tree.InsnList + * #insert(org.objectweb.asm.tree.InsnList) */ @Override public void insert(InsnList insns) { @@ -98,7 +104,9 @@ class ReadOnlyInsnList extends InsnList { /* * (non-Javadoc) * - * @see org.objectweb.asm.tree.InsnList#insert(org.objectweb.asm.tree.AbstractInsnNode, org.objectweb.asm.tree.AbstractInsnNode) + * @see org.objectweb.asm.tree.InsnList + * #insert(org.objectweb.asm.tree.AbstractInsnNode, + * org.objectweb.asm.tree.AbstractInsnNode) */ @Override public void insert(AbstractInsnNode location, AbstractInsnNode insn) { @@ -108,7 +116,9 @@ class ReadOnlyInsnList extends InsnList { /* * (non-Javadoc) * - * @see org.objectweb.asm.tree.InsnList#insert(org.objectweb.asm.tree.AbstractInsnNode, org.objectweb.asm.tree.InsnList) + * @see org.objectweb.asm.tree.InsnList + * #insert(org.objectweb.asm.tree.AbstractInsnNode, + * org.objectweb.asm.tree.InsnList) */ @Override public void insert(AbstractInsnNode location, InsnList insns) { @@ -118,7 +128,9 @@ class ReadOnlyInsnList extends InsnList { /* * (non-Javadoc) * - * @see org.objectweb.asm.tree.InsnList#insertBefore(org.objectweb.asm.tree.AbstractInsnNode, org.objectweb.asm.tree.AbstractInsnNode) + * @see org.objectweb.asm.tree.InsnList + * #insertBefore(org.objectweb.asm.tree.AbstractInsnNode, + * org.objectweb.asm.tree.AbstractInsnNode) */ @Override public void insertBefore(AbstractInsnNode location, AbstractInsnNode insn) { @@ -128,7 +140,9 @@ class ReadOnlyInsnList extends InsnList { /* * (non-Javadoc) * - * @see org.objectweb.asm.tree.InsnList#insertBefore(org.objectweb.asm.tree.AbstractInsnNode, org.objectweb.asm.tree.InsnList) + * @see org.objectweb.asm.tree.InsnList + * #insertBefore(org.objectweb.asm.tree.AbstractInsnNode, + * org.objectweb.asm.tree.InsnList) */ @Override public void insertBefore(AbstractInsnNode location, InsnList insns) { @@ -138,7 +152,8 @@ class ReadOnlyInsnList extends InsnList { /* * (non-Javadoc) * - * @see org.objectweb.asm.tree.InsnList#remove(org.objectweb.asm.tree.AbstractInsnNode) + * @see org.objectweb.asm.tree.InsnList + * #remove(org.objectweb.asm.tree.AbstractInsnNode) */ @Override public void remove(AbstractInsnNode insn) { @@ -198,7 +213,8 @@ class ReadOnlyInsnList extends InsnList { /* * (non-Javadoc) * - * @see org.objectweb.asm.tree.InsnList#contains(org.objectweb.asm.tree.AbstractInsnNode) + * @see org.objectweb.asm.tree.InsnList + * #contains(org.objectweb.asm.tree.AbstractInsnNode) */ @Override public boolean contains(AbstractInsnNode insn) { @@ -208,7 +224,8 @@ class ReadOnlyInsnList extends InsnList { /* * (non-Javadoc) * - * @see org.objectweb.asm.tree.InsnList#indexOf(org.objectweb.asm.tree.AbstractInsnNode) + * @see org.objectweb.asm.tree.InsnList + * #indexOf(org.objectweb.asm.tree.AbstractInsnNode) */ @Override public int indexOf(AbstractInsnNode insn) { diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/invoke/InvokeInjector.java b/src/main/java/org/spongepowered/asm/mixin/injection/invoke/InvokeInjector.java index 5d20be88..76865997 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/invoke/InvokeInjector.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/invoke/InvokeInjector.java @@ -62,7 +62,8 @@ public abstract class InvokeInjector extends Injector { } /* (non-Javadoc) - * @see org.spongepowered.asm.mixin.injection.callback.BytecodeInjector#sanityCheck(org.spongepowered.asm.mixin.injection.callback.Target, + * @see org.spongepowered.asm.mixin.injection.callback.BytecodeInjector + * #sanityCheck(org.spongepowered.asm.mixin.injection.callback.Target, * java.util.List) */ @Override @@ -73,7 +74,8 @@ public abstract class InvokeInjector extends Injector { } /* (non-Javadoc) - * @see org.spongepowered.asm.mixin.injection.callback.BytecodeInjector#inject(org.spongepowered.asm.mixin.injection.callback.Target, + * @see org.spongepowered.asm.mixin.injection.callback.BytecodeInjector + * #inject(org.spongepowered.asm.mixin.injection.callback.Target, * org.objectweb.asm.tree.AbstractInsnNode) */ @Override @@ -108,7 +110,8 @@ public abstract class InvokeInjector extends Injector { } /** - * Generate an array containing local indexes for the specified args, returns an array of identical size to the supplied array with an + * Generate an array containing local indexes for the specified args, + * returns an array of identical size to the supplied array with an * allocated local index in each corresponding position */ protected int[] generateArgMap(Type[] args, int start, int local) { @@ -121,7 +124,8 @@ public abstract class InvokeInjector extends Injector { } /** - * Store args on the stack starting at the end and working back to position specified by start, return the generated argMap + * Store args on the stack starting at the end and working back to position + * specified by start, return the generated argMap */ protected int[] storeArgs(Target target, Type[] args, InsnList insns, int start) { int[] argMap = this.generateArgMap(args, start, target.method.maxLocals); diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/invoke/ModifyArgInjector.java b/src/main/java/org/spongepowered/asm/mixin/injection/invoke/ModifyArgInjector.java index 0e81a4aa..0158b869 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/invoke/ModifyArgInjector.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/invoke/ModifyArgInjector.java @@ -37,17 +37,20 @@ import org.spongepowered.asm.mixin.injection.struct.InjectionInfo; import org.spongepowered.asm.mixin.injection.struct.Target; /** - * A bytecode injector which allows a single argument of a chosen method call to be altered + * A bytecode injector which allows a single argument of a chosen method call to + * be altered. */ public class ModifyArgInjector extends InvokeInjector { /** - * Index of the target arg or -1 to find the arg automatically (only works where there is only one arg of specified type on the element) + * Index of the target arg or -1 to find the arg automatically (only works + * where there is only one arg of specified type on the element) */ private final int index; /** - * True if processing in single arg mode, the callback only accepts a single arg of the same type as the return. Otherwise the handler method is + * True if processing in single arg mode, the callback only accepts a single + * arg of the same type as the return. Otherwise the handler method is * expected to have matching args to the target invocation */ private final boolean singleArgMode; @@ -63,7 +66,8 @@ public class ModifyArgInjector extends InvokeInjector { } /* (non-Javadoc) - * @see org.spongepowered.asm.mixin.injection.callback.BytecodeInjector#sanityCheck(org.spongepowered.asm.mixin.injection.callback.Target, + * @see org.spongepowered.asm.mixin.injection.callback.BytecodeInjector + * #sanityCheck(org.spongepowered.asm.mixin.injection.callback.Target, * java.util.List) */ @Override diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/invoke/RedirectInjector.java b/src/main/java/org/spongepowered/asm/mixin/injection/invoke/RedirectInjector.java index d119ab98..e5a8ef6e 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/invoke/RedirectInjector.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/invoke/RedirectInjector.java @@ -37,9 +37,11 @@ import org.spongepowered.asm.util.ASMHelper; import com.google.common.collect.ObjectArrays; /** - *

A bytecode injector which allows a method call to be redirected to the annotated handler method. The handler method signature must match the - * hooked method precisely but prepended with an arg of the owning object's type to accept the object instance the method was going to be - * invoked on. For example when hooking the following call:

+ *

A bytecode injector which allows a method call to be redirected to the + * annotated handler method. The handler method signature must match the hooked + * method precisely but prepended with an arg of the owning object's type + * to accept the object instance the method was going to be invoked on. For + * example when hooking the following call:

* *
  *   int abc = 0;
@@ -52,10 +54,13 @@ import com.google.common.collect.ObjectArrays;
  * 
  * 

The signature of the redirected method should be:

* - *
public boolean barProxy(Foo someObject, int abc, int def)
+ *
+ *
public boolean barProxy(Foo someObject, int abc, int def)
+ *
* - *

For obvious reasons this does not apply for static methods, for static methods it is sufficient that the signature simply match the hooked - * method.

+ *

For obvious reasons this does not apply for static methods, for static + * methods it is sufficient that the signature simply match the hooked method. + *

*/ public class RedirectInjector extends InvokeInjector { diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/points/BeforeFieldAccess.java b/src/main/java/org/spongepowered/asm/mixin/injection/points/BeforeFieldAccess.java index 50c15508..5c258fd7 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/points/BeforeFieldAccess.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/points/BeforeFieldAccess.java @@ -30,26 +30,37 @@ import org.objectweb.asm.tree.FieldInsnNode; import org.spongepowered.asm.mixin.injection.struct.InjectionPointData; /** - *

This injection point searches for GETFIELD and PUTFIELD (and static equivalent) opcodes matching its arguments and returns a list of insns - * immediately prior to matching instructions. It accepts the following parameters from {@link org.spongepowered.asm.mixin.injection.At At}:

+ *

This injection point searches for GETFIELD and PUTFIELD (and static + * equivalent) opcodes matching its arguments and returns a list of insns + * immediately prior to matching instructions. It accepts the following + * parameters from {@link org.spongepowered.asm.mixin.injection.At At}: + *

* *
*
target
- *
A {@link org.spongepowered.asm.mixin.injection.struct.MemberInfo MemberInfo} which identifies the target field
+ *
A + * {@link org.spongepowered.asm.mixin.injection.struct.MemberInfo MemberInfo} + * which identifies the target field.
*
opcode
- *
The {@link Opcodes opcode} of the field access, must be one of GETSTATIC, PUTSTATIC, GETFIELD or PUTFIELD.
+ *
The {@link Opcodes opcode} of the field access, must be one of + * GETSTATIC, PUTSTATIC, GETFIELD or PUTFIELD.
*
ordinal
- *
The ordinal position of the field access to match. For example if the field is referenced 3 times and you want to match the 3rd then you can - * specify an ordinal of 2 (ordinals are zero-indexed). The default value is -1 which supresses ordinal matching
+ *
The ordinal position of the field access to match. For example if the + * field is referenced 3 times and you want to match the 3rd then you can + * specify an ordinal of 2 (ordinals are zero-indexed). The + * default value is -1 which supresses ordinal matching
*
* *

Example:

*
- *   @At(value = "FIELD", target="field_5678_z:I", opcode = Opcodes.GETFIELD)
+ * @At(value = "FIELD", target="field_59_z:I", opcode = Opcodes.GETFIELD) + *
*
* - *

Note that like all standard injection points, this class matches the insn itself, putting the injection point immediately before the - * access in question. Use the {@link org.spongepowered.asm.mixin.injection.At#shift shift} specifier to adjust the matched opcode as necessary.

+ *

Note that like all standard injection points, this class matches the insn + * itself, putting the injection point immediately before the access in + * question. Use {@link org.spongepowered.asm.mixin.injection.At#shift shift} + * specifier to adjust the matched opcode as necessary.

*/ public class BeforeFieldAccess extends BeforeInvoke { diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/points/BeforeInvoke.java b/src/main/java/org/spongepowered/asm/mixin/injection/points/BeforeInvoke.java index cffcff41..2c8ba476 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/points/BeforeInvoke.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/points/BeforeInvoke.java @@ -37,15 +37,21 @@ import org.spongepowered.asm.mixin.injection.struct.InjectionPointData; import org.spongepowered.asm.mixin.injection.struct.MemberInfo; /** - *

This injection point searches for INVOKEVIRTUAL, INVOKESTATIC and INVOKESPECIAL opcodes matching its arguments and returns a list of insns - * immediately prior to matching instructions. It accepts the following parameters from {@link org.spongepowered.asm.mixin.injection.At At}:

+ *

This injection point searches for INVOKEVIRTUAL, INVOKESTATIC and + * INVOKESPECIAL opcodes matching its arguments and returns a list of insns + * immediately prior to matching instructions. It accepts the following + * parameters from {@link org.spongepowered.asm.mixin.injection.At At}:

* *
*
target
- *
A {@link org.spongepowered.asm.mixin.injection.struct.MemberInfo MemberInfo} which identifies the target method
+ *
A + * {@link org.spongepowered.asm.mixin.injection.struct.MemberInfo MemberInfo} + * which identifies the target method
*
ordinal
- *
The ordinal position of the method invocation to match. For example if the method is invoked 3 times and you want to match the 3rd then you - * can specify an ordinal of 2 (ordinals are zero-indexed). The default value is -1 which supresses ordinal matching
+ *
The ordinal position of the method invocation to match. For example if + * the method is invoked 3 times and you want to match the 3rd then you can + * specify an ordinal of 2 (ordinals are zero-indexed). The + * default value is -1 which supresses ordinal matching
*
* *

Example:

@@ -53,8 +59,10 @@ import org.spongepowered.asm.mixin.injection.struct.MemberInfo; * @At(value = "INVOKE", target="func_1234_a(III)V") * * - *

Note that like all standard injection points, this class matches the insn itself, putting the injection point immediately before the - * access in question. Use the {@link org.spongepowered.asm.mixin.injection.At#shift shift} specifier to adjust the matched opcode as necessary.

+ *

Note that like all standard injection points, this class matches the insn + * itself, putting the injection point immediately before the access in + * question. Use {@link org.spongepowered.asm.mixin.injection.At#shift shift} + * specifier to adjust the matched opcode as necessary.

*/ public class BeforeInvoke extends InjectionPoint { @@ -63,7 +71,8 @@ public class BeforeInvoke extends InjectionPoint { protected final MemberInfo target; /** - * This strategy can be used to identify a particular invokation if the same method is invoked at multiple points, if this value is -1 then the + * This strategy can be used to identify a particular invokation if the same + * method is invoked at multiple points, if this value is -1 then the * strategy returns all invokations of the method. */ protected final int ordinal; @@ -92,8 +101,11 @@ public class BeforeInvoke extends InjectionPoint { /* * (non-Javadoc) * - * @see com.mumfrey.liteloader.transformers.event.InjectionStrategy#findInjectionPoint(java.lang.String, org.objectweb.asm.tree.InsnList, - * com.mumfrey.liteloader.transformers.event.Event, java.util.Collection) + * @see com.mumfrey.liteloader.transformers.event.InjectionStrategy + * #findInjectionPoint(java.lang.String, + * org.objectweb.asm.tree.InsnList, + * com.mumfrey.liteloader.transformers.event.Event, + * java.util.Collection) */ @Override public boolean find(String desc, InsnList insns, Collection nodes) { diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/points/BeforeNew.java b/src/main/java/org/spongepowered/asm/mixin/injection/points/BeforeNew.java index 0ab8d3e2..f6cea1b3 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/points/BeforeNew.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/points/BeforeNew.java @@ -35,16 +35,20 @@ import org.spongepowered.asm.mixin.injection.InjectionPoint; import org.spongepowered.asm.mixin.injection.struct.InjectionPointData; /** - *

This injection point searches for NEW opcodes matching its arguments and returns a list of insns immediately prior to matching instructions. It - * accepts the following parameters from {@link org.spongepowered.asm.mixin.injection.At At}:

+ *

This injection point searches for NEW opcodes matching its arguments and + * returns a list of insns immediately prior to matching instructions. It + * accepts the following parameters from + * {@link org.spongepowered.asm.mixin.injection.At At}:

* *
*
named argument class
- *
The value of the NEW node to look for, the fully-qualified class name
+ *
The value of the NEW node to look for, the fully-qualified class name + *
*
ordinal
- *
The ordinal position of the NEW opcode to match. For example if the NEW opcode appears 3 times in the method and you want to match the 3rd - * then you can specify an ordinal of 2 (ordinals are zero-indexed). The default value is -1 which supresses ordinal - * matching
+ *
The ordinal position of the NEW opcode to match. For example if the NEW + * opcode appears 3 times in the method and you want to match the 3rd then you + * can specify an ordinal of 2 (ordinals are zero-indexed). + * The default value is -1 which supresses ordinal matching
*
* *

Example:

@@ -52,8 +56,10 @@ import org.spongepowered.asm.mixin.injection.struct.InjectionPointData; * @At(value = "NEW", args = { "class=java/lang/String" }) * * - *

Note that like all standard injection points, this class matches the insn itself, putting the injection point immediately before the - * access in question. Use the {@link org.spongepowered.asm.mixin.injection.At#shift shift} specifier to adjust the matched opcode as necessary.

+ *

Note that like all standard injection points, this class matches the insn + * itself, putting the injection point immediately before the access in + * question. Use {@link org.spongepowered.asm.mixin.injection.At#shift shift} + * specifier to adjust the matched opcode as necessary.

*/ public class BeforeNew extends InjectionPoint { diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/points/BeforeReturn.java b/src/main/java/org/spongepowered/asm/mixin/injection/points/BeforeReturn.java index cc85bb0c..57731a24 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/points/BeforeReturn.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/points/BeforeReturn.java @@ -36,23 +36,30 @@ import org.spongepowered.asm.mixin.injection.InjectionPoint; import org.spongepowered.asm.mixin.injection.struct.InjectionPointData; /** - *

This injection point searches for RETURN opcodes in the target method and returns a list of insns immediately prior to matching instructions. - * Note that every RETURN opcode will be returned and thus every natural exit from the method except for exception throws will be implicitly - * specified. To specify a particular RETURN use the ordinal parameter. The injection point accepts the following parameters from - * {@link org.spongepowered.asm.mixin.injection.At At}:

+ *

This injection point searches for RETURN opcodes in the target method and + * returns a list of insns immediately prior to matching instructions. Note that + * every RETURN opcode will be returned and thus every natural exit + * from the method except for exception throws will be implicitly specified. To + * specify a particular RETURN use the ordinal parameter. The injection + * point accepts the following parameters from + * {@link org.spongepowered.asm.mixin.injection.At At}:

* *
*
ordinal
- *
The ordinal position of the RETURN opcode to match, if not specified then the injection point returns all RETURN opcodes. For - * example if the RETURN opcode appears 3 times in the method and you want to match the 3rd then you can specify an ordinal of 2 - * (ordinals are zero-indexed). The default value is -1 which supresses ordinal matching
+ *
The ordinal position of the RETURN opcode to match, if not specified + * then the injection point returns all RETURN opcodes. For example + * if the RETURN opcode appears 3 times in the method and you want to match + * the 3rd then you can specify an ordinal of 2 (ordinals are + * zero-indexed). The default value is -1 which supresses ordinal + * matching
*
* *

Example:

*
  *   @At(value = "RETURN")
*
- *

Note that if value is the only parameter specified, it can be omitted:

+ *

Note that if value is the only parameter specified, it can be + * omitted:

*
  *   @At("RETURN")
*
diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/points/BeforeStringInvoke.java b/src/main/java/org/spongepowered/asm/mixin/injection/points/BeforeStringInvoke.java index 76f6c84c..7ad86360 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/points/BeforeStringInvoke.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/points/BeforeStringInvoke.java @@ -33,36 +33,52 @@ import org.spongepowered.asm.mixin.injection.struct.InjectionPointData; import org.spongepowered.asm.mixin.injection.struct.MemberInfo; /** - *

Like {@link BeforeInvoke}, this injection point searches for INVOKEVIRTUAL, INVOKESTATIC and INVOKESPECIAL opcodes matching its arguments and - * returns a list of insns immediately prior to matching instructions. This specialised version however only matches methods which accept a single - * string and return void, but allows the string itself to be matched as part of the search process. This is primarily used for matching particular - * invocations of Profiler::startSection with a specific argument. Note that because a string literal is required, this injection point can - * not be used to match invocations where the value being passed in is a variable.

+ *

Like {@link BeforeInvoke}, this injection point searches for + * INVOKEVIRTUAL, INVOKESTATIC and INVOKESPECIAL opcodes matching its arguments + * and returns a list of insns immediately prior to matching instructions. This + * specialised version however only matches methods which accept a single string + * and return void, but allows the string itself to be matched as part of the + * search process. This is primarily used for matching particular invocations of + * Profiler::startSection with a specific argument. Note that because a + * string literal is required, this injection point can not be used to match + * invocations where the value being passed in is a variable.

* - *

To be precise, this injection point matches invocations of the specified method which are preceded by an LDC instruction. The LDC instruction's + *

To be precise, this injection point matches invocations of the specified + * method which are preceded by an LDC instruction. The LDC instruction's * payload can be specified with the ldc named argument (see below)

* - *

The following parameters from {@link org.spongepowered.asm.mixin.injection.At At} are accepted

+ *

The following parameters from + * {@link org.spongepowered.asm.mixin.injection.At At} are accepted

* *
*
target
- *
A {@link org.spongepowered.asm.mixin.injection.struct.MemberInfo MemberInfo} which identifies the target method, the method must be - * specified with a signature which accepts a single string and returns void, eg. (Ljava/lang/String;)V
+ *
A + * {@link org.spongepowered.asm.mixin.injection.struct.MemberInfo MemberInfo} + * which identifies the target method, the method must be specified + * with a signature which accepts a single string and returns void, + * eg. (Ljava/lang/String;)V
*
ordinal
- *
The ordinal position of the method invocation to match. For example if the method is invoked 3 times and you want to match the 3rd then you - * can specify an ordinal of 2 (ordinals are zero-indexed). The default value is -1 which supresses ordinal matching
+ *
The ordinal position of the method invocation to match. For example if + * the method is invoked 3 times and you want to match the 3rd then you can + * specify an ordinal of 2 (ordinals are zero-indexed). The + * default value is -1 which supresses ordinal matching
*
named argument ldc
- *
The value of the LDC node to look for prior to the method invocation
+ *
The value of the LDC node to look for prior to the method invocation + *
*
* *

Example:

*
- *   @At(value = "INVOKE_STRING", target="startSection(Ljava/lang/String;)V", args = { "ldc=root" })
+ * @At(value = "INVOKE_STRING", + * target="startSection(Ljava/lang/String;)V", args = { "ldc=root" }) *
- *

Notice the use of the named argument "ldc" which specifies the value of the target LDC node.

+ *

Notice the use of the named argument "ldc" which specifies the + * value of the target LDC node.

* - *

Note that like all standard injection points, this class matches the insn itself, putting the injection point immediately before the - * access in question. Use the {@link org.spongepowered.asm.mixin.injection.At#shift shift} specifier to adjust the matched opcode as necessary.

+ *

Note that like all standard injection points, this class matches the insn + * itself, putting the injection point immediately before the access in + * question. Use {@link org.spongepowered.asm.mixin.injection.At#shift shift} + * specifier to adjust the matched opcode as necessary.

*/ public class BeforeStringInvoke extends BeforeInvoke { diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/points/JumpInsnPoint.java b/src/main/java/org/spongepowered/asm/mixin/injection/points/JumpInsnPoint.java index 38706de7..f714ad75 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/points/JumpInsnPoint.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/points/JumpInsnPoint.java @@ -35,18 +35,25 @@ import org.spongepowered.asm.mixin.injection.InjectionPoint; import org.spongepowered.asm.mixin.injection.struct.InjectionPointData; /** - *

This injection point searches for JUMP opcodes (if, try/catch, continue, break, conditional assignment, etc.) with either a particular opcode - * or at a particular ordinal in the method body (eg. "the Nth JUMP insn" where N is the ordinal of the instruction). By default it returns all JUMP - * instructions in a method body. It accepts the following parameters from {@link org.spongepowered.asm.mixin.injection.At At}:

+ *

This injection point searches for JUMP opcodes (if, try/catch, continue, + * break, conditional assignment, etc.) with either a particular opcode or at a + * particular ordinal in the method body (eg. "the Nth JUMP insn" where N is the + * ordinal of the instruction). By default it returns all JUMP instructions in a + * method body. It accepts the following parameters from + * {@link org.spongepowered.asm.mixin.injection.At At}:

* *
*
opcode
- *
The {@link Opcodes opcode} of the jump instruction, must be one of IFEQ, IFNE, IFLT, IFGE, IFGT, IFLE, IF_ICMPEQ, IF_ICMPNE, IF_ICMPLT, - * IF_ICMPGE, IF_ICMPGT, IF_ICMPLE, IF_ACMPEQ, IF_ACMPNE, GOTO, JSR, IFNULL or IFNONNULL. Defaults to -1 which matches any JUMP opcode. - *
+ *
The {@link Opcodes opcode} of the jump instruction, must be one of + * IFEQ, IFNE, IFLT, IFGE, IFGT, IFLE, IF_ICMPEQ, IF_ICMPNE, IF_ICMPLT, + * IF_ICMPGE, IF_ICMPGT, IF_ICMPLE, IF_ACMPEQ, IF_ACMPNE, GOTO, JSR, IFNULL or + * IFNONNULL. Defaults to -1 which matches any JUMP opcode. + *
*
ordinal
- *
The ordinal position of the jump insn to match. For example if there are 3 jumps of the specified type and you want to match the 2nd then you - * can specify an ordinal of 1 (ordinals are zero-indexed). The default value is -1 which supresses ordinal matching
+ *
The ordinal position of the jump insn to match. For example if there + * are 3 jumps of the specified type and you want to match the 2nd then you + * can specify an ordinal of 1 (ordinals are zero-indexed). + * The default value is -1 which supresses ordinal matching
*
* *

Example:

@@ -54,8 +61,10 @@ import org.spongepowered.asm.mixin.injection.struct.InjectionPointData; * @At(value = "JUMP", opcode = Opcodes.IFLE, ordinal = 2) * * - *

Note that like all standard injection points, this class matches the insn itself, putting the injection point immediately before the - * access in question. Use the {@link org.spongepowered.asm.mixin.injection.At#shift shift} specifier to adjust the matched opcode as necessary.

+ *

Note that like all standard injection points, this class matches the insn + * itself, putting the injection point immediately before the access in + * question. Use {@link org.spongepowered.asm.mixin.injection.At#shift shift} + * specifier to adjust the matched opcode as necessary.

*/ public class JumpInsnPoint extends InjectionPoint { diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/points/MethodHead.java b/src/main/java/org/spongepowered/asm/mixin/injection/points/MethodHead.java index 501fa910..310e5257 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/points/MethodHead.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/points/MethodHead.java @@ -32,8 +32,10 @@ import org.spongepowered.asm.mixin.injection.InjectionPoint; import org.spongepowered.asm.mixin.injection.struct.InjectionPointData; /** - *

This injection point simply returns the first instruction in the target method body, allowing the injection to be placed at the "head" of the - * target method. It accepts no parameters and only returns a single insn in all circumstances.

+ *

This injection point simply returns the first instruction in the target + * method body, allowing the injection to be placed at the "head" of the target + * method. It accepts no parameters and only returns a single insn in all + * circumstances.

* *

Example:

*
diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/struct/InjectionInfo.java b/src/main/java/org/spongepowered/asm/mixin/injection/struct/InjectionInfo.java
index 8d440288..87525f89 100644
--- a/src/main/java/org/spongepowered/asm/mixin/injection/struct/InjectionInfo.java
+++ b/src/main/java/org/spongepowered/asm/mixin/injection/struct/InjectionInfo.java
@@ -45,7 +45,8 @@ import org.spongepowered.asm.util.ASMHelper;
 
 
 /**
- * Contructs information about an injection from an {@link Inject} annotation and allows the injection to be processed
+ * Contructs information about an injection from an {@link Inject} annotation
+ * and allows the injection to be processed.
  */
 public abstract class InjectionInfo {
     
@@ -78,7 +79,8 @@ public abstract class InjectionInfo {
     protected final Deque targets = new ArrayDeque();
     
     /**
-     * Injection points parsed from {@link org.spongepowered.asm.mixin.injection.At} annotations
+     * Injection points parsed from
+     * {@link org.spongepowered.asm.mixin.injection.At} annotations
      */
     protected final List injectionPoints = new ArrayList();
     
@@ -156,7 +158,8 @@ public abstract class InjectionInfo {
     protected abstract Injector initInjector(AnnotationNode injectAnnotation);
     
     /**
-     * Get whether there is enough valid information in this info to actually perform an injection
+     * Get whether there is enough valid information in this info to actually
+     * perform an injection.
      */
     public boolean isValid() {
         return this.targets.size() > 0 && this.injectionPoints.size() > 0;
diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/struct/InjectionPointData.java b/src/main/java/org/spongepowered/asm/mixin/injection/struct/InjectionPointData.java
index fe892129..c6b28311 100644
--- a/src/main/java/org/spongepowered/asm/mixin/injection/struct/InjectionPointData.java
+++ b/src/main/java/org/spongepowered/asm/mixin/injection/struct/InjectionPointData.java
@@ -32,7 +32,8 @@ import org.spongepowered.asm.mixin.transformer.MixinData;
 
 
 /**
- * Data read from an {@link org.spongepowered.asm.mixin.injection.At} annotation and passed into an InjectionPoint ctor
+ * Data read from an {@link org.spongepowered.asm.mixin.injection.At} annotation
+ * and passed into an InjectionPoint ctor
  */
 public class InjectionPointData {
 
diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/struct/MemberInfo.java b/src/main/java/org/spongepowered/asm/mixin/injection/struct/MemberInfo.java
index 3d870be2..e6b4193d 100644
--- a/src/main/java/org/spongepowered/asm/mixin/injection/struct/MemberInfo.java
+++ b/src/main/java/org/spongepowered/asm/mixin/injection/struct/MemberInfo.java
@@ -33,18 +33,23 @@ import org.spongepowered.asm.mixin.transformer.MixinData;
 
 
 /**
- * 

Information bundle about a member (method or field) parsed from a String token in another annotation, this is used where target members need to - * be specified as Strings in order to parse the String representation to something useful.

+ *

Information bundle about a member (method or field) parsed from a String + * token in another annotation, this is used where target members need to be + * specified as Strings in order to parse the String representation to something + * useful.

* *

Some examples:

*
- *   // references a method or field called func_1234_a, if there are multiple members with the same signature, matches the first occurrence
+ *   // references a method or field called func_1234_a, if there are multiple
+ *   // members with the same signature, matches the first occurrence
  *   func_1234_a
  *   
- *   // references a method or field called func_1234_a, if there are multiple members with the same signature, matches all occurrences
+ *   // references a method or field called func_1234_a, if there are multiple
+ *   // members with the same signature, matches all occurrences
  *   func_1234_a*
  *   
- *   // references a method called func_1234_a which takes 3 ints and returns a bool
+ *   // references a method called func_1234_a which takes 3 ints and returns
+ *   // a bool
  *   func_1234_a(III)Z
  *   
  *   // references a field called field_5678_z which is a String
@@ -59,7 +64,8 @@ import org.spongepowered.asm.mixin.transformer.MixinData;
  *   // references a field called field_5678_z in class com.example.Dave
  *   Lcom/example/Dave;field_5678_z
  *  
- *   // references a method called func_1234_a in class foo.bar.Baz which takes 3 doubles and returns void
+ *   // references a method called func_1234_a in class foo.bar.Baz which takes
+ *   // three doubles and returns void
  *   Lfoo/bar/Baz;func_1234_a(DDD)V
  *   
  *   // alternate syntax for the same
@@ -97,7 +103,8 @@ public class MemberInfo {
     
     /**
      * @param name Member name, must not be null
-     * @param owner Member owner, can be null otherwise must be in internal form without L;
+     * @param owner Member owner, can be null otherwise must be in internal form
+     *      without L;
      */
     public MemberInfo(String name, String owner, boolean matchAll) {
         this(name, owner, null, matchAll);
@@ -105,7 +112,8 @@ public class MemberInfo {
     
     /**
      * @param name Member name, must not be null
-     * @param owner Member owner, can be null otherwise must be in internal form without L;
+     * @param owner Member owner, can be null otherwise must be in internal form
+     *      without L;
      * @param desc Member descriptor, can be null
      * @param matchAll True to match all matching members, not just the first
      */
@@ -121,7 +129,8 @@ public class MemberInfo {
     }
     
     /**
-     * Initialise a MemberInfo using the supplied insn which must be an instance of MethodInsnNode or FieldInsnNode
+     * Initialise a MemberInfo using the supplied insn which must be an instance
+     * of MethodInsnNode or FieldInsnNode.
      */
     public MemberInfo(AbstractInsnNode insn) {
         this.matchAll = false;
@@ -200,21 +209,24 @@ public class MemberInfo {
     }
     
     /**
-     * Get whether this MemberInfo is definitely a field, the output of this method is undefined if {@link #isFullyQualified} returns false
+     * Get whether this MemberInfo is definitely a field, the output of this
+     * method is undefined if {@link #isFullyQualified} returns false.
      */
     public boolean isField() {
         return this.desc != null && !this.desc.startsWith("(");
     }
 
     /**
-     * Test whether this MemberInfo matches the supplied values. Null values are ignored.
+     * Test whether this MemberInfo matches the supplied values. Null values are
+     * ignored.
      */
     public boolean matches(String owner, String name, String desc) {
         return this.matches(owner, name, desc, 0);
     }
     
     /**
-     * Test whether this MemberInfo matches the supplied values at the specified ordinal. Null values are ignored.
+     * Test whether this MemberInfo matches the supplied values at the specified
+     * ordinal. Null values are ignored.
      */
     public boolean matches(String owner, String name, String desc, int ordinal) {
         if (this.desc != null && desc != null && !this.desc.equals(desc)) {
@@ -230,14 +242,16 @@ public class MemberInfo {
     }
 
     /**
-     * Test whether this MemberInfo matches the supplied values. Null values are ignored.
+     * Test whether this MemberInfo matches the supplied values. Null values are
+     * ignored.
      */
     public boolean matches(String name, String desc) {
         return this.matches(name, desc, 0);
     }
     
     /**
-     * Test whether this MemberInfo matches the supplied values at the specified ordinal. Null values are ignored.
+     * Test whether this MemberInfo matches the supplied values at the specified
+     * ordinal. Null values are ignored.
      */
     public boolean matches(String name, String desc, int ordinal) {
         return (this.name == null || this.name.equals(name)) 
diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/struct/Target.java b/src/main/java/org/spongepowered/asm/mixin/injection/struct/Target.java
index 4e4595e8..84f259f3 100644
--- a/src/main/java/org/spongepowered/asm/mixin/injection/struct/Target.java
+++ b/src/main/java/org/spongepowered/asm/mixin/injection/struct/Target.java
@@ -30,7 +30,8 @@ import org.spongepowered.asm.mixin.injection.callback.CallbackInfo;
 
 
 /**
- * Information about the current injection target, mainly just convenience rather than passing a bunch of values around
+ * Information about the current injection target, mainly just convenience
+ * rather than passing a bunch of values around.
  */
 public class Target {
 
diff --git a/src/main/java/org/spongepowered/asm/mixin/transformer/ClassInfo.java b/src/main/java/org/spongepowered/asm/mixin/transformer/ClassInfo.java
index 535287a0..9f86e2d7 100644
--- a/src/main/java/org/spongepowered/asm/mixin/transformer/ClassInfo.java
+++ b/src/main/java/org/spongepowered/asm/mixin/transformer/ClassInfo.java
@@ -41,14 +41,16 @@ import com.google.common.collect.ImmutableList;
 
 
 /**
- * Information about a class, used as a way of keeping track of class hierarchy information needed to support mixins with detached targets.  
+ * Information about a class, used as a way of keeping track of class hierarchy
+ * information needed to support mixins with detached targets.  
  */
 class ClassInfo extends TreeInfo {
     
     private static final String JAVA_LANG_OBJECT = "java/lang/Object";
 
     /**
-     * Loading and parsing classes is expensive, so keep a cache of all the information we generate
+     * Loading and parsing classes is expensive, so keep a cache of all the
+     * information we generate
      */
     private static final Map cache = new HashMap();
     
@@ -263,7 +265,8 @@ class ClassInfo extends TreeInfo {
     }
     
     /**
-     * Get the superclass info, can return null if the superclass cannot be resolved
+     * Get the superclass info, can return null if the superclass cannot be
+     * resolved
      */
     public ClassInfo getSuperClass() {
         if (this.superClass == null && this.superName != null) {
@@ -281,7 +284,8 @@ class ClassInfo extends TreeInfo {
     }
     
     /**
-     * Get the outer class info, can return null if the outer class cannot be resolved or if this is not an inner class
+     * Get the outer class info, can return null if the outer class cannot be
+     * resolved or if this is not an inner class
      */
     public ClassInfo getOuterClass() {
         if (this.outerClass == null && this.outerName != null) {
@@ -308,7 +312,8 @@ class ClassInfo extends TreeInfo {
     /**
      * Test whether this class has the specified superclass in its hierarchy
      *  
-     * @return true if the specified class appears in the class's hierarchy anywhere
+     * @return true if the specified class appears in the class's hierarchy
+     * anywhere
      */
     public boolean hasSuperClass(String superClass) {
         if (ClassInfo.JAVA_LANG_OBJECT.equals(superClass)) {
@@ -361,12 +366,15 @@ class ClassInfo extends TreeInfo {
     }
 
     /**
-     * Finds the owner of the specified private or protected method in this class's hierarchy
+     * Finds the owner of the specified private or protected method in this
+     * class's hierarchy
      * 
      * @param name Method name to search for
      * @param desc Method descriptor
-     * @param includeThisClass True to return this class if the method exists here, or false to search only superclasses
-     * @return the name of the class which contains the specified method or null if the method could not be resolved
+     * @param includeThisClass True to return this class if the method exists
+     *      here, or false to search only superclasses
+     * @return the name of the class which contains the specified method or null
+     *      if the method could not be resolved
      */
     public String findMethodInHierarchy(String name, String desc, boolean includeThisClass) {
         if (includeThisClass && this.hasMethod(name, desc)) {
@@ -417,8 +425,10 @@ class ClassInfo extends TreeInfo {
     }
 
     /**
-     * Return a ClassInfo for the supplied {@link ClassNode}. If a ClassInfo for the class was already defined, then the original ClassInfo is
-     * returned from the internal cache. Otherwise a new ClassInfo is created and returned.
+     * Return a ClassInfo for the supplied {@link ClassNode}. If a ClassInfo for
+     * the class was already defined, then the original ClassInfo is returned
+     * from the internal cache. Otherwise a new ClassInfo is created and
+     * returned.
      * 
      * @param classNode
      * @return
@@ -434,10 +444,12 @@ class ClassInfo extends TreeInfo {
     }
 
     /**
-     * Return a ClassInfo for the specified class name, fetches the ClassInfo from the cache where possible
+     * Return a ClassInfo for the specified class name, fetches the ClassInfo
+     * from the cache where possible
      * 
      * @param className Binary name of the class to look up
-     * @return ClassInfo for the specified class name or null if the specified name cannot be resolved for some reason
+     * @return ClassInfo for the specified class name or null if the specified
+     *      name cannot be resolved for some reason
      */
     public static ClassInfo forName(String className) {
         className = className.replace('.', '/');
diff --git a/src/main/java/org/spongepowered/asm/mixin/transformer/InterfaceInfo.java b/src/main/java/org/spongepowered/asm/mixin/transformer/InterfaceInfo.java
index ad6edd77..53b7c246 100644
--- a/src/main/java/org/spongepowered/asm/mixin/transformer/InterfaceInfo.java
+++ b/src/main/java/org/spongepowered/asm/mixin/transformer/InterfaceInfo.java
@@ -38,12 +38,14 @@ import org.spongepowered.asm.util.ASMHelper;
 
 
 /**
- * Information about an interface being runtime-patched onto a mixin target class, see {@link Implements}
+ * Information about an interface being runtime-patched onto a mixin target
+ * class, see {@link Implements}
  */
 public class InterfaceInfo extends TreeInfo {
     
     /**
-     * Prefix for interface methods. Any methods using this prefix must exist in the target interface
+     * Prefix for interface methods. Any methods using this prefix must exist in
+     * the target interface
      */
     private final String prefix;
     
@@ -78,7 +80,8 @@ public class InterfaceInfo extends TreeInfo {
     }
     
     /**
-     * Reads an interface and its super-interfaces and gathers method names in to the local "methods" collection
+     * Reads an interface and its super-interfaces and gathers method names in
+     * to the local "methods" collection
      */
     private void readInterface(String ifaceName) {
         ClassNode ifaceNode = new ClassNode();
@@ -122,8 +125,10 @@ public class InterfaceInfo extends TreeInfo {
     }
 
     /**
-     * Processes a method node in the mixin and renames it if necessary. If the prefix is found then we verify that the method exists in the target
-     * interface and throw our teddies out of the pram if that's not the case (replacement behaviour for {@link Override} essentially. 
+     * Processes a method node in the mixin and renames it if necessary. If the
+     * prefix is found then we verify that the method exists in the target
+     * interface and throw our teddies out of the pram if that's not the case
+     * (replacement behaviour for {@link Override} essentially. 
      */
     public boolean renameMethod(MethodNode method) {
         if (this.methods == null) {
@@ -145,7 +150,8 @@ public class InterfaceInfo extends TreeInfo {
     }
 
     /**
-     * Convert an {@link Interface} annotation node into an {@link InterfaceInfo}
+     * Convert an {@link Interface} annotation node into an
+     * {@link InterfaceInfo}
      */
     static InterfaceInfo fromAnnotation(AnnotationNode node) {
         String prefix = ASMHelper.getAnnotationValue(node, "prefix");
diff --git a/src/main/java/org/spongepowered/asm/mixin/transformer/MixinClassWriter.java b/src/main/java/org/spongepowered/asm/mixin/transformer/MixinClassWriter.java
index 29093bea..8166fa8b 100644
--- a/src/main/java/org/spongepowered/asm/mixin/transformer/MixinClassWriter.java
+++ b/src/main/java/org/spongepowered/asm/mixin/transformer/MixinClassWriter.java
@@ -28,7 +28,8 @@ import org.objectweb.asm.ClassReader;
 import org.objectweb.asm.ClassWriter;
 
 /**
- * ClassWriter which resolves common superclasses using Mixin's metadata instead of calling Class.forName
+ * ClassWriter which resolves common superclasses using Mixin's metadata instead
+ * of calling Class.forName
  */
 public class MixinClassWriter extends ClassWriter {
 
@@ -43,7 +44,8 @@ public class MixinClassWriter extends ClassWriter {
     }
 
     /* (non-Javadoc)
-     * @see org.objectweb.asm.ClassWriter#getCommonSuperClass(java.lang.String, java.lang.String)
+     * @see org.objectweb.asm.ClassWriter#getCommonSuperClass(java.lang.String,
+     *      java.lang.String)
      */
     @Override
     protected String getCommonSuperClass(final String type1, final String type2) {
diff --git a/src/main/java/org/spongepowered/asm/mixin/transformer/MixinConfig.java b/src/main/java/org/spongepowered/asm/mixin/transformer/MixinConfig.java
index 83a0b1a9..2e2803bf 100644
--- a/src/main/java/org/spongepowered/asm/mixin/transformer/MixinConfig.java
+++ b/src/main/java/org/spongepowered/asm/mixin/transformer/MixinConfig.java
@@ -49,7 +49,8 @@ import com.google.gson.annotations.SerializedName;
 class MixinConfig implements Comparable {
     
     /**
-     * Global order of mixin configs, used to determine ordering between configs with equivalent priority
+     * Global order of mixin configs, used to determine ordering between configs
+     * with equivalent priority
      */
     private static int configOrder = 0;
 
@@ -75,7 +76,8 @@ class MixinConfig implements Comparable {
     private final int priority = 1000;
 
     /**
-     * Package containing all mixins. This package will be monitored by the transformer so that we can explode if some dummy tries to reference a
+     * Package containing all mixins. This package will be monitored by the
+     * transformer so that we can explode if some dummy tries to reference a
      * mixin class directly.
      */
     @SerializedName("package")
@@ -94,7 +96,8 @@ class MixinConfig implements Comparable {
     private List mixinClassesClient;
     
     /**
-     * Mixin classes to load ONLY on dedicated server, mixinPackage will be prepended
+     * Mixin classes to load ONLY on dedicated server, mixinPackage will be
+     * prepended
      */
     @SerializedName("server")
     private List mixinClassesServer;
@@ -187,13 +190,17 @@ class MixinConfig implements Comparable {
     }
 
     /**
-     * 

Initialisation routine. It's important that we call this routine as late as possible. In general we want to call it on the first call to - * transform() in the parent transformer. At the very least we want to be called after all the transformers for the current environment - * have been spawned, because we will run the mixin bytecode through the transformer chain and naturally we want this to happen at a point when - * we can be reasonably sure that all transfomers have loaded.

+ *

Initialisation routine. It's important that we call this routine as + * late as possible. In general we want to call it on the first call to + * transform() in the parent transformer. At the very least we want to be + * called after all the transformers for the current environment + * have been spawned, because we will run the mixin bytecode through the + * transformer chain and naturally we want this to happen at a point when we + * can be reasonably sure that all transfomers have loaded.

* - *

For this reason we will invoke the initialisation on the first call to either the hasMixinsFor() or getMixinsFor() - * methods.

+ *

For this reason we will invoke the initialisation on the first call to + * either the hasMixinsFor() or getMixinsFor() methods. + *

*/ void initialise() { if (this.initialised) { @@ -250,7 +257,8 @@ class MixinConfig implements Comparable { } /** - * Get the name of the file from which this configuration object was initialised + * Get the name of the file from which this configuration object was + * initialised */ public String getName() { return this.name; @@ -271,7 +279,8 @@ class MixinConfig implements Comparable { } /** - * Get whether to propogate the source file attribute from a mixin onto the target class + * Get whether to propogate the source file attribute from a mixin onto the + * target class */ public boolean shouldSetSourceFile() { return this.setSourceFile; @@ -299,7 +308,8 @@ class MixinConfig implements Comparable { } /** - * Check whether this configuration bundle has a mixin for the specified class + * Check whether this configuration bundle has a mixin for the specified + * class * * @param targetClass * @return @@ -342,7 +352,8 @@ class MixinConfig implements Comparable { } /** - * Factory method, creates a new mixin configuration bundle from the specified configFile, which must be accessible on the classpath + * Factory method, creates a new mixin configuration bundle from the + * specified configFile, which must be accessible on the classpath * * @param configFile * @return diff --git a/src/main/java/org/spongepowered/asm/mixin/transformer/MixinData.java b/src/main/java/org/spongepowered/asm/mixin/transformer/MixinData.java index 9c0c0e6c..d67ba665 100644 --- a/src/main/java/org/spongepowered/asm/mixin/transformer/MixinData.java +++ b/src/main/java/org/spongepowered/asm/mixin/transformer/MixinData.java @@ -47,8 +47,9 @@ import org.spongepowered.asm.util.ASMHelper; /** - * Data for applying a mixin. Keeps a copy of the mixin tree and also handles any pre-transformations required by the mixin class itself such as - * method renaming and any other pre-processing of the mixin bytecode. + * Data for applying a mixin. Keeps a copy of the mixin tree and also handles + * any pre-transformations required by the mixin class itself such as method + * renaming and any other pre-processing of the mixin bytecode. */ public class MixinData { @@ -83,7 +84,8 @@ public class MixinData { private final Set interfaces = new HashSet(); /** - * Information about methods in the target class, used to keep track of transformations we apply + * Information about methods in the target class, used to keep track of + * transformations we apply */ private final Map targetMethods = new HashMap(); @@ -178,7 +180,8 @@ public class MixinData { } /** - * Get whether to propogate the source file attribute from a mixin onto the target class + * Get whether to propogate the source file attribute from a mixin onto the + * target class */ public boolean shouldSetSourceFile() { return this.info.getParent().shouldSetSourceFile(); @@ -266,12 +269,14 @@ public class MixinData { } /** - * Gets an annotation value or returns the default if the annotation value is not present + * Gets an annotation value or returns the default if the annotation value + * is not present * * @param annotation * @param key * @param annotationClass - * @return Value of the specified annotation node, default value if not specified, or null if no value or default + * @return Value of the specified annotation node, default value if not + * specified, or null if no value or default */ private static String getAnnotationValue(AnnotationNode annotation, String key, Class annotationClass) { String value = ASMHelper.getAnnotationValue(annotation, key); diff --git a/src/main/java/org/spongepowered/asm/mixin/transformer/MixinInfo.java b/src/main/java/org/spongepowered/asm/mixin/transformer/MixinInfo.java index c89feef0..c636a73d 100644 --- a/src/main/java/org/spongepowered/asm/mixin/transformer/MixinInfo.java +++ b/src/main/java/org/spongepowered/asm/mixin/transformer/MixinInfo.java @@ -51,7 +51,8 @@ import com.google.common.collect.Lists; class MixinInfo extends TreeInfo implements Comparable, IMixinInfo { /** - * Global order of mixin infos, used to determine ordering between mixins with equivalent priority + * Global order of mixin infos, used to determine ordering between mixins + * with equivalent priority */ static int mixinOrder = 0; @@ -96,7 +97,8 @@ class MixinInfo extends TreeInfo implements Comparable, IMixinInfo { private final List targetClassNames; /** - * True if the superclass of the mixin is not the direct superclass of one or more targets + * True if the superclass of the mixin is not the direct superclass + * of one or more targets */ private final boolean detachedSuper; @@ -144,7 +146,8 @@ class MixinInfo extends TreeInfo implements Comparable, IMixinInfo { } /** - * Initialises the class info and performs some pre-flight checks on the mixin + * Initialises the class info and performs some pre-flight checks on the + * mixin * * @param classNode * @return @@ -290,7 +293,8 @@ class MixinInfo extends TreeInfo implements Comparable, IMixinInfo { } /** - * True if the superclass of the mixin is not the direct superclass of one or more targets + * True if the superclass of the mixin is not the direct superclass + * of one or more targets */ @Override public boolean isDetachedSuper() { diff --git a/src/main/java/org/spongepowered/asm/mixin/transformer/MixinMerged.java b/src/main/java/org/spongepowered/asm/mixin/transformer/MixinMerged.java index 24db89cd..740601a6 100644 --- a/src/main/java/org/spongepowered/asm/mixin/transformer/MixinMerged.java +++ b/src/main/java/org/spongepowered/asm/mixin/transformer/MixinMerged.java @@ -30,9 +30,11 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - *

For internal use only! Contains small parts. Keep out of reach of children.

+ *

For internal use only! Contains small parts. Keep out of reach of + * children.

* - *

Decoration annotation used by the {@link MixinTransformer} to mark methods in a class which have been added or overwritten by a mixin.

+ *

Decoration annotation used by the {@link MixinTransformer} to mark methods + * in a class which have been added or overwritten by a mixin.

*/ @Target({ ElementType.METHOD }) @Retention(RetentionPolicy.RUNTIME) @@ -43,8 +45,9 @@ public @interface MixinMerged { public String mixin(); /** - * Prioriy of the mixin which merged this method, used to allow mixins with higher priority to overwrite methods already overwritten by those - * with a lower priority. + * Prioriy of the mixin which merged this method, used to allow mixins with + * higher priority to overwrite methods already overwritten by those with a + * lower priority. */ public int priority(); } diff --git a/src/main/java/org/spongepowered/asm/mixin/transformer/MixinTransformer.java b/src/main/java/org/spongepowered/asm/mixin/transformer/MixinTransformer.java index cc535611..2e32be0d 100644 --- a/src/main/java/org/spongepowered/asm/mixin/transformer/MixinTransformer.java +++ b/src/main/java/org/spongepowered/asm/mixin/transformer/MixinTransformer.java @@ -111,9 +111,12 @@ public class MixinTransformer extends TreeTransformer { private static final String CLINIT = ""; /** - * List of opcodes which must not appear in a class initialiser, mainly a sanity check so that if any of the specified opcodes are found, we can - * log it as an error condition and then people can bitch at me to fix it. Essentially if it turns out that field initialisers can somehow make - * use of local variables, then I need to write some code to ensure that said locals are shifted so that they don't interfere with locals in the + * List of opcodes which must not appear in a class initialiser, mainly a + * sanity check so that if any of the specified opcodes are found, we can + * log it as an error condition and then people can bitch at me to fix it. + * Essentially if it turns out that field initialisers can somehow make use + * of local variables, then I need to write some code to ensure that said + * locals are shifted so that they don't interfere with locals in the * receiving constructor. */ private static final int[] INITIALISER_OPCODE_BLACKLIST = { @@ -136,19 +139,23 @@ public class MixinTransformer extends TreeTransformer { private final List configs = new ArrayList(); /** - * True once initialisation is done. All mixin configs needs to be initialised as late as possible in startup (so that other transformers have - * had time to register) but before any game classes are transformed. To do this we initialise the configs on the first call to {@link #transform} - * and this flag keeps track of when we've done this. + * True once initialisation is done. All mixin configs needs to be + * initialised as late as possible in startup (so that other transformers + * have had time to register) but before any game classes are transformed. + * To do this we initialise the configs on the first call to + * {@link #transform} and this flag keeps track of when we've done this. */ private boolean initDone; /** - * Sanity check for this transformer. The transformer should never be re-entrant by design so we need to detect and warn when it happens. + * Sanity check for this transformer. The transformer should never be + * re-entrant by design so we need to detect and warn when it happens. */ private int reEntranceCheck = 0; /** - * Session ID, used as a check when parsing {@link MixinMerged} annotations to prevent them being applied at compile time by people trying to + * Session ID, used as a check when parsing {@link MixinMerged} annotations + * to prevent them being applied at compile time by people trying to * circumvent mixin application */ private final String sessionId = UUID.randomUUID().toString(); @@ -182,7 +189,8 @@ public class MixinTransformer extends TreeTransformer { } /* (non-Javadoc) - * @see net.minecraft.launchwrapper.IClassTransformer#transform(java.lang.String, java.lang.String, byte[]) + * @see net.minecraft.launchwrapper.IClassTransformer + * #transform(java.lang.String, java.lang.String, byte[]) */ @Override public byte[] transform(String name, String transformedName, byte[] basicClass) { @@ -289,7 +297,8 @@ public class MixinTransformer extends TreeTransformer { } /** - * Apply mixins for specified target class to the class described by the supplied byte array + * Apply mixins for specified target class to the class described by the + * supplied byte array. * * @param transformedName * @param basicClass @@ -381,8 +390,10 @@ public class MixinTransformer extends TreeTransformer { } /** - * Mixin fields from mixin class into the target class. It is vital that this is done before mixinMethods because we need to compute renamed - * fields so that transformMethod can rename field references in the method body + * Mixin fields from mixin class into the target class. It is vital that + * this is done before mixinMethods because we need to compute renamed + * fields so that transformMethod can rename field references in the method + * body. * * @param targetClass * @param mixin @@ -452,8 +463,10 @@ public class MixinTransformer extends TreeTransformer { } /** - * Handles "re-parenting" the method supplied, changes all references to the mixin class to refer to the target class (for field accesses and - * method invokations) and also handles fixing up the targets of INVOKESPECIAL opcodes for mixins with detached targets. + * Handles "re-parenting" the method supplied, changes all references to the + * mixin class to refer to the target class (for field accesses and method + * invokations) and also handles fixing up the targets of INVOKESPECIAL + * opcodes for mixins with detached targets. * * @param mixin * @param target @@ -484,7 +497,8 @@ public class MixinTransformer extends TreeTransformer { } /** - * Update INVOKESPECIAL opcodes to target the topmost class in the hierarchy which contains the specified method. + * Update INVOKESPECIAL opcodes to target the topmost class in the hierarchy + * which contains the specified method. * * @param mixin * @param target @@ -509,7 +523,8 @@ public class MixinTransformer extends TreeTransformer { * @param targetClass Target class to merge into * @param mixin Mixin being applied * @param method Method to merge - * @param isOverwrite true if the method is annotated with an {@link Overwrite} annotation + * @param isOverwrite true if the method is annotated with an + * {@link Overwrite} annotation */ private void mergeMethod(ClassNode targetClass, MixinData mixin, MethodNode method, boolean isOverwrite) { MethodNode target = this.findTargetMethod(targetClass, method); @@ -546,7 +561,8 @@ public class MixinTransformer extends TreeTransformer { } /** - * Handles appending instructions from the source method to the target method + * Handles appending instructions from the source method to the target + * method * * @param targetClass * @param targetMethodName @@ -592,7 +608,8 @@ public class MixinTransformer extends TreeTransformer { } /** - * (Attempts to) find and patch field initialisers from the mixin into the target class + * (Attempts to) find and patch field initialisers from the mixin into the + * target class * * @param targetClass * @param mixin @@ -648,10 +665,12 @@ public class MixinTransformer extends TreeTransformer { } /** - * Identifies line numbers in the supplied ctor which correspond to the start and end of the method body. + * Identifies line numbers in the supplied ctor which correspond to the + * start and end of the method body. * * @param ctor - * @return range indicating the line numbers of the specified constructor and the position of the superclass ctor invocation + * @return range indicating the line numbers of the specified constructor + * and the position of the superclass ctor invocation */ private Range getConstructorRange(MethodNode ctor) { int line = 0, start = 0, end = 0, superIndex = -1; @@ -673,12 +692,15 @@ public class MixinTransformer extends TreeTransformer { } /** - * Get insns corresponding to the instance initialiser (hopefully) from the supplied constructor. + * Get insns corresponding to the instance initialiser (hopefully) from the + * supplied constructor. + * * TODO Potentially rewrite this to be less horrible. * * @param mixin * @param ctor - * @return initialiser bytecode extracted from the supplied constructor, or null if the constructor range could not be parsed + * @return initialiser bytecode extracted from the supplied constructor, or + * null if the constructor range could not be parsed */ private InsnList getInitialiser(MethodNode ctor) { // Find the range of line numbers which corresponds to the constructor body @@ -747,7 +769,8 @@ public class MixinTransformer extends TreeTransformer { } /** - * Process {@link Inject} annotations and inject callbacks to annotated methods + * Process {@link Inject} annotations and inject callbacks to annotated + * methods * * @param targetClass * @param mixin diff --git a/src/main/java/org/spongepowered/asm/mixin/transformer/TreeInfo.java b/src/main/java/org/spongepowered/asm/mixin/transformer/TreeInfo.java index b3664892..1c87eabb 100644 --- a/src/main/java/org/spongepowered/asm/mixin/transformer/TreeInfo.java +++ b/src/main/java/org/spongepowered/asm/mixin/transformer/TreeInfo.java @@ -124,11 +124,13 @@ abstract class TreeInfo { } /** - * Since we obtain the class bytes with getClassBytes(), we need to apply the transformers ourself + * Since we obtain the class bytes with getClassBytes(), we need to apply + * the transformers ourself * * @param name * @param basicClass - * @return class bytecode after processing by all registered transformers except the excluded transformers + * @return class bytecode after processing by all registered transformers + * except the excluded transformers */ private static byte[] applyTransformers(String name, byte[] basicClass) { final List transformers = Launch.classLoader.getTransformers(); diff --git a/src/main/java/org/spongepowered/asm/util/ASMHelper.java b/src/main/java/org/spongepowered/asm/util/ASMHelper.java index e5525b6b..a9c7b7e1 100644 --- a/src/main/java/org/spongepowered/asm/util/ASMHelper.java +++ b/src/main/java/org/spongepowered/asm/util/ASMHelper.java @@ -202,7 +202,8 @@ public class ASMHelper { } /** - * Replace a method's code with a forward to an method on its first argument. + * Replace a method's code with a forward to an method on its first + * argument. * * @param method Method to replace code of * @param forwardname Name of method to forward to @@ -272,8 +273,9 @@ public class ASMHelper { } /** - * Gets an instruction that pushes a integer onto the stack. The instruction uses - * the smallest push possible (ICONST_*, BIPUSH, SIPUSH or Integer constant). + * Gets an instruction that pushes a integer onto the stack. The + * instruction uses the smallest push possible (ICONST_*, BIPUSH, SIPUSH or + * Integer constant). * * @param c the integer to push onto the stack */ @@ -345,7 +347,8 @@ public class ASMHelper { } /** - * Set a runtime-visible annotation of the specified class on the supplied field node + * Set a runtime-visible annotation of the specified class on the supplied + * field node * * @param field Target field * @param annotationClass Type of annotation to search for @@ -357,7 +360,8 @@ public class ASMHelper { } /** - * Set an invisible annotation of the specified class on the supplied field node + * Set an invisible annotation of the specified class on the supplied field + * node * * @param field Target field * @param annotationClass Type of annotation to search for @@ -369,7 +373,8 @@ public class ASMHelper { } /** - * Set a runtime-visible annotation of the specified class on the supplied method node + * Set a runtime-visible annotation of the specified class on the supplied + * method node * * @param method Target method * @param annotationClass Type of annotation to search for @@ -381,7 +386,8 @@ public class ASMHelper { } /** - * Set a invisible annotation of the specified class on the supplied method node + * Set a invisible annotation of the specified class on the supplied method + * node * * @param method Target method * @param annotationClass Type of annotation to search for @@ -395,7 +401,8 @@ public class ASMHelper { /** * Create a new annotation node with the supplied values * - * @param annotationType Name (internal name) of the annotation interface to create + * @param annotationType Name (internal name) of the annotation interface to + * create * @param value Interleaved key/value pairs. Keys must be strings * @return new annotation node */ @@ -422,7 +429,8 @@ public class ASMHelper { } /** - * Get a runtime-visible annotation of the specified class from the supplied field node + * Get a runtime-visible annotation of the specified class from the supplied + * field node * * @param field Source field * @param annotationClass Type of annotation to search for @@ -433,7 +441,8 @@ public class ASMHelper { } /** - * Get an invisible annotation of the specified class from the supplied field node + * Get an invisible annotation of the specified class from the supplied + * field node * * @param field Source field * @param annotationClass Type of annotation to search for @@ -444,7 +453,8 @@ public class ASMHelper { } /** - * Get a runtime-visible annotation of the specified class from the supplied method node + * Get a runtime-visible annotation of the specified class from the supplied + * method node * * @param method Source method * @param annotationClass Type of annotation to search for @@ -455,7 +465,8 @@ public class ASMHelper { } /** - * Get an invisible annotation of the specified class from the supplied method node + * Get an invisible annotation of the specified class from the supplied + * method node * * @param method Source method * @param annotationClass Type of annotation to search for @@ -466,7 +477,8 @@ public class ASMHelper { } /** - * Get a runtime-visible annotation of the specified class from the supplied method node + * Get a runtime-visible annotation of the specified class from the supplied + * method node * * @param method Source method * @param annotationClasses Types of annotation to search for @@ -477,7 +489,8 @@ public class ASMHelper { } /** - * Get an invisible annotation of the specified class from the supplied method node + * Get an invisible annotation of the specified class from the supplied + * method node * * @param method Source method * @param annotationClasses Types of annotation to search for @@ -488,7 +501,8 @@ public class ASMHelper { } /** - * Get a runtime-visible annotation of the specified class from the supplied class node + * Get a runtime-visible annotation of the specified class from the supplied + * class node * * @param classNode Source classNode * @param annotationClass Type of annotation to search for @@ -499,7 +513,8 @@ public class ASMHelper { } /** - * Get an invisible annotation of the specified class from the supplied class node + * Get an invisible annotation of the specified class from the supplied + * class node * * @param classNode Source classNode * @param annotationClass Type of annotation to search for @@ -510,7 +525,8 @@ public class ASMHelper { } /** - * Search for and return an annotation node matching the specified type within the supplied + * Search for and return an annotation node matching the specified type + * within the supplied * collection of annotation nodes * * @param annotations Haystack @@ -552,19 +568,23 @@ public class ASMHelper { * Duck type the "value" entry (if any) of the specified annotation node * * @param annotation Annotation node to query - * @return duck-typed annotation value, null if missing, or inevitable ClassCastException if your duck is actually a rooster + * @return duck-typed annotation value, null if missing, or inevitable + * {@link ClassCastException} if your duck is actually a rooster */ public static T getAnnotationValue(AnnotationNode annotation) { return ASMHelper.getAnnotationValue(annotation, "value"); } /** - * Get the value of an annotation node and do pseudo-duck-typing via Java's crappy generics + * Get the value of an annotation node and do pseudo-duck-typing via Java's + * crappy generics * * @param annotation Annotation node to query * @param key Key to search for - * @param defaultValue Value to return if the specified key is not found or is null - * @return duck-typed annotation value, null if missing, or inevitable ClassCastException if your duck is actually a rooster + * @param defaultValue Value to return if the specified key is not found or + * is null + * @return duck-typed annotation value, null if missing, or inevitable + * {@link ClassCastException} if your duck is actually a rooster */ public static T getAnnotationValue(AnnotationNode annotation, String key, T defaultValue) { T returnValue = ASMHelper.getAnnotationValue(annotation, key); @@ -572,11 +592,13 @@ public class ASMHelper { } /** - * Get the value of an annotation node and do pseudo-duck-typing via Java's crappy generics + * Get the value of an annotation node and do pseudo-duck-typing via Java's + * crappy generics * * @param annotation Annotation node to query * @param key Key to search for - * @return duck-typed annotation value, null if missing, or inevitable ClassCastException if your duck is actually a rooster + * @return duck-typed annotation value, null if missing, or inevitable + * {@link ClassCastException} if your duck is actually a rooster */ @SuppressWarnings("unchecked") public static T getAnnotationValue(AnnotationNode annotation, String key) { @@ -600,7 +622,8 @@ public class ASMHelper { } /** - * Get the value of an annotation node as the specified enum, returns defaultValue if the annotation value is not set + * Get the value of an annotation node as the specified enum, returns + * defaultValue if the annotation value is not set * * @param annotationNode Annotation node to query * @param key Key to search for @@ -628,30 +651,38 @@ public class ASMHelper { } /** - * Get the first variable index in the supplied method which is not an argument or "this" reference, this corresponds to the size of the arguments - * passed in to the method plus an extra spot for "this" if the method is non-static + * Get the first variable index in the supplied method which is not an + * argument or "this" reference, this corresponds to the size of the + * arguments passed in to the method plus an extra spot for "this" if the + * method is non-static * * @param method MethodNode to inspect - * @return first available local index which is NOT used by a method argument or "this" + * @return first available local index which is NOT used by a method + * argument or "this" */ public static int getFirstNonArgLocalIndex(MethodNode method) { return ASMHelper.getFirstNonArgLocalIndex(Type.getArgumentTypes(method.desc), (method.access & Opcodes.ACC_STATIC) == 0); } /** - * Get the first non-arg variable index based on the supplied arg array and whether to include the "this" reference, this corresponds to the size - * of the arguments passed in to the method plus an extra spot for "this" is specified + * Get the first non-arg variable index based on the supplied arg array and + * whether to include the "this" reference, this corresponds to the size of + * the arguments passed in to the method plus an extra spot for "this" is + * specified * * @param args Method arguments - * @param includeThis Whether to include a slot for "this" (generally true for all non-static methods) - * @return first available local index which is NOT used by a method argument or "this" + * @param includeThis Whether to include a slot for "this" (generally true + * for all non-static methods) + * @return first available local index which is NOT used by a method + * argument or "this" */ public static int getFirstNonArgLocalIndex(Type[] args, boolean includeThis) { return ASMHelper.getArgsSize(args) + (includeThis ? 1 : 0); } /** - * Get the size of the specified args array in local variable terms (eg. doubles and longs take two spaces) + * Get the size of the specified args array in local variable terms (eg. + * doubles and longs take two spaces) * * @param args Method argument types as array * @return size of the specified arguments array in terms of stack slots @@ -667,7 +698,8 @@ public class ASMHelper { } /** - * Injects appropriate LOAD opcodes into the supplied InsnList appropriate for each entry in the args array starting at pos + * Injects appropriate LOAD opcodes into the supplied InsnList appropriate + * for each entry in the args array starting at pos * * @param args Argument types * @param insns Instruction List to inject into @@ -678,7 +710,8 @@ public class ASMHelper { } /** - * Injects appropriate LOAD opcodes into the supplied InsnList appropriate for each entry in the args array starting at start and ending at end + * Injects appropriate LOAD opcodes into the supplied InsnList appropriate + * for each entry in the args array starting at start and ending at end * * @param args Argument types * @param insns Instruction List to inject into diff --git a/src/main/java/org/spongepowered/asm/util/Locals.java b/src/main/java/org/spongepowered/asm/util/Locals.java index 46de4f40..225bf33f 100644 --- a/src/main/java/org/spongepowered/asm/util/Locals.java +++ b/src/main/java/org/spongepowered/asm/util/Locals.java @@ -53,14 +53,17 @@ import org.objectweb.asm.tree.analysis.SimpleVerifier; public class Locals { /** - * Cached local variable lists, to avoid having to recalculate them (expensive) if multiple injectors are working with the same method + * Cached local variable lists, to avoid having to recalculate them + * (expensive) if multiple injectors are working with the same method */ private static final Map> calculatedLocalVariables = new HashMap>(); /** - * Injects appropriate LOAD opcodes into the supplied InsnList for each entry in the supplied locals array starting at pos + * Injects appropriate LOAD opcodes into the supplied InsnList for each + * entry in the supplied locals array starting at pos * - * @param locals Local types (can contain nulls for uninitialised, TOP, or RETURN values in locals) + * @param locals Local types (can contain nulls for uninitialised, TOP, or + * RETURN values in locals) * @param insns Instruction List to inject into * @param pos Start position */ @@ -73,9 +76,11 @@ public class Locals { } /** - *

Attempts to identify available locals at an arbitrary point in the bytecode specified by node.

+ *

Attempts to identify available locals at an arbitrary point in the + * bytecode specified by node.

* - *

This method builds an approximate view of the locals available at an arbitrary point in the bytecode by examining the following features in + *

This method builds an approximate view of the locals available at an + * arbitrary point in the bytecode by examining the following features in * the bytecode:

*
    *
  • Any available stack map frames
  • @@ -83,22 +88,34 @@ public class Locals { *
  • The local variable table
  • *
* - *

Inference proceeds by walking the bytecode from the start of the method looking for stack frames and STORE opcodes. When either of these is - * encountered, an attempt is made to cross-reference the values in the stack map or STORE opcode with the value in the local variable table which - * covers the code range. Stack map frames overwrite the entire simulated local variable table with their own value types, STORE opcodes overwrite - * only the local slot to which they pertain. Values in the simulated locals array are spaced according to their size (unlike the representation - * in FrameNode) and this TOP, NULL and UNINTITIALIZED_THIS opcodes will be represented as null values in the simulated frame.

+ *

Inference proceeds by walking the bytecode from the start of the + * method looking for stack frames and STORE opcodes. When either of these + * is encountered, an attempt is made to cross-reference the values in the + * stack map or STORE opcode with the value in the local variable table + * which covers the code range. Stack map frames overwrite the entire + * simulated local variable table with their own value types, STORE opcodes + * overwrite only the local slot to which they pertain. Values in the + * simulated locals array are spaced according to their size (unlike the + * representation in FrameNode) and this TOP, NULL and UNINTITIALIZED_THIS + * opcodes will be represented as null values in the simulated frame.

* - *

This code does not currently simulate the prescribed JVM behaviour where overwriting the second slot of a DOUBLE or LONG actually - * invalidates the DOUBLE or LONG stored in the previous location, so we have to hope (for now) that this behaviour isn't emitted by the compiler - * or any upstream transformers. I may have to re-think this strategy if this situation is encountered in the wild.

+ *

This code does not currently simulate the prescribed JVM behaviour + * where overwriting the second slot of a DOUBLE or LONG actually + * invalidates the DOUBLE or LONG stored in the previous location, so we + * have to hope (for now) that this behaviour isn't emitted by the compiler + * or any upstream transformers. I may have to re-think this strategy if + * this situation is encountered in the wild.

* - * @param classNode ClassNode containing the method, used to initialise the implicit "this" reference in simple methods with no stack frames + * @param classNode ClassNode containing the method, used to initialise the + * implicit "this" reference in simple methods with no stack frames * @param method MethodNode to explore - * @param node Node indicating the position at which to determine the locals state. The locals will be enumerated UP TO the specified node, so - * bear in mind that if the specified node is itself a STORE opcode, then we will be looking at the state of the locals PRIOR to its - * invokation - * @return A sparse array containing a view (hopefully) of the locals at the specified location + * @param node Node indicating the position at which to determine the locals + * state. The locals will be enumerated UP TO the specified node, so + * bear in mind that if the specified node is itself a STORE opcode, + * then we will be looking at the state of the locals PRIOR to its + * invocation + * @return A sparse array containing a view (hopefully) of the locals at the + * specified location */ public static LocalVariableNode[] getLocalsAt(ClassNode classNode, MethodNode method, AbstractInsnNode node) { LocalVariableNode[] frame = new LocalVariableNode[method.maxLocals]; @@ -156,13 +173,16 @@ public class Locals { } /** - * Attempts to locate the appropriate entry in the local variable table for the specified local variable index at the location specified by node. + * Attempts to locate the appropriate entry in the local variable table for + * the specified local variable index at the location specified by node. * * @param classNode Containing class * @param method Method - * @param node Instruction defining the location to get the local variable table at + * @param node Instruction defining the location to get the local variable + * table at * @param var Local variable index - * @return a LocalVariableNode containing information about the local variable at the specified location in the specified local slot + * @return a LocalVariableNode containing information about the local + * variable at the specified location in the specified local slot */ public static LocalVariableNode getLocalVariableAt(ClassNode classNode, MethodNode method, AbstractInsnNode node, int var) { LocalVariableNode localVariableNode = null; @@ -185,8 +205,10 @@ public class Locals { } /** - * Fetches or generates the local variable table for the specified method. Since Mojang strip the local variable table as part of the obfuscation - * process, we need to generate the local variable table when running obfuscated. We cache the generated tables so that we only need to do the + * Fetches or generates the local variable table for the specified method. + * Since Mojang strip the local variable table as part of the obfuscation + * process, we need to generate the local variable table when running + * obfuscated. We cache the generated tables so that we only need to do the * relatively expensive calculation once per method we encounter. * * @param classNode Containing class @@ -210,7 +232,8 @@ public class Locals { } /** - * Use ASM Analyzer to generate the local variable table for the specified method + * Use ASM Analyzer to generate the local variable table for the specified + * method * * @param classNode Containing class * @param method Method