Saluran Pesan

Dalam Sponge, setiap objek yang pesan mungkin terkirim untuk mengimplementasikan antarmukan :javadoc:'MessageReceiver'. Sebuah :javadoc:'MessageChannel' adalah sebuah perangkat yang mungkin mengirim pesan semaunya ke sejumlah "MessageReceiver"s dan bahkan melakukan tindakan seperti penerima format dari pesan tertentu.

Memilih Penerima Pesan

Dalam antar muka "MessageChannel ada yang konstanta dan metode statis yang bisa digunakan untuk memperoleh atau membuat yang umumnya digunakan saluran. Ada juga kelas lainnya dan antarmuka yang bisa digunakan untuk membuat sebuah "MessageChannel". seperti :javadoc:'AbstractMutableMessageChannel' dan :javadoc:'MutableMessageChannel'. Sebuah daftar lengkap dari ini bisa ditemukan pada :javadoc:'org.spongepowered.api.text.channel" dan sub-paket itu sendiri.

Penyiaran

Saluran yang paling umum akan menjadi saluran penyiaran. Itu dapat diperoleh dari salah satu :javadoc:'Server' melalui metode :javadoc:'Server#getBroadcastChannel()' atau dari salah satu konstanta :javadoc:'MessageChannel#TO_PLAYERS' atau :javadoc:'MessageChannel#TO_ALL'. Satu-satunya perbedaan adalah "TO_ALL" tidak hanya termasuk setiap pemain yang terhubung ke server tetapi juga server "Console".

Saluran yang dikembalikan oleh "getBroadcastChannel()" umumnya akan menjadi saluran "MessageChannel.TO_ALL, Namun saluran yang berbeda mungkin disetel menggunakan metode :javadoc:'Server#setBroadcastChannel(MessageChannel)'.

Pengiriman untuk Tetap Daftar MessageReceivers

Itu juga mungkin untuk tidak mengirim pesan kepada semua pemain yang terhubung, tetapi untuk sejumlah tangan penerima yang dipilih. Hal ini dapat dilakukan dengan menambahkan daftar penerima yang dimaksudkan untuk metode :javadoc:'MessageChannel#fixed(MessageReceiver...)'. Tidak seperti kebanyakan saluran lainnya, daftar penerima tidak akan dapat dibuat secara dinamis setiap kali sesuatu yang dikirimkan melalui saluran tetapi masih tetapi untuk selebihnya masih tetap statis dari keberadaannya. Namun, acuan-acuan yang diteruskan adalah weak. Ini berarti jika misalnya seorang pemain memutuskan dan sesuai dengan objek :javadoc:'Player' adalah dihapus oleh Java garbage collector, pemain itu juga akan lenyap dari daftar penerima saluran.

Izin-berdasarkan Seleksi

Itu juga mungkin untuk membuat salurang pengiriman untuk semua penerima yang memegang sebuah izin khuhus. Saluran tersebut diperoleh dari metode :javadoc:'MessageChannel#permission(String)' dengan izin untuk memeriksa sebagai argumen. Bila sebuah pesan yang kemudian akan dikirimkan melalui saluran ini, itu akan memperoleh semua subjek dari :javadoc:'PermissionService' yang memiliki izin yang diberikan.

Menggabungkan Saluran

Itu juga mungkin untuk menggabungkan beberapa saluran menjadi satu. Hal ini dapat dilakukan dengan menambahkan semua saluran ke dalam metode :javadoc:'MessageChannel#combine(MessageChannel...)'. Saluran yang dihasilkan akan menyampaikan untuk setiap penerima pesan yang ditargetkan oleh salah satu saluran gabungan.

Mengirimkan Pesan

Setelah anda memperoleh sebuah "MessageChannel" anda dapat mengirim pesan itu melalui metode :javadoc:'MessageChannel#send(Object, Text)'. Metode ini adalah yang lebih disukai metode :javadoc:'MessageChannel#send(Text)'. sebagai "Object" dapat digunakan untuk identifikasi atau untuk melakukan berbagai tindakan-tindakan lainnya. Sebagai alternatif, anda dapat menggunakan sebuah :javadoc:'ChatType' untuk menentukan pesan mana yang akan di kirim. Menggunakan metode :javadoc:'MessageChannel#sent(Object, Text, ChatType)' akan memungkinkan anda untuk menyelesaikan ini. Saluran kemudian akan mengubah pesan dari setiap penerima dan mengirim pesan yang berubah.

