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 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 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:

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

  • Constructor Details

  • Method Details

    • getSlice

      public String getSlice()

    • getSpecifier

      public InjectionPoint.Specifier getSpecifier(InjectionPoint.Specifier defaultSpecifier)

    • getId

      public String getId()

    • addMessage

      protected void addMessage(String format, 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(String desc, org.objectweb.asm.tree.InsnList insns, 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 String toString()
      Overrides:
      toString in class 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 List<InjectionPoint> parse(IMixinContext context, org.objectweb.asm.tree.MethodNode method, org.objectweb.asm.tree.AnnotationNode parent, 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 List<InjectionPoint> parse(IInjectionPointContext context, 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, String at, At.Shift shift, int by, List<String> args, String target, String slice, int ordinal, int opcode, 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, String at, At.Shift shift, int by, List<String> args, String target, String slice, int ordinal, int opcode, 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 String getAtCode()

    • register

      @Deprecated public static void register(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(Class<? extends InjectionPoint> type, 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