Add checkstyle rule for javadoc and update all javadocs to 80 cols

This commit is contained in:
Mumfrey committed 2015-01-20 13:49:14 +00:00
1 parent 116ecb0458
commit e87402bf70
49 files changed
+844 -432

No files matched your search

+4
View File
@@ -49,6 +49,10 @@
<property name="max" value="150"/>
<property name="ignorePattern" value="^package.*|^import.*|a href|href|http://|https://|ftp://"/>
</module>
<module name="LineLength">
<property name="max" value="80"/>
<property name="ignorePattern" value="^[ ]*([a-zA-Z0-9\{\}\+\|\&amp;\&quot;@]|//)"/>
</module>
<!-- module name="AvoidStarImport"/>-->
<!-- Check doesn't exist in current release of checkstyle -->
<!--<module name="OneTopLevelClass"/>-->
@@ -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)) {
@@ -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);
@@ -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<? extends TypeElement> 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<? extends Annotation> injectorClass) {
for (Element elem : roundEnv.getElementsAnnotatedWith(injectorClass)) {
@@ -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) {
@@ -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<? extends TypeElement> 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)) {
@@ -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<String> 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) {
@@ -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)
@@ -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 <b>must</b> end with a dollar sign ($)
* [Required] prefix for implementing interface methods. Works similarly to
* {@link Shadow} prefixes, but <b>must</b> end with a dollar sign ($)
*/
public String prefix();
@@ -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 <code>remap</code> to <em>false</em> on the individual annotations, or disabled for the entire
* mixin by setting the value here to <em>false</em>. 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 <code>remap</code> to
* <em>false</em> on the individual annotations, or disabled for the entire
* mixin by setting the value here to <em>false</em>. Doing so will cause
* the annotation processor to skip all annotations in this mixin when
* building the obfuscation table.
*/
public boolean remap() default true;
@@ -30,17 +30,25 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* <p>Annotation used to indicate a mixin class member which must overwrite an obfuscated method in the target class.</p>
* <p>Annotation used to indicate a mixin class member which must overwrite an
* obfuscated method in the target class.</p>
*
* <p>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.</p>
* <p>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.</p>
*
* <p>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.</p>
* <p>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.</p>
*
* <p>Adding this annotation to a non-obfuscated method will cause the annotation processor to raise an error at compile time.</p>
* <p>Adding this annotation to a non-obfuscated method will cause the
* annotation processor to raise an error at compile time.</p>
*/
@Target({ ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
@@ -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
/**
* <p>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
* <p>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.</p>
*
* <p>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</p>:
* <p>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</p>:
*
* <blockquote><pre>
* &#64;Shadow abstract void someMethod(int arg1, int arg2);
@@ -55,22 +63,34 @@ public @interface Shadow {
* &#64;Shadow(prefix = "foo$") abstract void foo$someMethod(int arg1, int arg2);
* </pre></blockquote>
*
* <p>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.</p>
* <p>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.</p>
*
* <p>Note that specifying a <em>prefix</em> does not <b>enforce</b> use of the prefix, the behaviour of <em>prefix</em> is such that the prefix
* will be stripped from the start of the method name <em>as long as the method name actually starts with the prefix</em>! This has important
* repercussions since if the annotation value does not match the method prefix then <em>no renaming will take place</em> likey resulting in
* a failure state indicated by an {@link InvalidMixinException} at run time.</p>
* <p>Note that specifying a <em>prefix</em> does not <b>enforce</b> use of
* the prefix, the behaviour of <em>prefix</em> is such that the prefix will
* be stripped from the start of the method name <em>as long as the method
* name actually starts with the prefix</em>! This has important
* repercussions since if the annotation value does not match the method
* prefix then <em>no renaming will take place</em> likey resulting in a
* failure state indicated by an {@link InvalidMixinException} at run
* time.</p>
*/
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 <em>false</em> 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 <em>false</em> will cause
* the annotation processor to skip this annotation when attempting to build
* the obfuscation table for the mixin.
*/
public boolean remap() default true;
}
@@ -30,14 +30,19 @@ import java.util.Set;
import org.objectweb.asm.tree.ClassNode;
/**
* <p>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.</p>
* <p>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.</p>
*
* <p>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.</p>
* <p>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.</p>
*/
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 <b>not</b> set. This allows the refmap file name to be supplied by the plugin
* programatically if desired. Returning <code>null</code> will revert to the default behaviour of using the default refmap json file.
* Called only if the "referenceMap" key in the config is <b>not</b> set.
* This allows the refmap file name to be supplied by the plugin
* programatically if desired. Returning <code>null</code> 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<String> myTargets, Set<String> 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<String> getMixins();
/**
* Called immediately <b>before</b> a mixin is applied to a target class, allows any pre-application transformations to be applied
* Called immediately <b>before</b> 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 <b>after</b> a mixin is applied to a target class, allows any post-application transformations to be applied
* Called immediately <b>after</b> 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
@@ -51,7 +51,8 @@ public interface IMixinInfo {
public abstract byte[] getClassBytes();
/**
* True if the superclass of the mixin is <b>not</b> the direct superclass of one or more targets
* True if the superclass of the mixin is <b>not</b> the direct superclass
* of one or more targets.
*/
public abstract boolean isDetachedSuper();
@@ -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 {
}
/**
* <p>Type of {@link InjectionPoint} to use. Can be a built-in class or the fully-qualified name of a custom class which extends
* <p>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}.</p>
*
* <p>Built-in types are {@link org.spongepowered.asm.mixin.injection.points.MethodHead HEAD},
* <p>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.</p>
* {@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.</p>
*/
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
* <i>after</i> 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
* <i>after</i> 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;
/**
* <p>The <b>named arguments</b> list is used to expand the scope of the annotation beyond the fixed values below in order to accommodate the
* <p>The <b>named arguments</b> 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 <b>must be specified as a fully-qualified member path</b> 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 <b>must be
* specified as a fully-qualified member path</b> 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 <em>ordinal</em> 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 <em>only</em> 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 <em>ordinal</em> 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 <em>only</em> 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 <em>false</em> 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 <em>false</em> will cause the annotation processor to skip
* this annotation when attempting to build the obfuscation table for the
* mixin.
*/
public boolean remap() default true;
}
@@ -30,42 +30,56 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* Specifies that this mixin method should inject a callback (or callback<b>s</b>) to itself in the target method(s) identified by {@link #method}.
* Specifies that this mixin method should inject a callback (or
* callback<b>s</b>) 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 <em>cancellable</em> 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 <em>cancellable</em> 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 <em>false</em> 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 <em>false</em> will cause the
* annotation processor to skip this annotation when attempting to build the
* obfuscation table for the mixin.
*/
public boolean remap() default true;
}
@@ -49,26 +49,37 @@ import com.google.common.base.Joiner;
import com.google.common.collect.ImmutableList;
/**
* <p>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.</p>
* <p>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.</p>
*
* <p>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.</p>
* <p>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.</p>
*
* <p>You are free to create your own injection point subclasses, but take note that it <b>is allowed</b> 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 <b>stateless</b>.</p>
* <p>You are free to create your own injection point subclasses, but take note
* that it <b>is allowed</b> 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
* <b>stateless</b>.</p>
*/
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 <b>add()</b> 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 <b>add()</b> method
* @return true if one or more injection points were found
*/
public abstract boolean find(String desc, InsnList insns, Collection<AbstractInsnNode> 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.<String>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<String> args, String target, int ordinal, int opcode) {
@@ -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} <em>must only
* </em> 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} <i>must only</i>
* 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();
/**
* <p>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.</p>
* <p>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.</p>
*
* <p>The index is zero-based.</p>
*/
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 <em>false</em> 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 <em>false</em> will cause the
* annotation processor to skip this annotation when attempting to build the
* obfuscation table for the mixin.
*/
public boolean remap() default true;
}
@@ -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} <em>must only
* </em> 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} <i>must only</i>
* 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 <em>false</em> 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 <em>false</em> will cause the
* annotation processor to skip this annotation when attempting to build the
* obfuscation table for the mixin.
*/
public boolean remap() default true;
}
@@ -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;
@@ -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 <R> Return type
*/
@@ -95,7 +96,8 @@ public class CallbackInfoReturnable<R> 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
*/
@@ -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
@@ -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;
}
@@ -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) {
@@ -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);
@@ -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
@@ -37,9 +37,11 @@ import org.spongepowered.asm.util.ASMHelper;
import com.google.common.collect.ObjectArrays;
/**
* <p>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 <b>but</b> 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:</p>
* <p>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 <b>but</b> 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:</p>
*
* <blockquote><pre>
* int abc = 0;
@@ -52,10 +54,13 @@ import com.google.common.collect.ObjectArrays;
*
* <p>The signature of the redirected method should be:</p>
*
* <blockquote><pre>public boolean barProxy(Foo someObject, int abc, int def)</pre></blockquote>
* <blockquote>
* <pre>public boolean barProxy(Foo someObject, int abc, int def)</pre>
* </blockquote>
*
* <p>For obvious reasons this does not apply for static methods, for static methods it is sufficient that the signature simply match the hooked
* method.</p>
* <p>For obvious reasons this does not apply for static methods, for static
* methods it is sufficient that the signature simply match the hooked method.
* </p>
*/
public class RedirectInjector extends InvokeInjector {
@@ -30,26 +30,37 @@ import org.objectweb.asm.tree.FieldInsnNode;
import org.spongepowered.asm.mixin.injection.struct.InjectionPointData;
/**
* <p>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}:</p>
* <p>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}:
* </p>
*
* <dl>
* <dt>target</dt>
* <dd>A {@link org.spongepowered.asm.mixin.injection.struct.MemberInfo MemberInfo} which identifies the target field</dd>
* <dd>A
* {@link org.spongepowered.asm.mixin.injection.struct.MemberInfo MemberInfo}
* which identifies the target field.</dd>
* <dt>opcode</dt>
* <dd>The {@link Opcodes opcode} of the field access, must be one of GETSTATIC, PUTSTATIC, GETFIELD or PUTFIELD.</dd>
* <dd>The {@link Opcodes opcode} of the field access, must be one of
* GETSTATIC, PUTSTATIC, GETFIELD or PUTFIELD.</dd>
* <dt>ordinal</dt>
* <dd>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 <em>ordinal</em> of <b>2</b> (ordinals are zero-indexed). The default value is <b>-1</b> which supresses ordinal matching</dd>
* <dd>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 <em>ordinal</em> of <b>2</b> (ordinals are zero-indexed). The
* default value is <b>-1</b> which supresses ordinal matching</dd>
* </dl>
*
* <p>Example:</p>
* <blockquote><pre>
* &#064;At(value = "FIELD", target="field_5678_z:I", opcode = Opcodes.GETFIELD)</pre>
* &#064;At(value = "FIELD", target="field_59_z:I", opcode = Opcodes.GETFIELD)
* </pre>
* </blockquote>
*
* <p>Note that like all standard injection points, this class matches the insn itself, putting the injection point immediately <em>before</em> the
* access in question. Use the {@link org.spongepowered.asm.mixin.injection.At#shift shift} specifier to adjust the matched opcode as necessary.</p>
* <p>Note that like all standard injection points, this class matches the insn
* itself, putting the injection point immediately <em>before</em> the access in
* question. Use {@link org.spongepowered.asm.mixin.injection.At#shift shift}
* specifier to adjust the matched opcode as necessary.</p>
*/
public class BeforeFieldAccess extends BeforeInvoke {
@@ -37,15 +37,21 @@ import org.spongepowered.asm.mixin.injection.struct.InjectionPointData;
import org.spongepowered.asm.mixin.injection.struct.MemberInfo;
/**
* <p>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}:</p>
* <p>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}:</p>
*
* <dl>
* <dt>target</dt>
* <dd>A {@link org.spongepowered.asm.mixin.injection.struct.MemberInfo MemberInfo} which identifies the target method</dd>
* <dd>A
* {@link org.spongepowered.asm.mixin.injection.struct.MemberInfo MemberInfo}
* which identifies the target method</dd>
* <dt>ordinal</dt>
* <dd>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 <em>ordinal</em> of <b>2</b> (ordinals are zero-indexed). The default value is <b>-1</b> which supresses ordinal matching</dd>
* <dd>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 <em>ordinal</em> of <b>2</b> (ordinals are zero-indexed). The
* default value is <b>-1</b> which supresses ordinal matching</dd>
* </dl>
*
* <p>Example:</p>
@@ -53,8 +59,10 @@ import org.spongepowered.asm.mixin.injection.struct.MemberInfo;
* &#064;At(value = "INVOKE", target="func_1234_a(III)V")</pre>
* </blockquote>
*
* <p>Note that like all standard injection points, this class matches the insn itself, putting the injection point immediately <em>before</em> the
* access in question. Use the {@link org.spongepowered.asm.mixin.injection.At#shift shift} specifier to adjust the matched opcode as necessary.</p>
* <p>Note that like all standard injection points, this class matches the insn
* itself, putting the injection point immediately <em>before</em> the access in
* question. Use {@link org.spongepowered.asm.mixin.injection.At#shift shift}
* specifier to adjust the matched opcode as necessary.</p>
*/
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 <em>all</em> 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<AbstractInsnNode> nodes) {
@@ -35,16 +35,20 @@ import org.spongepowered.asm.mixin.injection.InjectionPoint;
import org.spongepowered.asm.mixin.injection.struct.InjectionPointData;
/**
* <p>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}:</p>
* <p>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}:</p>
*
* <dl>
* <dt><em>named argument</em> class</dt>
* <dd>The value of the NEW node to look for, the fully-qualified class name</dd>
* <dd>The value of the NEW node to look for, the fully-qualified class name
* </dd>
* <dt>ordinal</dt>
* <dd>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 <em>ordinal</em> of <b>2</b> (ordinals are zero-indexed). The default value is <b>-1</b> which supresses ordinal
* matching</dd>
* <dd>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 <em>ordinal</em> of <b>2</b> (ordinals are zero-indexed).
* The default value is <b>-1</b> which supresses ordinal matching</dd>
* </dl>
*
* <p>Example:</p>
@@ -52,8 +56,10 @@ import org.spongepowered.asm.mixin.injection.struct.InjectionPointData;
* &#064;At(value = "NEW", args = { "class=java/lang/String" })</pre>
* </blockquote>
*
* <p>Note that like all standard injection points, this class matches the insn itself, putting the injection point immediately <em>before</em> the
* access in question. Use the {@link org.spongepowered.asm.mixin.injection.At#shift shift} specifier to adjust the matched opcode as necessary.</p>
* <p>Note that like all standard injection points, this class matches the insn
* itself, putting the injection point immediately <em>before</em> the access in
* question. Use {@link org.spongepowered.asm.mixin.injection.At#shift shift}
* specifier to adjust the matched opcode as necessary.</p>
*/
public class BeforeNew extends InjectionPoint {
@@ -36,23 +36,30 @@ import org.spongepowered.asm.mixin.injection.InjectionPoint;
import org.spongepowered.asm.mixin.injection.struct.InjectionPointData;
/**
* <p>This injection point searches for RETURN opcodes in the target method and returns a list of insns immediately prior to matching instructions.
* Note that <em>every</em> 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 <em>ordinal</em> parameter. The injection point accepts the following parameters from
* {@link org.spongepowered.asm.mixin.injection.At At}:<p>
* <p>This injection point searches for RETURN opcodes in the target method and
* returns a list of insns immediately prior to matching instructions. Note that
* <em>every</em> 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 <em>ordinal</em> parameter. The injection
* point accepts the following parameters from
* {@link org.spongepowered.asm.mixin.injection.At At}:</p>
*
* <dl>
* <dt>ordinal</dt>
* <dd>The ordinal position of the RETURN opcode to match, if not specified then the injection point returns <em>all</em> 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 <em>ordinal</em> of <b>2</b>
* (ordinals are zero-indexed). The default value is <b>-1</b> which supresses ordinal matching</dd>
* <dd>The ordinal position of the RETURN opcode to match, if not specified
* then the injection point returns <em>all</em> 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 <em>ordinal</em> of <b>2</b> (ordinals are
* zero-indexed). The default value is <b>-1</b> which supresses ordinal
* matching</dd>
* </dl>
*
* <p>Example:</p>
* <blockquote><pre>
* &#064;At(value = "RETURN")</pre>
* </blockquote>
* <p>Note that if <em>value</em> is the only parameter specified, it can be omitted:</p>
* <p>Note that if <em>value</em> is the only parameter specified, it can be
* omitted:</p>
* <blockquote><pre>
* &#064;At("RETURN")</pre>
* </blockquote>
@@ -33,36 +33,52 @@ import org.spongepowered.asm.mixin.injection.struct.InjectionPointData;
import org.spongepowered.asm.mixin.injection.struct.MemberInfo;
/**
* <p>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 <em>Profiler::startSection</em> 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.</p>
* <p>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
* <em>Profiler::startSection</em> 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.</p>
*
* <p>To be precise, this injection point matches invocations of the specified method which are preceded by an LDC instruction. The LDC instruction's
* <p>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 <b>ldc</b> named argument (see below)</p>
*
* <p>The following parameters from {@link org.spongepowered.asm.mixin.injection.At At} are accepted<p>
* <p>The following parameters from
* {@link org.spongepowered.asm.mixin.injection.At At} are accepted</p>
*
* <dl>
* <dt>target</dt>
* <dd>A {@link org.spongepowered.asm.mixin.injection.struct.MemberInfo MemberInfo} which identifies the target method, the method <b>must</b> be
* specified with a signature which accepts a single string and returns void, eg. <code>(Ljava/lang/String;)V</code></dd>
* <dd>A
* {@link org.spongepowered.asm.mixin.injection.struct.MemberInfo MemberInfo}
* which identifies the target method, the method <b>must</b> be specified
* with a signature which accepts a single string and returns void,
* eg. <code>(Ljava/lang/String;)V</code></dd>
* <dt>ordinal</dt>
* <dd>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 <em>ordinal</em> of <b>2</b> (ordinals are zero-indexed). The default value is <b>-1</b> which supresses ordinal matching</dd>
* <dd>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 <em>ordinal</em> of <b>2</b> (ordinals are zero-indexed). The
* default value is <b>-1</b> which supresses ordinal matching</dd>
* <dt><em>named argument</em> ldc</dt>
* <dd>The value of the LDC node to look for prior to the method invocation</dd>
* <dd>The value of the LDC node to look for prior to the method invocation
* </dd>
* </dl>
*
* <p>Example:</p>
* <blockquote><pre>
* &#064;At(value = "INVOKE_STRING", target="startSection(Ljava/lang/String;)V", args = { "ldc=root" })</pre>
* &#064;At(value = "INVOKE_STRING",
* target="startSection(Ljava/lang/String;)V", args = { "ldc=root" })</pre>
* </blockquote>
* <p>Notice the use of the <em>named argument</em> "ldc" which specifies the value of the target LDC node.</p>
* <p>Notice the use of the <em>named argument</em> "ldc" which specifies the
* value of the target LDC node.</p>
*
* <p>Note that like all standard injection points, this class matches the insn itself, putting the injection point immediately <em>before</em> the
* access in question. Use the {@link org.spongepowered.asm.mixin.injection.At#shift shift} specifier to adjust the matched opcode as necessary.</p>
* <p>Note that like all standard injection points, this class matches the insn
* itself, putting the injection point immediately <em>before</em> the access in
* question. Use {@link org.spongepowered.asm.mixin.injection.At#shift shift}
* specifier to adjust the matched opcode as necessary.</p>
*/
public class BeforeStringInvoke extends BeforeInvoke {
@@ -35,18 +35,25 @@ import org.spongepowered.asm.mixin.injection.InjectionPoint;
import org.spongepowered.asm.mixin.injection.struct.InjectionPointData;
/**
* <p>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}:</p>
* <p>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}:</p>
*
* <dl>
* <dt>opcode</dt>
* <dd>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 <b>-1</b> which matches any JUMP opcode.
* </dd>
* <dd>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 <b>-1</b> which matches any JUMP opcode.
* </dd>
* <dt>ordinal</dt>
* <dd>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 <em>ordinal</em> of <b>1</b> (ordinals are zero-indexed). The default value is <b>-1</b> which supresses ordinal matching</dd>
* <dd>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 <em>ordinal</em> of <b>1</b> (ordinals are zero-indexed).
* The default value is <b>-1</b> which supresses ordinal matching</dd>
* </dl>
*
* <p>Example:</p>
@@ -54,8 +61,10 @@ import org.spongepowered.asm.mixin.injection.struct.InjectionPointData;
* &#064;At(value = "JUMP", opcode = Opcodes.IFLE, ordinal = 2)</pre>
* </blockquote>
*
* <p>Note that like all standard injection points, this class matches the insn itself, putting the injection point immediately <em>before</em> the
* access in question. Use the {@link org.spongepowered.asm.mixin.injection.At#shift shift} specifier to adjust the matched opcode as necessary.</p>
* <p>Note that like all standard injection points, this class matches the insn
* itself, putting the injection point immediately <em>before</em> the access in
* question. Use {@link org.spongepowered.asm.mixin.injection.At#shift shift}
* specifier to adjust the matched opcode as necessary.</p>
*/
public class JumpInsnPoint extends InjectionPoint {
@@ -32,8 +32,10 @@ import org.spongepowered.asm.mixin.injection.InjectionPoint;
import org.spongepowered.asm.mixin.injection.struct.InjectionPointData;
/**
* <p>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.</p>
* <p>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.</p>
*
* <p>Example:</p>
* <blockquote><pre>
@@ -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<MethodNode> targets = new ArrayDeque<MethodNode>();
/**
* 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<InjectionPoint> injectionPoints = new ArrayList<InjectionPoint>();
@@ -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;
@@ -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 {
@@ -33,18 +33,23 @@ import org.spongepowered.asm.mixin.transformer.MixinData;
/**
* <p>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.</p>
* <p>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.</p>
*
* <p>Some examples:</p>
* <blockquote><pre>
* // 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))
@@ -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 {
@@ -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<String, ClassInfo> cache = new HashMap<String, ClassInfo>();
@@ -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('.', '/');
@@ -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.<String>getAnnotationValue(node, "prefix");
@@ -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) {
@@ -49,7 +49,8 @@ import com.google.gson.annotations.SerializedName;
class MixinConfig implements Comparable<MixinConfig> {
/**
* 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<MixinConfig> {
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<MixinConfig> {
private List<String> 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<String> mixinClassesServer;
@@ -187,13 +190,17 @@ class MixinConfig implements Comparable<MixinConfig> {
}
/**
* <p>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 <em>after</em> 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.</p>
* <p>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 <em>after</em> 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.</p>
*
* <p>For this reason we will invoke the initialisation on the first call to either the <em>hasMixinsFor()</em> or <em>getMixinsFor()</em>
* methods.</p>
* <p>For this reason we will invoke the initialisation on the first call to
* either the <em>hasMixinsFor()</em> or <em>getMixinsFor()</em> methods.
* </p>
*/
void initialise() {
if (this.initialised) {
@@ -250,7 +257,8 @@ class MixinConfig implements Comparable<MixinConfig> {
}
/**
* 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<MixinConfig> {
}
/**
* 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<MixinConfig> {
}
/**
* 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<MixinConfig> {
}
/**
* 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
@@ -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<String> interfaces = new HashSet<String>();
/**
* 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<String, Target> targetMethods = new HashMap<String, Target>();
@@ -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);
@@ -51,7 +51,8 @@ import com.google.common.collect.Lists;
class MixinInfo extends TreeInfo implements Comparable<MixinInfo>, 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<MixinInfo>, IMixinInfo {
private final List<String> targetClassNames;
/**
* True if the superclass of the mixin is <b>not</b> the direct superclass of one or more targets
* True if the superclass of the mixin is <b>not</b> the direct superclass
* of one or more targets
*/
private final boolean detachedSuper;
@@ -144,7 +146,8 @@ class MixinInfo extends TreeInfo implements Comparable<MixinInfo>, 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<MixinInfo>, IMixinInfo {
}
/**
* True if the superclass of the mixin is <b>not</b> the direct superclass of one or more targets
* True if the superclass of the mixin is <b>not</b> the direct superclass
* of one or more targets
*/
@Override
public boolean isDetachedSuper() {
@@ -30,9 +30,11 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* <p><b>For internal use only!</b> Contains small parts. Keep out of reach of children.</p>
* <p><b>For internal use only!</b> Contains small parts. Keep out of reach of
* children.</p>
*
* <p>Decoration annotation used by the {@link MixinTransformer} to mark methods in a class which have been added or overwritten by a mixin.</p>
* <p>Decoration annotation used by the {@link MixinTransformer} to mark methods
* in a class which have been added or overwritten by a mixin.</p>
*/
@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();
}
@@ -111,9 +111,12 @@ public class MixinTransformer extends TreeTransformer {
private static final String CLINIT = "<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<MixinConfig> configs = new ArrayList<MixinConfig>();
/**
* 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
@@ -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<IClassTransformer> transformers = Launch.classLoader.getTransformers();
@@ -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> 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> 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> 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
@@ -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<String, List<LocalVariableNode>> calculatedLocalVariables = new HashMap<String, List<LocalVariableNode>>();
/**
* 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 {
}
/**
* <p>Attempts to identify available locals at an arbitrary point in the bytecode specified by node.</p>
* <p>Attempts to identify available locals at an arbitrary point in the
* bytecode specified by node.</p>
*
* <p>This method builds an approximate view of the locals available at an arbitrary point in the bytecode by examining the following features in
* <p>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:</p>
* <ul>
* <li>Any available stack map frames</li>
@@ -83,22 +88,34 @@ public class Locals {
* <li>The local variable table</li>
* </ul>
*
* <p>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.</p>
* <p>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.</p>
*
* <p>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.</p>
* <p>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.</p>
*
* @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