Add all missing class javadoc

This commit is contained in:
Mumfrey committed 2016-02-05 13:06:00 +00:00
1 parent 83a9f4fb02
commit 9cd453cd63
42 files changed
+413 -11

No files matched your search

@@ -24,6 +24,9 @@
*/
package org.spongepowered.asm.launch;
/**
* Error raised when mixin subsystem initialisation fails
*/
public class MixinInitialisationError extends Error {
private static final long serialVersionUID = 1L;
@@ -545,6 +545,9 @@ public class MixinEnvironment implements ITokenProvider {
}
/**
* Temporary
*/
static class MixinLogger {
static MixinAppender appender = new MixinAppender("MixinLogger", null, null);
@@ -555,11 +558,13 @@ public class MixinEnvironment implements ITokenProvider {
log.addAppender(appender);
}
/**
* Temporary
*/
static class MixinAppender extends AbstractAppender {
protected MixinAppender(String name, Filter filter, Layout<? extends Serializable> layout) {
super(name, filter, layout);
// TODO Auto-generated constructor stub
}
@Override
@@ -24,6 +24,9 @@
*/
package org.spongepowered.asm.mixin;
/**
* Base class for all mixin processor exceptions
*/
public class MixinException extends RuntimeException {
private static final long serialVersionUID = 1L;
@@ -29,6 +29,10 @@ import java.util.List;
import org.spongepowered.asm.mixin.extensibility.IRemapper;
/**
* Mixin environment remapper chain. Contains all remappers for the current
* environment to facilitate remapping via all registered remappers.
*/
public class RemapperChain implements IRemapper {
private final List<IRemapper> remappers = new ArrayList<IRemapper>();
@@ -29,6 +29,9 @@ import java.util.List;
import org.spongepowered.asm.lib.tree.ClassNode;
import org.spongepowered.asm.mixin.MixinEnvironment.Phase;
/**
* Interface for MixinInfo, used in extensibility API
*/
public interface IMixinInfo {
/**
@@ -29,52 +29,119 @@ import java.util.HashMap;
import java.util.Map;
import org.spongepowered.asm.lib.tree.AbstractInsnNode;
import org.spongepowered.asm.mixin.injection.struct.Target;
import org.spongepowered.asm.util.ASMHelper;
/**
* Used to keep track of instruction nodes in a {@link Target} method which are
* targetted by various types of injector. This collection is populated during
* the first injector pass and allows injectors to keep track of their targets
* even when the target method is being manipulated by other injectors.
*/
public class InjectionNodes extends ArrayList<InjectionNodes.InjectionNode> {
/**
* Never gonna give you up
*/
private static final long serialVersionUID = 1L;
/**
* A node targetted by one or more injectors. Using this wrapper allows
* injectors to be aware of when their target node is removed or replace by
* another injector. It also allows injectors to decorate certain nodes with
* custom metadata to allow arbitration between injectors to take place.
*/
public static class InjectionNode implements Comparable<InjectionNode> {
/**
* The original node targetted
*/
private final AbstractInsnNode originalTarget;
/**
* Initially set to the {@link #originalTarget}, if an injector removes
* or replaces this node then points to the current target. Can be null
* if the node is removed.
*/
private AbstractInsnNode currentTarget;
/**
* Injector decorations on this node
*/
private Map<Object, Object> decorations;
public InjectionNode(AbstractInsnNode target) {
this.currentTarget = this.originalTarget = target;
/**
* Create a new node wrapper for the specified target node
*
* @param node target node
*/
public InjectionNode(AbstractInsnNode node) {
this.currentTarget = this.originalTarget = node;
}
/**
* Get the original target of this node
*/
public AbstractInsnNode getOriginalTarget() {
return this.originalTarget;
}
/**
* Get the current target of this node, can be null if the node was
* replaced
*/
public AbstractInsnNode getCurrentTarget() {
return this.currentTarget;
}
public void replace(AbstractInsnNode currentTarget) {
this.currentTarget = currentTarget;
/**
* Replace this node with the specified target
*
* @param target new node
*/
public void replace(AbstractInsnNode target) {
this.currentTarget = target;
}
/**
* Remove the node
*/
public void remove() {
this.currentTarget = null;
}
/**
* Checks whether the original or current target of this node match the
* specified node
*
* @param node node to check
* @return true if the supplied node matches either of this node's
* internal identities
*/
public boolean matches(AbstractInsnNode node) {
return this.originalTarget == node || this.currentTarget == node;
}
/**
* Get whether this node has been replaced
*/
public boolean isReplaced() {
return this.originalTarget != this.currentTarget;
}
/**
* Get whether this node has been removed
*/
public boolean isRemoved() {
return this.currentTarget == null;
}
/**
* Decorate this node with arbitrary metadata for injector arbitration
*
* @param key meta key
* @param value meta value
*/
public <K, V> void decorate(K key, V value) {
if (this.decorations == null) {
this.decorations = new HashMap<Object, Object>();
@@ -82,20 +149,38 @@ public class InjectionNodes extends ArrayList<InjectionNodes.InjectionNode> {
this.decorations.put(key, value);
}
/**
* Get whether this node is decorated with the specified key
*
* @param key meta key
* @return true if the specified decoration exists
*/
public <K> boolean hasDecoration(K key) {
return this.decorations != null && this.decorations.get(key) != null;
}
/**
* Get the specified decoration
*
* @param key meta key
* @return decoration value or null if absent
*/
@SuppressWarnings("unchecked")
public <K, V> V getDecoration(K key) {
return (V) (this.decorations == null ? null : this.decorations.get(key));
}
/* (non-Javadoc)
* @see java.lang.Comparable#compareTo(java.lang.Object)
*/
@Override
public int compareTo(InjectionNode other) {
return other == null ? Integer.MAX_VALUE : this.hashCode() - other.hashCode();
}
/* (non-Javadoc)
* @see java.lang.Object#toString()
*/
@Override
public String toString() {
return String.format("InjectionNode[%s]", ASMHelper.getNodeDescriptionForDebug(this.currentTarget));
@@ -103,6 +188,12 @@ public class InjectionNodes extends ArrayList<InjectionNodes.InjectionNode> {
}
/**
* Add a tracked node to this collection if it does not already exist
*
* @param node Instruction node to add
* @return wrapper for the specified node
*/
public InjectionNode add(AbstractInsnNode node) {
InjectionNode injectionNode = this.get(node);
if (injectionNode == null) {
@@ -112,6 +203,13 @@ public class InjectionNodes extends ArrayList<InjectionNodes.InjectionNode> {
return injectionNode;
}
/**
* Get a tracked node from this collection if it already exists, returns
* null if the node is not tracked
*
* @param node instruction node
* @return wrapper node or null if not tracked
*/
public InjectionNode get(AbstractInsnNode node) {
for (InjectionNode injectionNode : this) {
if (injectionNode.matches(node)) {
@@ -121,10 +219,23 @@ public class InjectionNodes extends ArrayList<InjectionNodes.InjectionNode> {
return null;
}
/**
* Get whether this collection contains a mapping for the specified insn
*
* @param node instruction node to check
* @return true if a wrapper exists for the node
*/
public boolean contains(AbstractInsnNode node) {
return this.get(node) != null;
}
/**
* Replace the specified node with the new node, does not update the wrapper
* if no wrapper exists for <tt>oldNode</tt>
*
* @param oldNode node being replaced
* @param newNode node to replace with
*/
public void replace(AbstractInsnNode oldNode, AbstractInsnNode newNode) {
InjectionNode injectionNode = this.get(oldNode);
if (injectionNode != null) {
@@ -132,8 +243,14 @@ public class InjectionNodes extends ArrayList<InjectionNodes.InjectionNode> {
}
}
public void remove(AbstractInsnNode oldNode) {
InjectionNode injectionNode = this.get(oldNode);
/**
* Mark the specified node as removed, does not update the wrapper if no
* wrapper exists
*
* @param node node being removed
*/
public void remove(AbstractInsnNode node) {
InjectionNode injectionNode = this.get(node);
if (injectionNode != null) {
injectionNode.remove();
}
@@ -24,6 +24,7 @@
*/
package org.spongepowered.asm.mixin.injection;
import java.lang.reflect.Array;
import java.lang.reflect.Constructor;
import java.util.ArrayList;
import java.util.Arrays;
@@ -148,12 +149,12 @@ public abstract class InjectionPoint {
super(points);
}
@SuppressWarnings("unchecked")
@Override
public boolean find(String desc, InsnList insns, Collection<AbstractInsnNode> nodes) {
boolean found = false;
@SuppressWarnings("unchecked")
ArrayList<AbstractInsnNode>[] allNodes = new ArrayList[this.components.length];
ArrayList<AbstractInsnNode>[] allNodes = (ArrayList<AbstractInsnNode>[]) Array.newInstance(ArrayList.class, this.components.length);
for (int i = 0; i < this.components.length; i++) {
allNodes[i] = new ArrayList<AbstractInsnNode>();
@@ -24,6 +24,9 @@
*/
package org.spongepowered.asm.mixin.injection;
/**
* Thrown when an injector group fails an injection check
*/
public class InjectionValidationException extends Exception {
private static final long serialVersionUID = 1L;
@@ -28,6 +28,10 @@ import org.spongepowered.asm.mixin.injection.struct.InjectionInfo;
import org.spongepowered.asm.mixin.transformer.InvalidMixinException;
import org.spongepowered.asm.mixin.transformer.MixinTargetContext;
/**
* Thrown when an injector fails a state check, for example if an injector
* handler signature is invalid, an invalid opcode is targetted, etc.
*/
public class InvalidInjectionException extends InvalidMixinException {
private static final long serialVersionUID = 1L;
@@ -24,6 +24,10 @@
*/
package org.spongepowered.asm.mixin.injection.callback;
/**
* Exception thrown when a consumer attemtps to call <tt>cancel()</tt> on a
* callback not marked as <tt>cancellable</tt>.
*/
public class CancellationException extends RuntimeException {
private static final long serialVersionUID = 1L;
@@ -26,6 +26,10 @@ package org.spongepowered.asm.mixin.injection.modify;
import org.spongepowered.asm.mixin.MixinException;
/**
* Thrown when an <em>implicit</em> discriminator (no args) fails to identify
* a unique candidate.
*/
public class InvalidImplicitDiscriminatorException extends MixinException {
private static final long serialVersionUID = 1L;
@@ -26,12 +26,16 @@ package org.spongepowered.asm.mixin.injection.struct;
import org.spongepowered.asm.lib.tree.AnnotationNode;
import org.spongepowered.asm.lib.tree.MethodNode;
import org.spongepowered.asm.mixin.injection.Inject;
import org.spongepowered.asm.mixin.injection.callback.CallbackInjector;
import org.spongepowered.asm.mixin.injection.callback.LocalCapture;
import org.spongepowered.asm.mixin.injection.code.Injector;
import org.spongepowered.asm.mixin.transformer.MixinTargetContext;
import org.spongepowered.asm.util.ASMHelper;
/**
* Information about a callback to inject, usually specified by {@link Inject}
*/
public class CallbackInjectionInfo extends InjectionInfo {
protected CallbackInjectionInfo(MixinTargetContext mixin, MethodNode method, AnnotationNode annotation) {
@@ -26,6 +26,9 @@ package org.spongepowered.asm.mixin.injection.struct;
import org.spongepowered.asm.mixin.MixinException;
/**
* Thrown when a {@link MemberInfo} fails basic syntax validation
*/
public class InvalidMemberDescriptorException extends MixinException {
private static final long serialVersionUID = 1L;
@@ -26,11 +26,15 @@ package org.spongepowered.asm.mixin.injection.struct;
import org.spongepowered.asm.lib.tree.AnnotationNode;
import org.spongepowered.asm.lib.tree.MethodNode;
import org.spongepowered.asm.mixin.injection.ModifyArg;
import org.spongepowered.asm.mixin.injection.code.Injector;
import org.spongepowered.asm.mixin.injection.invoke.ModifyArgInjector;
import org.spongepowered.asm.mixin.transformer.MixinTargetContext;
import org.spongepowered.asm.util.ASMHelper;
/**
* Information about a {@link ModifyArg} injector
*/
public class ModifyArgInjectionInfo extends InjectionInfo {
public ModifyArgInjectionInfo(MixinTargetContext mixin, MethodNode method, AnnotationNode annotation) {
@@ -26,12 +26,16 @@ package org.spongepowered.asm.mixin.injection.struct;
import org.spongepowered.asm.lib.tree.AnnotationNode;
import org.spongepowered.asm.lib.tree.MethodNode;
import org.spongepowered.asm.mixin.injection.ModifyVariable;
import org.spongepowered.asm.mixin.injection.code.Injector;
import org.spongepowered.asm.mixin.injection.modify.LocalVariableDiscriminator;
import org.spongepowered.asm.mixin.injection.modify.ModifyVariableInjector;
import org.spongepowered.asm.mixin.transformer.MixinTargetContext;
import org.spongepowered.asm.util.ASMHelper;
/**
* Information about a {@link ModifyVariable} injector
*/
public class ModifyVariableInjectionInfo extends InjectionInfo {
public ModifyVariableInjectionInfo(MixinTargetContext mixin, MethodNode method, AnnotationNode annotation) {
@@ -30,6 +30,9 @@ import org.spongepowered.asm.mixin.injection.code.Injector;
import org.spongepowered.asm.mixin.injection.invoke.RedirectInjector;
import org.spongepowered.asm.mixin.transformer.MixinTargetContext;
/**
* Information about a redirector injector
*/
public class RedirectInjectionInfo extends InjectionInfo {
public RedirectInjectionInfo(MixinTargetContext mixin, MethodNode method, AnnotationNode annotation) {
@@ -37,42 +37,107 @@ import com.google.gson.GsonBuilder;
import net.minecraft.launchwrapper.Launch;
/**
* Stores runtime information allowing field, method and type references which
* cannot be hard remapped by the reobfuscation process to be remapped in a
* "soft" manner at runtime. Refmaps are generated by the <em>Annotation
* Processor</em> at compile time and must be bundled with an obfuscated binary
* to allow obfuscated references in injectors and other String-defined targets
* to be remapped to the target obfsucation environment as appropriate. If the
* refmap is absent the environment is assumed to be deobfuscated (eg. dev-time)
* and injections and other transformations will fail if this is not the case.
*/
public final class ReferenceMapper implements Serializable {
private static final long serialVersionUID = 2L;
/**
* Resource to attempt to load if no source is specified explicitly
*/
public static final String DEFAULT_RESOURCE = "mixin.refmap.json";
/**
* Passthrough mapper, used as failover
*/
public static final ReferenceMapper DEFAULT_MAPPER = new ReferenceMapper(true);
/**
* "Default" mappings. The set of mappings to use as "default" is specified
* by the AP. Each entry is keyed by the owning mixin, with the value map
* containing the actual remappings for each owner
*/
private final Map<String, Map<String, String>> mappings = Maps.newHashMap();
/**
* All mapping sets, keyed by environment type, eg. "notch", "searge". The
* format of each map within this map is the same as for {@link #mappings}
*/
private final Map<String, Map<String, Map<String, String>>> data = Maps.newHashMap();
/**
* True if this refmap cannot be written. Only true for the
* {@link #DEFAULT_MAPPER}
*/
private final transient boolean readOnly;
/**
* Current remapping context, used as the key into {@link data}
*/
private transient String context = null;
/**
* Create an empty refmap
*/
public ReferenceMapper() {
this(false);
}
/**
* Create a readonly refmap, only used by {@link #DEFAULT_MAPPER}
*
* @param readOnly flag to indicate read-only
*/
private ReferenceMapper(boolean readOnly) {
this.readOnly = readOnly;
}
/**
* Get the current context
*
* @return current context key, can be null
*/
public String getContext() {
return this.context;
}
/**
* Set the current remap context, can be null
*
* @param context remap context
*/
public void setContext(String context) {
this.context = context;
}
/**
* Remap a reference for the specified owning class in the current context
*
* @param className Owner class
* @param reference Reference to remap
* @return remapped reference, returns original reference if not remapped
*/
public String remap(String className, String reference) {
return this.remapWithContext(this.context, className, reference);
}
/**
* Remap a reference for the specified owning class in the specified context
*
* @param context Remap context to use
* @param className Owner class
* @param reference Reference to remap
* @return remapped reference, returns original reference if not remapped
*/
public String remapWithContext(String context, String className, String reference) {
Map<String, Map<String, String>> mappings = this.mappings;
if (context != null) {
@@ -84,6 +149,9 @@ public final class ReferenceMapper implements Serializable {
return this.remap(mappings, className, reference);
}
/**
* Remap the things
*/
private String remap(Map<String, Map<String, String>> mappings, String className, String reference) {
if (className == null) {
for (Map<String, String> mapping : mappings.values()) {
@@ -101,8 +169,16 @@ public final class ReferenceMapper implements Serializable {
return remappedReference != null ? remappedReference : reference;
}
/**
* Add a mapping to this refmap
*
* @param context Obfuscation context, can be null
* @param className Class which owns this mapping, cannot be null
* @param reference Reference to remap, cannot be null
* @param newReference Remapped value, cannot be null
*/
public void addMapping(String context, String className, String reference, String newReference) {
if (this.readOnly) {
if (this.readOnly || reference == null || newReference == null || reference.equals(newReference)) {
return;
}
Map<String, Map<String, String>> mappings = this.mappings;
@@ -121,10 +197,21 @@ public final class ReferenceMapper implements Serializable {
classMappings.put(reference, newReference);
}
/**
* Write this refmap out to the specified writer
*
* @param writer Writer to write to
*/
public void write(Appendable writer) {
new GsonBuilder().setPrettyPrinting().create().toJson(this, writer);
}
/**
* Read a new refmap from the specified resource
*
* @param resource Resource to read from
* @return new refmap or {@link #DEFAULT_MAPPER} if reading fails
*/
public static ReferenceMapper read(String resource) {
Reader reader = null;
try {
@@ -143,7 +230,18 @@ public final class ReferenceMapper implements Serializable {
}
}
/**
* Read a new refmap instance from the specified reader
*
* @param reader Reader to read from
* @return new refmap
*/
public static ReferenceMapper read(Reader reader) {
return new Gson().fromJson(reader, ReferenceMapper.class);
try {
return new Gson().fromJson(reader, ReferenceMapper.class);
} catch (Exception ex) {
return ReferenceMapper.DEFAULT_MAPPER;
}
}
}
@@ -156,6 +156,9 @@ public class ClassInfo extends TreeInfo {
*/
abstract static class Member {
/**
* Member type
*/
static enum Type {
METHOD,
FIELD
@@ -26,6 +26,9 @@ package org.spongepowered.asm.mixin.transformer;
import org.spongepowered.asm.mixin.MixinException;
/**
* Thrown by the mixin validator when a mixin fails a pre-flight check
*/
public class InvalidMixinException extends MixinException {
private static final long serialVersionUID = 1L;
@@ -34,6 +34,9 @@ import org.spongepowered.asm.mixin.MixinException;
*/
public class MixinTransformerModuleCheckClass implements IMixinTransformerModule {
/**
* Exception thrown when checkclass fails
*/
public static class ValidationFailedException extends MixinException {
private static final long serialVersionUID = 1L;
@@ -26,6 +26,9 @@ package org.spongepowered.asm.obfuscation;
import com.google.common.base.Objects;
/**
* Stores information about an SRG field mapping during AP runs
*/
public final class SrgField {
private final String mapping;
@@ -26,6 +26,9 @@ package org.spongepowered.asm.obfuscation;
import com.google.common.base.Objects;
/**
* Stores information about an SRG method mapping during AP runs
*/
public final class SrgMethod {
private final String name;
@@ -41,6 +41,9 @@ import org.spongepowered.asm.lib.Type;
import org.spongepowered.asm.lib.tree.*;
import org.spongepowered.asm.lib.util.CheckClassAdapter;
/**
* Utility methods for working with ASM
*/
public class ASMHelper {
private static final int[] intConstants = new int[]
@@ -26,6 +26,10 @@ package org.spongepowered.asm.util;
import org.spongepowered.asm.mixin.MixinException;
/**
* Exception thrown when something goes horribly wrong whilst <s>summoning the
* antichrist</s> generating the LVT for a target method.
*/
public class LVTGeneratorException extends MixinException {
private static final long serialVersionUID = 1L;
@@ -24,8 +24,14 @@
*/
package org.spongepowered.asm.util;
/**
* Utility methods for obfuscation tasks
*/
public abstract class ObfuscationUtil {
/**
* Interface for remapper proxies
*/
public interface IClassRemapper {
/**
@@ -40,8 +40,16 @@ import com.google.common.base.Strings;
*/
public class PrettyPrinter {
/**
* Interface for object which supports printing to pretty printer
*/
public interface IPrettyPrintable {
/**
* Append this objec to specified pretty printer
*
* @param printer printer to append to
*/
public abstract void print(PrettyPrinter printer);
}