Filtros de eventos
Ahora que ha dedicado un poco de tiempo trabajando con eventos, probablemente se haya dado cuenta de que existen varias precondiciones que suele comprobar al escribir un detector de eventos. Los filtros de eventos son un grupo de anotaciones que lo asisten al permitirle validar automáticamente aspectos del evento, y si la validación falla, entonces no se llamará a su oyente. Esto le permite a su oyente estar dedicado a la lógica de su controlador, en lugar de las precondiciones, resultando en un código más limpio.
Los filtros de eventos vienen en dos variedades, filtros de tipo de evento y filtros de parámetros.
Los filtros de tipo de evento son anotaciones de método que se aplican al método de su oyente junto con la anotación: javadoc: Listener y proporcionan varios filtros según el tipo o el estado del evento.
Los filtros de parámetros validan los objetos contenidos dentro del evento como por ejemplo la causa. Vienen en otras dos variadades, fuentes de parámetros y filtros de parámetros. Cada parámetro adicional debe tener una anotación de fuente, y opcionalmente puede incluir cualquier cantidad de anotaciones de filtro.
Filtros de tipo de evento
@Include/@Exclude Estos dos parámetros se utilizan en conjunto con la escucha de eventos de supertipo, como por ejemplo :javadoc: AffectEntityEvent al tiempo que se reducen los eventos que recibe a solo un subconjunto de los eventos que amplían el evento que usted está escuchando.
Por ejemplo:
@Listener
@Exclude(InteractBlockEvent.Primary.class)
public void onInteract(InteractBlockEvent event) {
// do something
}
This listener would normally be called for all events extending InteractBlockEvent. However, the Exclude annotationte will prevent your listener from being called for the InteractBlockEvent.Primary event (leaving just the InteractBlockEvent.Secondary extended events).
Un ejemplo con :javadoc: Include podría ser:
@Listener
@Include({DamageEntityEvent.class, DestructEntityEvent.class})
public void onEvent(TargetEntityEvent event) {
// do something
}
Este oyente normalmente se llamaría para todos los EntityEvents, sin embargo, la anotación `` Include`` lo limita a solo recibir :javadoc: DamageEntityEvent y :javadoc:` DestructEntityEvent` s.
@IsCancelled This annotation allows filtering events by their cancellation state at the time that your event listener would normally be called. By default, your event listener will not be called if the event has been cancelled by a previous event listener. However you can change this behavior to one of three states depending on the Tristate value in the IsCancelled annotation.
`` Tristate.FALSE`` es el comportamiento predeterminado si la anotación `` IsCancelled`` no está presente, y no llamará a su oyente si el evento ha sido cancelado.
Tristate.UNDEFINEDcausará que su oyente sea llamado independientemente del estado de cancelación del evento.`` Tristate.TRUE`` hará que se llame a su oyente solo si el evento ha sido cancelado por un oyente de eventos anterior.
Filtros de Parámetros
Los filtros de parámetros le permitirán filtrar en función de los objetos dentro del evento. Estas anotaciones vienen en dos tipos, fuentes y filtros. Cada parámetro adicional para su método de su oyente, más allá del parámetro de evento normal, requiere exactamente una anotación de fuente y opcionalmente puede tener cualquier número de anotaciones de filtro.
Anotaciones de Fuentes de Parámetros
Las anotaciones de fuente de parámetros indican al sistema de eventos dónde debería buscar el valor de este parámetro. Esto puede estar en la causa de los eventos o en un miembro del objeto del mismo evento.
@ First Esta anotación de fuente de parámetro le dice al sistema de eventos que busque el primer objeto en la causa del evento que coincida con el tipo de su parámetro (Esto es equivalente a :javadoc: Cause # first (Class)). Si no se encuentra ningún objeto que coincida con este parámetro, entonces no se llama a su oyente.
En este ejemplo, solo se llamará a tu oyente si hay un jugador en la causa del evento, y el parámetro del `` player`` se establecerá para que el primer jugador presente la causa.
@Listener
public void onInteract(InteractBlockEvent.Secondary event, @First Player player) {
// do something
}
@Last Esto es similar a @ First; sin embargo, hace una llamada a :javadoc: Cause # last (Class).
@Listener
public void onInteract(InteractBlockEvent.Secondary event, @Last Player player) {
// do something
}
@Before Esta anotación fuente de parámetro le dice al sistema de eventos que encuentre el objeto antes que la del tipo especificado por el parámetro de anotación (Esto es equivalente a :javadoc: Cause#before(Class)). Además, el objeto encontrado debe coincidir con el tipo del parámetro. Si no se encuentra ningún objeto que cumpla con estos criterios, no se llamará a su oyente.
En este ejemplo, solo se llamará a su oyente si hay un jugador ubicado antes de un contenedor de extensiones en la causa del evento. El parámetro **``player`` se establecerá en ese jugador.**
@Listener
public void onInteract(InteractBlockEvent.Secondary event, @Before(PluginContainer.class) Player player) {
// do something
}
@After Esto es similar a @ Before, pero en su lugar utiliza :javadoc: Cause#after(Class).
@All This parameter source annotation requires that the annotated parameter be an array type. The returned array
will be equivalent to the contents of calling Cause#allOf(Class). By default, if the returned array would be
empty then the validation fails however this can be disabled by setting ignoreEmpty=false.
En este ejemplo siempre se llamará a su oyente, aunque la formación de jugadores puede estar vacía si la causa del evento no contenía jugadores.
@Listener
public void onInteract(InteractBlockEvent.Secondary event, @All(ignoreEmpty=false) Player[] players) {
// do something
}
@Root Esta anotación de fuente de parámetro obtendrá el objeto raíz de la causa, equivalente a :javadoc: Cause#root(). También realiza una comprobación adicional de que el tipo del objeto raíz coincida con el tipo de su parámetro.
**@Getter**Esta anotación de fuente de parámetro obtendrá un adquiridor en el evento con el nombre especificado. Si el adquiridor especificado devuelve un Optional, @Getter automáticamente desenvolverá el Optional.
**En este ejemplo, intentamos recuperar el valor de **getUseItemResult ** usando la anotación **@Getter **
@Listener
public void onInteract(InteractBlockEvent.Secondary event, @Getter("getUseItemResult") Tristate result) {
// do something
}
Anotaciones de Filtros de Parámetros
Las anotaciones de filtro de parámetros agregan validación adicional a los objetos devueltos a partir de anotaciones de fuente de parámetro. Al igual que con todos los filtros de eventos, si cualquiera de estas validaciones falla, entonces no se llamará a su oyente.
@Admite Este filtro de parámetro se puede aplicar a cualquier tipo de parámetro que sea a :javadoc: DataHolder. Se necesita una clase que extienda :javadoc: DataManipulator como su parámetro y valida que el` DataHolder` anotado soporta el ` DataManipulator` dado. Esta validación es equivalente a :javadoc: CompositeValueStore#supports (Class <? Extends H>).
**En este ejemplo, se llamará al oyente solo si hay una entidad en la causa del evento, y si esa entidad soporta el manipulador de datos ** :javadoc: FlyingData.
@Listener
public void onInteract(InteractBlockEvent.Secondary event, @First @Supports(FlyingData.class) Entity entity) {
// do something
}
@Has Este filtro de parámetros es similar al filtro de parámetros @Supports, excepto que adicionalmente valida que DataHolder contenga una instancia del `` DataManipulator`` proporcionado.
En este ejemplo, se llamará al oyente solo si hay una entidad en la causa del evento, y si esa entidad tiene una instancia de ** ``FlyingData`` **disponible.
@Listener
public void onInteract(InteractBlockEvent.Secondary event, @First @Has(FlyingData.class) Entity entity) {
// do something
}
Nota
Tanto @Has como @Supports tienen un parámetro opcional inverse que se puede configurar para que la validación falle si tiene, o si admite, el DataManipulator de destino.
