Developer API

If you are a developer, ChatControl offers you several method to implement its functionality into your plugin. See the following classes to learn how you can benefit from ChatControl's API.

At present, the vast majority of the API focuses on the Chat Channels.

ChannelAPI

The main API class, containing the core method to manipulate with player chat channels.

package me.kangarko.chatcontrol.api;

import java.util.ArrayList;
import java.util.List;
import java.util.Objects;

import org.bukkit.entity.Player;

import me.kangarko.chatcontrol.ChatControl;
import me.kangarko.chatcontrol.channels.Channel;
import me.kangarko.chatcontrol.channels.ChannelManager;
import me.kangarko.chatcontrol.channels.PlayerChannelCache;

public class ChannelAPI {

	/**
	 * Return amount of channels installed.
	 * 
	 * @return the amount of loaded chat channels
	 */
	public static int getChannelCount() {
		return ChannelManager.channelCount();
	}
	
	/**
	 * Lookups for a channel by specified name. Must be configured within the plugin first.
	 * Returns the channel, or throws an error if it doesn't exist.
	 * 
	 * @param name the name of the channel
	 * @return the channel
	 */
	public static ChatChannel getChannel(String name) {
		Channel ch = ChannelManager.getChannel(name);
		Objects.requireNonNull(ch, "Channel by the name '" + name + "' does not exist");
		
		return new ChatChannel(ch);
	}

	/**
	 * Get all available channels
	 */
	public static List<ChatChannel> getChannels() {
		List<ChatChannel> channels = new ArrayList<>();
		for (Channel ch : ChannelManager.getChannels())
			channels.add(new ChatChannel(ch));
		
		return channels;
	}
	
	/**
	 * Check if a player is spying on channel.
	 * 
	 * NB: Exception thrown if not in channel.
	 * 
	 * @param channel the channels
	 * @return if the player is spying on channel
	 */
	public static boolean isReceivingOnly(Player pl, String channelName) {
		return getChannelCache(pl).isReceivingOnly(ChannelManager.getChannel(channelName));
	}

	public static void setChannel(Player pl, String channelName) {
		final PlayerChannelCache cache = getChannelCache(pl);
		
		if (!hasNoWriteChannels(pl))
			cache.onChannelLeave(cache.getWriteChannel(), pl);
		
		getChannelCache(pl).onChannelJoin(ChannelManager.getChannel(channelName), pl);
	}
	
	/**
	 * Checks if the player is in channel.
	 * 
	 * @param channel the channel
	 * @return if the player is in channel
	 */
	public static boolean isInChannel(Player pl, String channelName) {
		return getChannelCache(pl).isInChannel(ChannelManager.getChannel(channelName));
	}

	/**
	 * Checks if the player has at least one channel he can write into.
	 * Channels the player spies on, are not counted.
	 * 
	 * @return true if player has at least one channel he/she can write into
	 */
	public static boolean hasNoWriteChannels(Player pl) {
		return getChannelCache(pl).hasNoWriteChannels();
	}

	/**
	 * Gets the channel player can write into. Spy channels are not counted.
	 * 
	 * NB: Exception thrown if has not any.
	 * NB: Player is only allowed to be joined in one channel. Error thrown otherwise.
	 * 
	 * @return the channel player is joined to
	 */
	public static ChatChannel getWriteChannel(Player pl) {
		return new ChatChannel(getChannelCache(pl).getWriteChannel());
	}

	/**
	 * Get channels player is spying on.
	 */
	public static List<ChatChannel> getSpyChannels(Player pl) {
		List<ChatChannel> channels = new ArrayList<>();
		for (String name : getChannelCache(pl).getSpyChannels())
			channels.add(new ChatChannel(name));
		
		return channels;
	}
	
	private static PlayerChannelCache getChannelCache(Player pl) {
		return ChatControl.getDataFor(pl).channels;
	}
}

ChatChannel

A class representing a single chat channel instance.

package me.kangarko.chatcontrol.api;

import java.util.List;

import org.bukkit.entity.Player;

import me.kangarko.chatcontrol.channels.Channel;
import me.kangarko.chatcontrol.channels.ChannelManager;

/**
 * Represents a chat channel.
 */
public class ChatChannel {

	private final Channel handle;

	/**
	 * Create a new instance of a channel from an existing channel in-game.
	 * The channel to be created must be configured within chat.yml in ChatControl already.
	 * 
	 * @param channelName the name of the channel
	 */
	public ChatChannel(String channelName) {
		this(ChannelManager.getChannel(channelName));
	}
	
	ChatChannel(Channel handle) {
		this.handle = handle;
	}
	
	public boolean equals(Object paramObject) {
		return handle.equals(paramObject);
	}
	
	Channel getHandle() {
		return handle;
	}
	
	public void broadcastMessage(String message) {
		handle.broadcastMessage(message);
	}
	
	public void setRange(int range) {
		handle.setRange(range);
	}

	public void setLogFormat(String logFormat) {
		handle.setLogFormat(logFormat);
	}

	public void setSave(String path, String format) {
		handle.setSave(path, format);
	}

	public void setBungee() {
		handle.setBungee();
	}

	public void setPermission(String permission) {
		handle.setPermission(permission);
	}

	public String getName() {
		return handle.getName();
	}

	public boolean isLogged() {
		return handle.isLogged();
	}

	public List<Player> getPlayers() {
		return handle.getAllRecipients();
	}
	
	public String toString() {
		return handle.toString();
	}
}

ChatChannelEvent

An event that is executed when players send their message to a chat channel.

package me.kangarko.chatcontrol.api;

import java.util.List;

import org.bukkit.command.CommandSender;
import org.bukkit.entity.Player;
import org.bukkit.event.Cancellable;
import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;

import me.kangarko.chatcontrol.channels.Channel;

