Package org.spongepowered.asm.mixin.injection

Class 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 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 and or which allow strategies to be combined using intersection (and) or union (or) relationships to allow multiple strategies to be easily combined.

    Built-in Injection Points

    The following built-in Injection Points are available:

    • HEAD - Selects the first insn
    • RETURN - Selects RETURN insns
    • TAIL - Selects the last RETURN insn
    • INVOKE - Selects method invocations
    • INVOKE_ASSIGN - Selects STORE insns after method invocations which return a value
    • FIELD - Selects field access insns
    • NEW - Selects object constructions
    • INVOKE_STRING - Selects method invocations where a specific string is passed to the invocation.
    • JUMP - Selects branching (jump) instructions
    • CONSTANT - Selects constant values

    Additionally, the two special injection points are available which are only supported for use with @ModifyVariable:

    • LOAD - Selects xLOAD insns matching the ModifyVariable discriminators.
    • STORE - Selects xSTORE insns matching the ModifyVariable discriminators.

    See the javadoc for each type for more details on the scheme used by each injection point.

    Custom Injection Points

    You are free to create your own injection point subclasses. Once defined, they can be used by your mixins in one of two ways:

    1. Specify the fully-qualified name of the injection point class in the @At.value.
    2. Decorate your injection point class with @AtCode annotation which specifies a namespace and shortcode for the injection point, and register the class in your mixin config. You can then specify the namespaced code (eg. MYMOD:CUSTOMPOINT) in @At.value.

    When writing custom injection points, note that the general contract of injection points is that they be entirely - or at least behaviourally - stateless. It is allowed for a single InjectionPoint instance to be used by the mixin processor for multiple injections and thus implementing classes MUST NOT cache the insn list, event, or nodes instance passed to the find method, as each call to find must be considered a separate contract and the InjectionPoint's lifespan is not linked to the discovery lifespan. It is therefore important that the InjectionPoint implementation is fully stateless and that calls to find are idempotent.

    • 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

    • Method Detail

      • getSlice

        public java.lang.String getSlice()

      • 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

      • setTargetRestriction

        protected void setTargetRestriction​(InjectionPoint.RestrictTargetLevel targetRestriction)
        Set a new target restriction level for this injection point

      • 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,
                                   int flags)
        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
        flags - Additional flags
        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,
                                   int flags)
        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
        flags - Additional flags
        Returns:
        InjectionPoint parsed from the supplied data or null if parsing failed

      • getAtCode

        protected java.lang.String getAtCode()

      • register

        @Deprecated
public static void register​(java.lang.Class<? extends InjectionPoint> type)
        Deprecated.
        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

      • register

        public static void register​(java.lang.Class<? extends InjectionPoint> type,
                            java.lang.String namespace)
        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
        namespace - namespace for AtCode