org.spongepowered.asm.mixin.injection

Class InjectionPoint

java.lang.Object

org.spongepowered.asm.mixin.injection.InjectionPoint

Direct Known Subclasses:

BeforeConstant, BeforeFinalReturn, BeforeInvoke, BeforeLoadLocal, BeforeNew, BeforeReturn, JumpInsnPoint, MethodHead

public abstract class InjectionPoint
extends java.lang.Object

Base class for injection point discovery classes. Each subclass describes a strategy for locating code injection points within an instruction list, with the find(java.lang.String, org.objectweb.asm.tree.InsnList, java.util.Collection<org.objectweb.asm.tree.AbstractInsnNode>) method populating a collection with insn nodes from the supplied list which satisfy its strategy.

This base class also contains composite strategy factory methods such as and(org.spongepowered.asm.mixin.injection.InjectionPoint...) and or(org.spongepowered.asm.mixin.injection.InjectionPoint...) which allow strategies to be combined using intersection (and) or union (or) relationships to allow multiple strategies to be easily combined.

You are free to create your own injection point subclasses, but take note that it is allowed for a single InjectionPoint instance to be used for multiple injections and thus implementing classes MUST NOT cache the insn list, event, or nodes instance passed to the find(java.lang.String, org.objectweb.asm.tree.InsnList, java.util.Collection<org.objectweb.asm.tree.AbstractInsnNode>) method, as each call to find(java.lang.String, org.objectweb.asm.tree.InsnList, java.util.Collection<org.objectweb.asm.tree.AbstractInsnNode>) must be considered a separate functional contract and the InjectionPoint's lifespan is not linked to the discovery lifespan, therefore it is important that the InjectionPoint implementation is fully stateless.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	InjectionPoint.AtCode Injection point code for At annotations to use
static class	InjectionPoint.RestrictTargetLevel Target restriction level for different injection point types when used by restricted injectors (eg.
static class	InjectionPoint.Selector Selector type for slice delmiters, ignored for normal injection points.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_ALLOWED_SHIFT_BY Initial limit on the value of At.by() which triggers warning/error (based on environment)
static int	MAX_ALLOWED_SHIFT_BY Hard limit on the value of At.by() which triggers error

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	InjectionPoint()
protected	InjectionPoint(InjectionPointData data)
	InjectionPoint(java.lang.String slice, InjectionPoint.Selector selector, java.lang.String id)
	InjectionPoint(java.lang.String slice, InjectionPoint.Selector selector, java.lang.String id, IMessageSink messageSink)

Method Summary

Modifier and Type	Method and Description
protected void	addMessage(java.lang.String format, java.lang.Object... args) Notify method for subclasses to log when notable but non-fatal failures occur, for example allows subclasses to add notes when they return no results.
static InjectionPoint	after(InjectionPoint point) Returns an injection point which returns all insns immediately following insns from the supplied injection point
static InjectionPoint	and(InjectionPoint... operands) Returns a composite injection point which returns the intersection of nodes from all component injection points
static InjectionPoint	before(InjectionPoint point) Returns an injection point which returns all insns immediately prior to insns from the supplied injection point
boolean	checkPriority(int targetPriority, int mixinPriority) Runs a priority check in the context of this injection point.
abstract boolean	find(java.lang.String desc, org.objectweb.asm.tree.InsnList insns, java.util.Collection<org.objectweb.asm.tree.AbstractInsnNode> nodes) Find injection points in the supplied insn list
protected java.lang.String	getAtCode()
java.lang.String	getId()
InjectionPoint.Selector	getSelector()
java.lang.String	getSlice()
InjectionPoint.RestrictTargetLevel	getTargetRestriction(IInjectionPointContext context) Returns the target restriction level for this injection point.
protected static org.objectweb.asm.tree.AbstractInsnNode	nextNode(org.objectweb.asm.tree.InsnList insns, org.objectweb.asm.tree.AbstractInsnNode insn) Get the insn immediately following the specified insn, or return the same insn if the insn is the last insn in the list
static InjectionPoint	or(InjectionPoint... operands) Returns a composite injection point which returns the union of nodes from all component injection points
static InjectionPoint	parse(IInjectionPointContext context, org.objectweb.asm.tree.AnnotationNode at) Parse an InjectionPoint from the supplied At annotation supplied as an AnnotationNode instance
static InjectionPoint	parse(IInjectionPointContext context, At at) Parse an InjectionPoint from the supplied At annotation
static java.util.List<InjectionPoint>	parse(IInjectionPointContext context, java.util.List<org.objectweb.asm.tree.AnnotationNode> ats) Parse a collection of InjectionPoints from the supplied At annotations
static InjectionPoint	parse(IInjectionPointContext context, java.lang.String at, At.Shift shift, int by, java.util.List<java.lang.String> args, java.lang.String target, java.lang.String slice, int ordinal, int opcode, java.lang.String id) Parse and instantiate an InjectionPoint from the supplied information.
static InjectionPoint	parse(IMixinContext context, org.objectweb.asm.tree.MethodNode method, org.objectweb.asm.tree.AnnotationNode parent, org.objectweb.asm.tree.AnnotationNode at) Parse an InjectionPoint from the supplied At annotation supplied as an AnnotationNode instance
static InjectionPoint	parse(IMixinContext context, org.objectweb.asm.tree.MethodNode method, org.objectweb.asm.tree.AnnotationNode parent, At at) Parse an InjectionPoint from the supplied At annotation
static java.util.List<InjectionPoint>	parse(IMixinContext context, org.objectweb.asm.tree.MethodNode method, org.objectweb.asm.tree.AnnotationNode parent, java.util.List<org.objectweb.asm.tree.AnnotationNode> ats) Parse a collection of InjectionPoints from the supplied At annotations
static InjectionPoint	parse(IMixinContext context, org.objectweb.asm.tree.MethodNode method, org.objectweb.asm.tree.AnnotationNode parent, java.lang.String at, At.Shift shift, int by, java.util.List<java.lang.String> args, java.lang.String target, java.lang.String slice, int ordinal, int opcode, java.lang.String id) Parse and instantiate an InjectionPoint from the supplied information.
static void	register(java.lang.Class<? extends InjectionPoint> type) Register an injection point class.
static InjectionPoint	shift(InjectionPoint point, int count) Returns an injection point which returns all insns offset by the specified "count" from insns from the supplied injection point
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_ALLOWED_SHIFT_BY

public static final int DEFAULT_ALLOWED_SHIFT_BY

Initial limit on the value of At.by() which triggers warning/error (based on environment)

See Also:

Constant Field Values

MAX_ALLOWED_SHIFT_BY

public static final int MAX_ALLOWED_SHIFT_BY

Hard limit on the value of At.by() which triggers error

See Also:

Constant Field Values

Constructor Detail

InjectionPoint

protected InjectionPoint()

InjectionPoint

protected InjectionPoint(InjectionPointData data)

InjectionPoint

public InjectionPoint(java.lang.String slice,
                      InjectionPoint.Selector selector,
                      java.lang.String id)

InjectionPoint

public InjectionPoint(java.lang.String slice,
                      InjectionPoint.Selector selector,
                      java.lang.String id,
                      IMessageSink messageSink)

Method Detail

getSlice

public java.lang.String getSlice()

getSelector

public InjectionPoint.Selector getSelector()

getId

public java.lang.String getId()

addMessage

protected void addMessage(java.lang.String format,
                          java.lang.Object... args)

Notify method for subclasses to log when notable but non-fatal failures occur, for example allows subclasses to add notes when they return no results.

Parameters:

format - Message format

args - Format args

checkPriority

public boolean checkPriority(int targetPriority,
                             int mixinPriority)

Runs a priority check in the context of this injection point. A priority check should return true if the injection point is allowed to inject given the relative priorities of the target (a method merged by another mixin with targetPriority) and the incoming mixin with priority mixinPriority.

Parameters:

targetPriority - Priority of the mixin which originally merged the target method in question

mixinPriority - Priority of the mixin which owns the owning injector

Returns:

true if the priority check succeeds

getTargetRestriction

public InjectionPoint.RestrictTargetLevel getTargetRestriction(IInjectionPointContext context)

Returns the target restriction level for this injection point. This level defines whether an injection point is valid in its current state when being used by a restricted injector (currently CallbackInjector).

Parameters:

context - injection-specific context

Returns:

restriction level

find

public abstract boolean find(java.lang.String desc,
                             org.objectweb.asm.tree.InsnList insns,
                             java.util.Collection<org.objectweb.asm.tree.AbstractInsnNode> nodes)

Find injection points in the supplied insn list

Parameters:

desc - Method descriptor, supplied to allow return types and arguments etc. to be determined

insns - Insn list to search in, the strategy MUST ONLY add nodes from this list to the nodes collection

nodes - Collection of nodes to populate. Injectors should NOT make any assumptions about the state of this collection and should only call the add() method

Returns:

true if one or more injection points were found

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

nextNode

protected static org.objectweb.asm.tree.AbstractInsnNode nextNode(org.objectweb.asm.tree.InsnList insns,
                                                                  org.objectweb.asm.tree.AbstractInsnNode insn)

Get the insn immediately following the specified insn, or return the same insn if the insn is the last insn in the list

Parameters:

insns - Insn list to fetch from

insn - Insn node

Returns:

Next insn or the same insn if last in the list

and

public static InjectionPoint and(InjectionPoint... operands)

Returns a composite injection point which returns the intersection of nodes from all component injection points

Parameters:

operands - injection points to perform intersection

Returns:

adjusted InjectionPoint

or

public static InjectionPoint or(InjectionPoint... operands)

Returns a composite injection point which returns the union of nodes from all component injection points

Parameters:

operands - injection points to perform union

Returns:

adjusted InjectionPoint

after

public static InjectionPoint after(InjectionPoint point)

Returns an injection point which returns all insns immediately following insns from the supplied injection point

Parameters:

point - injection points to perform shift

Returns:

adjusted InjectionPoint

before

public static InjectionPoint before(InjectionPoint point)

Returns an injection point which returns all insns immediately prior to insns from the supplied injection point

Parameters:

point - injection points to perform shift

Returns:

adjusted InjectionPoint

shift

public static InjectionPoint shift(InjectionPoint point,
                                   int count)

Returns an injection point which returns all insns offset by the specified "count" from insns from the supplied injection point

Parameters:

point - injection points to perform shift

count - amount to shift by

Returns:

adjusted InjectionPoint

parse

public static java.util.List<InjectionPoint> parse(IMixinContext context,
                                                   org.objectweb.asm.tree.MethodNode method,
                                                   org.objectweb.asm.tree.AnnotationNode parent,
                                                   java.util.List<org.objectweb.asm.tree.AnnotationNode> ats)

Parse a collection of InjectionPoints from the supplied At annotations

Parameters:

context - Data for the mixin containing the annotation, used to obtain the refmap, amongst other things

method - The annotated handler method

parent - The parent annotation which owns this At annotation

ats - At annotations to parse information from

Returns:

InjectionPoint parsed from the supplied data or null if parsing failed

parse

public static java.util.List<InjectionPoint> parse(IInjectionPointContext context,
                                                   java.util.List<org.objectweb.asm.tree.AnnotationNode> ats)

Parse a collection of InjectionPoints from the supplied At annotations

Parameters:

context - Data for the mixin containing the annotation, used to obtain the refmap, amongst other things

ats - At annotations to parse information from

Returns:

InjectionPoint parsed from the supplied data or null if parsing failed

parse

public static InjectionPoint parse(IInjectionPointContext context,
                                   At at)

Parse an InjectionPoint from the supplied At annotation

Parameters:

context - Data for the mixin containing the annotation, used to obtain the refmap, amongst other things

at - At annotation to parse information from

Returns:

InjectionPoint parsed from the supplied data or null if parsing failed

parse

public static InjectionPoint parse(IMixinContext context,
                                   org.objectweb.asm.tree.MethodNode method,
                                   org.objectweb.asm.tree.AnnotationNode parent,
                                   At at)

Parse an InjectionPoint from the supplied At annotation

Parameters:

context - Data for the mixin containing the annotation, used to obtain the refmap, amongst other things

method - The annotated handler method

parent - The parent annotation which owns this At annotation

at - At annotation to parse information from

Returns:

InjectionPoint parsed from the supplied data or null if parsing failed

parse

public static InjectionPoint parse(IMixinContext context,
                                   org.objectweb.asm.tree.MethodNode method,
                                   org.objectweb.asm.tree.AnnotationNode parent,
                                   org.objectweb.asm.tree.AnnotationNode at)

Parse an InjectionPoint from the supplied At annotation supplied as an AnnotationNode instance

Parameters:

context - Data for the mixin containing the annotation, used to obtain the refmap, amongst other things

method - The annotated handler method

parent - The parent annotation which owns this At annotation

at - At annotation to parse information from

Returns:

InjectionPoint parsed from the supplied data or null if parsing failed

parse

public static InjectionPoint parse(IInjectionPointContext context,
                                   org.objectweb.asm.tree.AnnotationNode at)

Parse an InjectionPoint from the supplied At annotation supplied as an AnnotationNode instance

Parameters:

context - Data for the mixin containing the annotation, used to obtain the refmap, amongst other things

at - At annotation to parse information from

Returns:

InjectionPoint parsed from the supplied data or null if parsing failed

parse

public static InjectionPoint parse(IMixinContext context,
                                   org.objectweb.asm.tree.MethodNode method,
                                   org.objectweb.asm.tree.AnnotationNode parent,
                                   java.lang.String at,
                                   At.Shift shift,
                                   int by,
                                   java.util.List<java.lang.String> args,
                                   java.lang.String target,
                                   java.lang.String slice,
                                   int ordinal,
                                   int opcode,
                                   java.lang.String id)

Parse and instantiate an InjectionPoint from the supplied information. Returns null if an InjectionPoint could not be created.

Parameters:

context - Data for the mixin containing the annotation, used to obtain the refmap, amongst other things

method - The annotated handler method

parent - The parent annotation which owns this At annotation

at - Injection point specifier

shift - Shift type to apply

by - Amount of shift to apply for the BY shift type

args - Named parameters

target - Target for supported injection points

slice - Slice id for injectors which support multiple slices

ordinal - Ordinal offset for supported injection points

opcode - Bytecode opcode for supported injection points

id - Injection point id from annotation

Returns:

InjectionPoint parsed from the supplied data or null if parsing failed

parse

public static InjectionPoint parse(IInjectionPointContext context,
                                   java.lang.String at,
                                   At.Shift shift,
                                   int by,
                                   java.util.List<java.lang.String> args,
                                   java.lang.String target,
                                   java.lang.String slice,
                                   int ordinal,
                                   int opcode,
                                   java.lang.String id)

Parse and instantiate an InjectionPoint from the supplied information. Returns null if an InjectionPoint could not be created.

Parameters:

context - The injection point context which owns this At annotation

at - Injection point specifier

shift - Shift type to apply

by - Amount of shift to apply for the BY shift type

args - Named parameters

target - Target for supported injection points

slice - Slice id for injectors which support multiple slices

ordinal - Ordinal offset for supported injection points

opcode - Bytecode opcode for supported injection points

id - Injection point id from annotation

Returns:

InjectionPoint parsed from the supplied data or null if parsing failed

getAtCode

protected java.lang.String getAtCode()

register

public static void register(java.lang.Class<? extends InjectionPoint> type)

Register an injection point class. The supplied class must be decorated with an InjectionPoint.AtCode annotation for registration purposes.

Parameters:

type - injection point type to register