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