Aplikasi yang diperluas: Saluran Obrolan

Saluran pesan mempunyai aplikasi yang sangat berguna yang dapat digunakan untuk membangun saluran obrolan. Misalnya, anda dapat menentukan sebuah saluran pesan untuk setiap saluran obrolan yang ingin anda miliki. Kemudian, ketika sebuah "MessageReceiver" bergabung dengan sebuah saluran, seperti dengan "/join <channel name>", cukup mengatur "MessageReceiver"'s "MessageChannel" untuk sesuaikan saluran menggunakan :javadoc:'MessageReceiver#setMessageChannel(MessageChannel)'. Ini akan menyebabkan setiap pesan yang dikirim from "MessageReceiver untuk dilalui kepada yang diberikan sebagai gantinya "MessageChannel" dari satu default. Sebagai alternatif, anda dapat mendengarkan terhadap :javadoc:'MessageChannelEvent', dan mengatur menyesuaikan "MessageChannel" menggunakan :javadoc:'MessageChannelEvent#setChannel(MessageChannel). Melewati "null" untuk metode yang akan membatalkan penyetelan apapun dari saluran khusus, menyebabkan pesan asli yang akan dikirim ke MessageChannel sebagai gantinya.

Mengubah Pesan

Anda dapat menerapkan sebuah penyaringan untuk semua "Text"s yang lewat melalui sebuah "MessageChannel" untuk mengubah pesan yang meskipun demikian anda sukai. Hal ini dimungkinkan dengan memperluas "MessageChannel" dan metode utama :javadoc:'MessageChannel#transformMessage(Object, MessageReceiver, Text, ChatType)' seperti yang ditunjukkan di bawah ini.

Contoh: Mengubah pesan

Kutipan kode berikut mendefinisikan sebuah kelas "AdminMessageChannel" yang menimpa metode "transformMessage. Metode "transformMessage" baru akan mengambil pesan asli dan menambahkan sebuah tanda merah "[Admin]" ke depan pesan.

import java.util.Collection;
import java.util.Collections;
import java.util.Optional;

import org.spongepowered.api.text.Text;
import org.spongepowered.api.text.channel.MessageChannel;
import org.spongepowered.api.text.channel.MessageReceiver;
import org.spongepowered.api.text.format.TextColors;

public class AdminMessageChannel implements MessageChannel {

    @Override
    public Optional<Text> transformMessage(Object sender, MessageReceiver recipient,
                                                                Text original) {
        Text text = original;
        text = Text.of(TextColors.RED, "[Admin]", TextColors.RESET, text);
        return Optional.of(text);
    }

    @Override
    public Collection<MessageReceiver> getMembers() {
        return Collections.emptyList();
    }
}

Catatan bahwa kita tidak menginginkan untuk menentukan penerima tambahan, jika kita mengembalikan koleksi kosong pada metode :javadoc:'MessageChannel#getMembers()'.

Berkat kemampuan yang digabungkan "MessageChannel"s, kita dapat menggabungkan yang baru diciptakan "AdminMessageChannel" dengan apa saja lainnya "MessageChannel". Sekarang jika seorang pemain bergabung dengan izin "Myplugin.admin, kita akan memperoleh "MessageChannel" pesan yang di kirimnya ke, menggabungkan itu dengan "AdminMessageChannel" dan mengatur saluran gabungan kembali ke pemain. Dengan cara itu semua pesan yang dikirimkan untuk setiap orang yang ditetapkan dalam saluran asli, tetapi karena penambahan dari "AdminMessageChannel", sebuah tanda merah "[Admin]" akan menjadi awalan.

import org.spongepowered.api.entity.living.player.Player;
import org.spongepowered.api.event.Listener;
import org.spongepowered.api.event.network.ClientConnectionEvent;

private AdminMessageChannel adminChannel = new AdminMessageChannel();

@Listener
public void onClientConnectionJoin(ClientConnectionEvent.Join event) {
    Player player = event.getTargetEntity();
    if(player.hasPermission("myplugin.admin")) {
        MessageChannel originalChannel = event.getOriginalChannel();
        MessageChannel newChannel = MessageChannel.combined(originalChannel,
            adminChannel);
        player.setMessageChannel(newChannel);
    }
}

