Etkinlik filtreleri

Etkinliklerle çalışmak için biraz zaman harcadıysanız, muhtemelen bir olay dinleyicisi yazarken çok sık kontrol ettiğiniz bazı ön koşulların olduğunu fark ettiniz. Etkinlik filtreleri, olayın otomatik olarak geçerliliğini doğrulamanıza izin verilerek size yardımcı olan ek açıklamalar grubudur ve doğrulama başarısız olursa dinleyiciniz çağrılamaz. Bu, dinleyicinizin koşulları yerine işlemeçinizin mantığına ayrılmış olmasını ve daha temiz bir kod üretilmesini sağlar.

Etkinlik filtreleri, etkinlik türü filtreleri ve parametre filtreleri olmak üzere iki çeşittir.

Olay türü filtreleri, dinleyicinize, Listener ek açıklamasıyla birlikte uygulanan yöntem ek açıklamalarıdır ve olayın türüne veya durumuna dayalı çeşitli filtreler sağlar.

Parametre filtreleri, olay gibi, olay nedeni gibi nesneleri doğrulamaktadır. Ayrıca iki çeşit parametre kaynağı ve parametre filtresi bulunur. Her ek parametrenin bir kaynak açıklamasına sahip olması ve isteğe bağlı olarak herhangi bir sayıda filtre açıklaması içerebilmesi gerekir.

Etkinlik türü filtreleri

@Include/@Exclude Bu iki parametre, aldığınız olayları daraltarak dinlediğiniz olayın genişleyen olayların bir alt kümesi gibi AffectEntityEvent gibi üst öğe türü etkinlikleri dinlemek için birlikte kullanılır.

Örneğin:

@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).

Bir örnek Include şu şekilde olabilir:

@Listener
@Include({DamageEntityEvent.class, DestructEntityEvent.class})
public void onEvent(TargetEntityEvent event) {
    // do something
}

Bu dinleyici normalde tüm EntityEvents için çağrılır, ancak Include açıklaması sadece onu almayı daraltır DamageEntityEvent ve DestructEntityEvent.

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

• IsCancelled notu mevcut değilse, Tristate.FALSE varsayılan davranış ve olayı iptal edildiğinde dinleyiciyi aramayacaktır.

• Tristate.UNDEFINED, dinleyicinizin olayın iptal durumundan bağımsız olarak çağrılmasına neden olur.

• Tristate.TRUE, dinleyicinizin yalnızca olay öncesi bir olay dinleyicisi tarafından iptal edildiğinde çağrılmasına neden olur.

Parametre filtreleri

Parametre filtreleri, etkinlik içindeki nesnelere dayalı olarak filtrelemenizi sağlar. Bu ek açıklamalar, kaynak ve filtre olmak üzere iki tür gelir. Normal olay parametresinin ötesinde, dinleyiciniz için her ek parametre, tam olarak bir kaynak açıklaması gerektirir ve isteğe bağlı olarak herhangi bir sayıda filtre açıklaması içerebilir.

Parametre Kaynağı Ek Açıklamaları

Parametre kaynak notları, olay sistemine bu parametrenin değerini nereden bulması gerektiğini bildirir. Bu, olay nesnesinin kendisinin bir üyesindeki veya üyelerindeki olaylarda olabilir.