/**
 * An event that is executed when players send their message to a chat channel.
 */
public final class ChatChannelEvent extends Event implements Cancellable {
	
    private static final HandlerList handlers = new HandlerList();
    
    private final Channel channel;
    private List<Player> recipients;
    private String message;
    private String formatter;
    private CommandSender sender;
    
    private boolean cancelled;

    public ChatChannelEvent(Channel channel, List<Player> recipients, String message, String formatter, CommandSender sender) {
    	this.channel = channel;
    	this.recipients = recipients;
    	this.message = message;
    	this.formatter = formatter;
    	this.sender = sender;
    }

    public ChatChannel getChannel() {
        return new ChatChannel(channel);
    }

    public List<Player> getRecipients() {
		return recipients;
	}
    
    public String getMessage() {
		return message;
	}
    
    public void setMessage(String message) {
		this.message = message;
	}
    
    public String getFormatter() {
		return formatter;
	}
    
    public void setFormatter(String formatter) {
		this.formatter = formatter;
	}
    
    public CommandSender getSender() {
		return sender;
	}
    
    public void setSender(CommandSender sender) {
		this.sender = sender;
	}
    
    public boolean isCancelled() {
        return cancelled;
    }

    public void setCancelled(boolean cancel) {
        cancelled = cancel;
    }

    public HandlerList getHandlers() {
        return handlers;
    }

    public static HandlerList getHandlerList() {
        return handlers;
    }
}

PrivateMessageEvent

package me.kangarko.chatcontrol.api;

import org.bukkit.command.CommandSender;
import org.bukkit.event.Cancellable;
import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;

/**
 * An event that is executed when players send a message via /reply or /tell.
 * 
 * This is fired before we determine whether the receiver is valid, online,
 * or whether to send the message over bungee.
 */
public final class PrivateMessageEvent extends Event implements Cancellable {
	
    private static final HandlerList handlers = new HandlerList();
    
    private final CommandSender sender;
    private CommandSender recipient;
    
    private String message;
    
    private boolean cancelled;

    public PrivateMessageEvent(CommandSender sender, CommandSender recipient, String message) {
    	this.sender = sender;
    	this.recipient = recipient;        	
    	this.message = message;
    }
    
    public CommandSender getSender() {
		return sender;
	}
    
    public CommandSender getRecipient() {
		return recipient;
	}
    
    public void setRecipient(CommandSender recipient) {
		this.recipient = recipient;
	}
    
    public String getMessage() {
		return message;
	}
    
    public void setMessage(String message) {
		this.message = message;
	}
    
    
    public boolean isCancelled() {
        return cancelled;
    }

    public void setCancelled(boolean cancel) {
        cancelled = cancel;
    }

    public HandlerList getHandlers() {
        return handlers;
    }

    public static HandlerList getHandlerList() {
        return handlers;
    }
}

PreRuleMatchEvent

package me.kangarko.chatcontrol.api;

import org.bukkit.entity.Player;
import org.bukkit.event.Cancellable;
import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;

/**
 * An event that is executed when a rule or a handler matches
 * a message.
 * 
 * The event is fired before the rule edits the message in any way.
 */
public final class PreRuleMatchEvent extends Event implements Cancellable {
	
    private static final HandlerList handlers = new HandlerList();
    
    private final Player player;
    private String message;
    private final String regex;
    private final String ruleId;
    
    private boolean cancelled;

    public PreRuleMatchEvent(Player player, String message, String regex, String ruleId) {
    	this.player = player;
    	this.message = message;
    	this.regex = regex;
    	this.ruleId = ruleId;
    }
    
    public Player getPlayer() {
		return player;
	}
    
    public String getMessage() {
		return message;
	}
    
    public void setMessage(String message) {
		this.message = message;
	}
    
    public String getRegex() {
		return regex;
	}
    
    public String getRuleId() {
		return ruleId;
	}
    
    public boolean isCancelled() {
        return cancelled;
    }

    public void setCancelled(boolean cancel) {
        cancelled = cancel;
    }

    public HandlerList getHandlers() {
        return handlers;
    }

    public static HandlerList getHandlerList() {
        return handlers;
    }
}

ChannelJoinEvent

package me.kangarko.chatcontrol.api;

import org.bukkit.command.CommandSender;
import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;

import me.kangarko.chatcontrol.channels.Channel;

/**
 * An event that is executed when a player joins a channel.
 */
public final class ChannelJoinEvent extends Event {

	private static final HandlerList handlers = new HandlerList();

	private final Channel channel;
	private CommandSender player;

	public ChannelJoinEvent(Channel channel, CommandSender player) {
		this.channel = channel;
		this.player = player;
	}

	public ChatChannel getChannel() {
		return new ChatChannel(channel);
	}

	public CommandSender getPlayer() {
		return player;
	}

	@Override
	public HandlerList getHandlers() {
		return handlers;
	}

	public static HandlerList getHandlerList() {
		return handlers;
	}
}

ChannelLeaveEvent

package me.kangarko.chatcontrol.api;

import org.bukkit.command.CommandSender;
import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;

import me.kangarko.chatcontrol.channels.Channel;

/**
 * An event that is executed when a player leaves a channel.
 */
public final class ChannelLeaveEvent extends Event {

	private static final HandlerList handlers = new HandlerList();

	private final Channel channel;
	private CommandSender player;

	public ChannelLeaveEvent(Channel channel, CommandSender player) {
		this.channel = channel;
		this.player = player;
	}

	public ChatChannel getChannel() {
		return new ChatChannel(channel);
	}

	public CommandSender getPlayer() {
		return player;
	}

	@Override
	public HandlerList getHandlers() {
		return handlers;
	}

	public static HandlerList getHandlerList() {
		return handlers;
	}
}