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
}

Bu dinleyici, normalde InteractBlockEvent uzanan tüm olaylar için çağrılır. Bununla birlikte Exclude notu dinleyicinizin InteractBlockEvent.Primary olayı için çağrılmasını engeller (yalnızca InteractBlockEvent.Secondary olayı bırakılıyor).

Bir örnek Include şu şekilde olabilir:

@Listener
@Include({DamageEntityEvent.class, DestructEntityEvent.class})
public void onEvent(EntityEvent 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 Bu ek açıklama, etkinlik dinleyicinizin normalde çağrılma anındaki iptal durumuna göre filtreleme işlemlerine izin verir. Varsayılan olarak, etkinlik bir önceki olay dinleyicisi tarafından iptal edildiğinde etkinlik dinleyiciniz çağrılmaz. Bununla birlikte, bu davranışı, IsCancelled ek açıklamasında Tristate değerine bağlı olarak üç durumdan birine değiştirebilirsiniz.

• 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 Bu parametre kaynağı açıklaması, açıklanan parametrenin bir dizi türü olmasını gerektirir. Döndürülen dizi çağrı içeriğine eşdeğer olacaktır Cause#allOf(Class). Varsayılan olarak, döndürülen dizi boş kalırsa, doğrulama başarısız olur ancak bu, ignoreEmpty=false olarak ayarlanarak devre dışı bırakılabilir.

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.

@Named Bu parametre kaynağı açıklaması, olay sistemine, ek açıklama parametresi tarafından belirtilen adla nesneyi bulmasını söyler (Buna eşdeğerdir Cause#get(String, Class)). 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 NamedCause.OWNER adıyla ilişkili bir oyuncu varsa çağırılacaktır ** player ** parametresi o oyuncuya ayarlanacaktır. **

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

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