@First Bu parametre kaynağı açıklaması, olay sistemine, olayın nedeninde parametrenizin türüne uyan ilk nesneyi bulmasını söyler (Bu, aşağıdakine denktir Cause#first(Class)). Bu parametre ile eşleşen herhangi bir nesne bulunamazsa, dinleyiciniz çağırılmaz.

** Bu örnekte, dinleyiciniz yalnızca olayın içinde bir oyuncu varsa çağrılır ve ** player ** parametresi ilk oyuncuya davayı açar. **

@Listener
public void onInteract(InteractBlockEvent.Secondary event, @First Player player) {
    // do something
}

@Last Bu, @First’e benzer ancak bunun yerine :javadoc:`Son#(Class)` `çağrısı yapar.

@Listener
public void onInteract(InteractBlockEvent.Secondary event, @Last Player player) {
    // do something
}

@Before Bu parametre kaynağı açıklaması, olay sistemine, ek açıklama parametresi tarafından belirtilen türden birinin öncesinde nesneyi bulmasını söyler (Bu, javadoc:Cause#before(Class)’a eşdeğerdir). Ayrıca, bulunan nesne parametrenin türüne uymalıdır. Bu ölçütleri karşılayan herhangi bir nesne bulunamazsa, dinleyiciniz çağrılmaz.

**Bu örnekte dinleyiciniz, yalnızca olayın nedeninde bir eklenti konteynerinden önce bulunan bir oyuncu varsa çağrılır. ** player ** parametresi o oyuncuya ayarlanacaktır. **

@Listener
public void onInteract(InteractBlockEvent.Secondary event, @Before(PluginContainer.class) Player player) {
    // do something
}

@After Bu, @Before benzer, fakat bunun yerine 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.

Bu örnekte, dinleyiciniz her zaman çağrılır; ancak olayın nedeni hiçbir oyuncu içermiyorsa, players dizisi boş olabilir.

@Listener
public void onInteract(InteractBlockEvent.Secondary event, @All(ignoreEmpty=false) Player[] players) {
    // do something
}

@Root Bu parametre kaynağı açıklaması sebebin kök objesini alacaktır, buna eşdeğerdir Cause#root(). Ayrıca, kök nesnesinin türünün sizin parametrenizin türüne uyduğuna dair ek bir kontrol gerçekleştirir.

@Getter Bu parametre kaynağı açıklaması, etkinlik üzerinde belirtilen adla bir alıcı getirecektir. Belirtilen alıcı bir Optional``döndürürse, ``@Getter otomatik olarak Optional’ı açar.

Bu örnekte getUseItemResult ** değerini ** @Getter ** açıklama özelliğini kullanarak almaya çalışıyoruz. **

@Listener
public void onInteract(InteractBlockEvent.Secondary event, @Getter("getUseItemResult") Tristate result) {
    // do something
}

Parametre Filtresi Ek Açıklamaları

Parametre filtre ek açıklamaları, parametre kaynağı ek açıklamalardan döndürülen nesnelere ek doğrulama ekler. Tüm etkinlik filtrelerinde olduğu gibi, bu doğrulamalardan herhangi biri başarısız olursa dinleyiciniz çağrılamaz.

@Supports Bu parametre filtresi DataHolder olan herhangi bir parametre türüne uygulanabilir. Bir sınıfı genişletir DataManipulator parametresi olarak ve açıklanan DataHolder’ın verili Manipülatörü desteklediğini doğrular. Bu doğrulama eşdeğerdir CompositeValueStore#supports(Class<? extends H>).

**Bu örnekte, dinleyicinin adı yalnızca olayın içinde bir varlık varsa ve o varlık ** :javadoc:’FlyingData’ veri manuel aracısını destekliyorsa çağrılır.

@Listener
public void onInteract(InteractBlockEvent.Secondary event, @First @Supports(FlyingData.class) Entity entity) {
    // do something
}

@Has Bu parametre filtresi, DataHolder’ın verilen DataManipulator`ün bir örneğini de içerdiğini doğrulamak dışında @Supports parametre filtresine benzemektedir.

** Bu örnekte, dinleyicinin çağrılması yalnızca olayın içinde bir varlık varsa ve o varlık ** FlyingData ** örneğine sahipse mümkündür.**

@Listener
public void onInteract(InteractBlockEvent.Secondary event, @First @Has(FlyingData.class) Entity entity) {
    // do something
}

Not

Hem @Has hem de @Supports opsiyonel bir parametre olan ``inverse``e sahiptir; bu, eğer hedef DataManipulator’e sahipse ya da desteklemiyorsa, doğrulamanın başarısız olmasına neden olabilir.