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` 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.

- - ### 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.Flags` | Boolean extensions for the At parser, mainly to avoid having to add many booleans in the future
    `static class` | `InjectionPoint.RestrictTargetLevel` | Target restriction level for different injection point types when used by restricted injectors (eg.
    `static class` | `InjectionPoint.Specifier` | Additional specifier for 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.Specifier specifier, java.lang.String id)` |
    `` | `InjectionPoint​(java.lang.String slice, InjectionPoint.Specifier specifier, java.lang.String id, IMessageSink messageSink)` |
    `` | `InjectionPoint​(java.lang.String slice, InjectionPoint.Specifier specifier, java.lang.String id, IMessageSink messageSink, InjectionPoint.RestrictTargetLevel targetRestriction)` |
    `protected` | `InjectionPoint​(InjectionPointData data)` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
    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()` |
    `java.lang.String` | `getId()` |
    `java.lang.String` | `getSlice()` |
    `InjectionPoint.Specifier` | `getSpecifier​(InjectionPoint.Specifier defaultSpecifier)` |
    `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, int flags)` | 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, int flags)` | 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)` | Deprecated.
    `static void` | `register​(java.lang.Class<? extends InjectionPoint> type, java.lang.String namespace)` | Register an injection point class.
    `protected void` | `setTargetRestriction​(InjectionPoint.RestrictTargetLevel targetRestriction)` | Set a new target restriction level for this injection point
    `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.Specifier specifier,
                                java.lang.String id)

    - #### InjectionPoint

          public InjectionPoint​(java.lang.String slice,
                                InjectionPoint.Specifier specifier,
                                java.lang.String id,
                                IMessageSink messageSink)

    - #### InjectionPoint

          public InjectionPoint​(java.lang.String slice,
                                InjectionPoint.Specifier specifier,
                                java.lang.String id,
                                IMessageSink messageSink,
                                InjectionPoint.RestrictTargetLevel targetRestriction)

  - ### Method Detail

    - #### getSlice

          public java.lang.String getSlice()

    - #### getSpecifier

          public InjectionPoint.Specifier getSpecifier​(InjectionPoint.Specifier defaultSpecifier)

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