/* * This file is part of Mixin, licensed under the MIT License (MIT). * * Copyright (c) SpongePowered * Copyright (c) contributors * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal * in the Software without restriction, including without limitation the rights * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell * copies of the Software, and to permit persons to whom the Software is * furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice shall be included in * all copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN * THE SOFTWARE. */ package org.spongepowered.asm.mixin.injection; import java.lang.annotation.ElementType; import java.lang.annotation.Repeatable; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; import org.spongepowered.asm.mixin.injection.selectors.dynamic.DynamicSelectorDesc; import org.spongepowered.asm.mixin.injection.struct.MemberInfo; /** *

A descriptor for matching a target element, for details of usage see * {@link DynamicSelectorDesc}.

* *

Unlike {@link MemberInfo Explicit Target Selectors} which can match any * element of a candidate member, @Desc descriptors always match * all elements of a target explicitly. Element defaults are as follows:

* *
*
{@link #owner}
*
Defaults to the current target of the mixin if not specified
*
{@link #ret}
*
Defaults to void
*
{@link #args}
*
Defaults to an empty array matching a target with no arguments, * omitting this value does not mean "match any" signature and * will explicitly match targets with no arguments. This value is ignored * for fields.
*
* *

Notes

* * */ @Target({ ElementType.TYPE, ElementType.METHOD }) @Retention(RetentionPolicy.RUNTIME) @Repeatable(Descriptors.class) public @interface Desc { /** * The identifier for this descriptor. Can be an implicit coordinate or a * user-defined string. IDs are not case-sensitive but must be unique within * a mixin or resolution scope. For more details on resolution for * descriptors see {@link DynamicSelectorDesc}. */ public String id() default ""; /** * The owner of the member to match. The "owner" is the class which declares * the member or, ocasionally the type of class upon which a virtual * call is being made. For example if a class SuperType defines a * method doSomething, usually owner will be * SuperType. However note that where a method retrieves a * reference to a derived type DerivedType which overrides * doSomething, it's possible the invocation will be made using * that type. To ensure usage of the correct type, inspect the disassembled * bytecode for your target. * *

When owner is not specified, it defaults to the current * target of the mixin.

*/ public Class owner() default void.class; /** * The name of the member to match. Must be specified. Matched * case-sensitively against targets. */ public String value(); /** * The return type of a method to match, or the declared type of a field. * Defaults to void. */ public Class ret() default void.class; /** * The argument types of a method to match, ignored for fields. Note that * failing to specify this value matches a target with no arguments. */ public Class[] args() default { }; /** * The next elements of this descriptor path, evaluated in order for each * recurse point. */ public Next[] next() default { }; /** * The minimum number of times this selector should match. By default the * selector is allowed to match no targets. When selecting fields or methods * setting this value to anything other than 0 or 1 is pointless since the * member can either be present or absent. However when matching method * calls or field accesses (eg. when using this value inside * {@link At#desc @At.desc}) this allows a minimum number of matches to * be specified in order to provide early validation that the selector * matched the correct number of candidates. To specify an exact number of * matches, set {@link #max max} to the same value as min. Values * less than zero are ignored since selectors cannot match a negative number * of times. */ public int min() default 0; /** * The maximum number of times this selector can match. By default the * selector is allowed to match an unlimited number of targets. When * selecting fields or methods, setting this value to anything other than 1 * is pointless since the member can either be present or absent. However * when matching method calls or field accesses (eg. when * using this value inside {@link At#desc @At.desc}) this allows a * maximum number of matches to be specified in order to limit the number of * times that the selector can match candidates. To specify an exact number * of matches, set max to the same value as {@link #min min}. * Values less than 1 are treated as Integer.MAX_VALUE (the * default) since setting a value of 0 or less has no meaning. */ public int max() default Integer.MAX_VALUE; }