Catatan bahwa awalan ini akan 'all' pesan-pesan yang terkait dengan seorang pemain. Ini termasuk pesan kematian, tinggalkan pesan, dll. Jika anda hanya ingin untuk awal semua pesan 'chat', anda akan perlu untuk mendengarkan :javadoc:'MessageChannelEvent.Chan' dan mengatur saluran ke acara daripada pemain. Ini akan dilakukan menggunakan "event.setChannel(newChannel)" ke acara "MessageChannelEvent.Chat". Untuk mendapatkan pemain dari acara dengan memeriksa izin, anda akan perlu untuk mendapatkan seorang "Player" dari acara "Cause". Seperti yang ditunjukkan di bawah ini:

Optional<Player> playerOptional = event.getCause().<Player>first(Player.class);

Penyebab lebih lanjut dapat ditemukan pada :doc:'cause page <../event/cause>'.

Catatan

Ketika menggabungkan beberapa "MessageChannel"s mendefinisikan pesan transformasi berbeda, "Teks" akan berubah dalam urutan yang "MessageChannel"s yang disampaikan dalam metode "MessageChannel#combined(MessageChannel... channels)". Catatan bahwa setiap transformasi hasilnya secara kosong "Optional" akan diabaikan kecuali kalau dilakukan oleh saluran terakhir dalam rantai.

Bisa Berubah Saluran Pesan

Sebuah :javadoc:'MutableMessageChannel' mengandung metode-metode untuk mengubah siapa yang mungkin dapat menerima pesan yang dikirim melalui saluran kami. Dengan demikian, kita harus melaksanakan metode untuk melakukan tindakan yang mengubah anggota kami. Untuk melakukan ini, kita hanya akan membuat kelas bernama "MutableAdminMessageChannel" yang akan melaksanakan sebuah "MutableMessageChannel".

import java.util.Set;
import java.util.WeakHashMap;

import org.spongepowered.api.text.channel.MutableMessageChannel;

public class MutableAdminMessageChannel implements MutableMessageChannel {

    private Set<MessageReceiver> members;

    public MutableAdminMessageChannel() {
        this(Collections.emptySet());
    }

    public MutableAdminMessageChannel(Collection<MessageReceiver> members) {
        this.members = Collections.newSetFromMap(new WeakHashMap<>());
        this.members.addAll(members);
    }

    @Override
    public Collection<MessageReceiver> getMembers() {
        return Collections.unmodifiableSet(this.members);
    }

    @Override
    public boolean addMember(MessageReceiver member) {
        return this.members.add(member);
    }

    @Override
    public boolean removeMember(MessageReceiver member) {
        return this.members.remove(member);
    }

    @Override
    public void clearMembers() {
        this.members.clear();
    }

    @Override
    public Optional<Text> transformMessage(Object sender, MessageReceiver recipient,
                                                                Text original) {
        Text text = original;
        if(this.members.contains(recipient)) {
            text = Text.of(TextColors.RED, "[Admin]", TextColors.RESET, text);
        }
        return Optional.of(text);
    }
}

Peberdaan utama antara kami "AdminMessageChannel" dan kami yang baru "MutableAdminMessageChannel" adalah bahwa kami memeriksa jika penerima masuk daftar anggota sebelum mengubah pesan. Jika iya, lalu kita mungkin mengubah pesan yang dikirim, menambahkan awalan merah "[Admin]". Dalam metode kami "getMembers()" kami kembali menetapkan sebagai yang kekal, sehingga mengatur hanya dapat diubah oleh metode yang sesuai pada kami "MutableAdminMessageChannel".

Catat bahwa implementasi abstrak untuk "MutableMessageChannel"s ada dalam API Sponge sebagai "AbstractMutableMessageChannel". Ingat juga bahwa anggota kami tidak berlangsung lama. Jika seorang pemain akan meninggalkan server, mereka akan dihapus dari kumpulan.

Memodifikasi Anggota

Untuk membuat penuh pengguna dari kami "MutableAdminMessageChannel", kita perlu untuk bisa dapat menambahkan dan menghapus anggota dari saluran. Untuk melakukan ini, kita dapat secara sederhana untuk seruan metode kami :javadoc:'MutableMessageChannel#addMember(MessageReceiver)' dan :javadoc:'MutableMessageChannel#removeMember(MessageReceiver)' sebelumnya kami implementasikan kapanpun kami perlu untuk menambahkan dan menghapus seorang anggota dari kumpulan anggota.