Package 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 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 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 Description
    protected InjectionPoint()  
      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)  
    protected InjectionPoint​(InjectionPointData data)  

  • Method Summary

    Modifier and Type Method 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()  
    InjectionPoint.RestrictTargetLevel getCancellationRestriction​(IInjectionPointContext context)
    Returns the target restriction level for this injection point's cancellation for @Inject annotations.
    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, 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 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, 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 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 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, 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 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 Details

    • 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 Details

    • 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 Details

    • 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

    • getCancellationRestriction

      public InjectionPoint.RestrictTargetLevel getCancellationRestriction​(IInjectionPointContext context)
      Returns the target restriction level for this injection point's cancellation for @Inject annotations. This level defines whether an injection point can declare cancellable = true.
      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