org.kitteh.irc.client.library

Interface Client

All Superinterfaces:

ClientLinked

All Known Subinterfaces:

Client.WithManagement

All Known Implementing Classes:

DefaultClient

public interface Client
extends ClientLinked

An individual IRC connection, see builder() to create one.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Client.Builder Builds Clients.
static interface	Client.Commands Provides commands.
static interface	Client.WithManagement A Client with management features.

Method Summary

Modifier and Type	Method and Description
void	addChannel(String... channels) Adds channels to this client.
void	addKeyProtectedChannel(Pair<String,String>... channelsAndKeys) Adds key-protected channels to this client.
void	addKeyProtectedChannel(@NonNull String channel, @NonNull String key) Adds a key-protected channel to this client.
static @NonNull Client.Builder	builder() Creates a Client.Builder to build clients.
@NonNull Client.Commands	commands() Provides access to Commands.
void	connect() Begin connecting to the server.
@NonNull AuthManager	getAuthManager() Gets the authentication manager.
@NonNull CapabilityManager	getCapabilityManager() Gets the capability manager.
@NonNull Optional<Channel>	getChannel(@NonNull String name) Gets a snapshot of known information about a named channel, if the channel is being tracked by the client.
@NonNull Set<Channel>	getChannels() Gets the channels in which the client is currently present.
@NonNull Set<Channel>	getChannels(@NonNull Collection<String> channels) Gets the channels on the given collection in which the client is currently present.
default @NonNull Client	getClient() Gets the Client to which this belongs.
@NonNull DefaultMessageMap	getDefaultMessageMap() Gets the message manager for default messages to reply with when certain messages are being sent.
@NonNull EventManager	getEventManager() Gets the client's event manager.
@NonNull Listener<Exception>	getExceptionListener() Gets the exception listener.
@NonNull String	getIntendedNick() Gets the nickname the client intends to possess.
@NonNull ISupportManager	getISupportManager() Gets the manager of ISUPPORT info.
@NonNull Cutter	getMessageCutter() Gets the current message cutter for multi-line messages.
@NonNull Function<Client.WithManagement,? extends MessageSendingQueue>	getMessageSendingQueueSupplier() Gets the message sending queue supplier.
@NonNull MessageTagManager	getMessageTagManager() Gets the message tag manager.
@NonNull String	getName() Gets the client name.
@NonNull String	getNick() Gets the current nickname the client has.
@NonNull ServerInfo	getServerInfo() Gets information about the server to which the client is currently connected.
@NonNull Optional<StsMachine>	getStsMachine() Gets the STS machine instance, if one is in use.
@NonNull Optional<User>	getUser() Gets the User that the client is represented by.
@NonNull Optional<ModeStatusList<UserMode>>	getUserModes() Gets the user's modes.
default boolean	isUser(@Nullable User user) Checks to see if this client is the same as the given user.
void	knockChannel(@NonNull String channelName) KNOCKs on a +i (but not +p) channel, requesting an INVITE.
void	reconnect() Triggers a reconnect, quitting with the default DefaultMessageType.RECONNECT message.
void	reconnect(@Nullable String reason) Triggers a reconnect, quitting with the given reason.
void	removeChannel(@NonNull String channel) Removes a channel from the client, leaving as necessary.
void	removeChannel(@NonNull String channel, @Nullable String reason) Removes a channel from the client, leaving as necessary.
default void	sendCtcpMessage(@NonNull MessageReceiver target, @NonNull String message) Sends a CTCP message to a target user or channel.
void	sendCtcpMessage(@NonNull String target, @NonNull String message) Sends a CTCP message to a target user or channel.
default void	sendCtcpReply(@NonNull MessageReceiver target, @NonNull String message) Sends a CTCP reply to a target user or channel.
void	sendCtcpReply(@NonNull String target, @NonNull String message) Sends a CTCP reply to a target user or channel.
default void	sendMessage(@NonNull MessageReceiver target, @NonNull String message) Sends a message to a target user or channel.
void	sendMessage(@NonNull String target, @NonNull String message) Sends a message to a target user or channel.
default void	sendMultiLineMessage(@NonNull MessageReceiver target, @NonNull String message) Sends a potentially multi-line message to a target user or channel using the client's current Cutter.
default void	sendMultiLineMessage(@NonNull MessageReceiver target, @NonNull String message, @NonNull Cutter cutter) Sends a potentially multi-line message to a target user or channel using the defined Cutter.
default void	sendMultiLineMessage(@NonNull String target, @NonNull String message) Sends a potentially multi-line message to a target user or channel using the client's current Cutter.
void	sendMultiLineMessage(@NonNull String target, @NonNull String message, @NonNull Cutter cutter) Sends a potentially multi-line message to a target user or channel using the defined Cutter.
default void	sendMultiLineNotice(@NonNull MessageReceiver target, @NonNull String message) Sends a potentially multi-line notice to a target user or channel using the client's current Cutter.
default void	sendMultiLineNotice(@NonNull MessageReceiver target, @NonNull String message, @NonNull Cutter cutter) Sends a potentially multi-line notice to a target user or channel using the defined Cutter.
default void	sendMultiLineNotice(@NonNull String target, @NonNull String message) Sends a potentially multi-line notice to a target user or channel using the client's current Cutter.
void	sendMultiLineNotice(@NonNull String target, @NonNull String message, @NonNull Cutter cutter) Sends a potentially multi-line notice to a target user or channel using the defined Cutter.
default void	sendNotice(@NonNull MessageReceiver target, @NonNull String message) Sends a notice to a target user or channel.
void	sendNotice(@NonNull String target, @NonNull String message) Sends a notice to a target user or channel.
void	sendRawLine(@NonNull String message) Sends a raw IRC message.
void	sendRawLineAvoidingDuplication(@NonNull String message) Sends a raw IRC message, unless the exact same message is already in the queue of messages not yet sent.
void	sendRawLineImmediately(@NonNull String message) Sends a raw IRC message, disregarding message delays and all sanity.
void	setDefaultMessageMap(@NonNull DefaultMessageMap defaults) Sets the message manager for default messages to reply with when certain messages are being sent.
void	setExceptionListener(@Nullable Consumer<Exception> listener) Sets a listener for all thrown exceptions on this client.
void	setInputListener(@Nullable Consumer<String> listener) Sets a listener for all incoming messages from the server.
void	setMessageCutter(@NonNull Cutter cutter) Sets the default message cutter to use for multi-line messages.
void	setMessageSendingQueueSupplier(@NonNull Function<Client.WithManagement,? extends MessageSendingQueue> supplier) Sets the message sending queue supplier.
void	setNick(@NonNull String nick) Sets the nick the client wishes to use.
void	setOutputListener(@Nullable Consumer<String> listener) Sets a listener for all outgoing messages to the server.
void	shutdown() Shuts down the client without a quit message.
void	shutdown(@Nullable String reason) Shuts down the client.

Method Detail

builder

static @NonNull Client.Builder builder()

Creates a Client.Builder to build clients.

Returns:

a client builder

addChannel

void addChannel(String... channels)

Adds channels to this client.

Joins the channels if already connected.

Parameters:

channels - channel(s) to add

Throws:

IllegalArgumentException - if null or invalid

See Also:

RequestedChannelJoinCompleteEvent, UnexpectedChannelLeaveEvent

addKeyProtectedChannel

void addKeyProtectedChannel(@NonNull String channel,
                            @NonNull String key)

Adds a key-protected channel to this client.

Joins the channels if already connected.

Parameters:

channel - channel to add

key - channel key

Throws:

IllegalArgumentException - if null or invalid

addKeyProtectedChannel

void addKeyProtectedChannel(Pair<String,String>... channelsAndKeys)

Adds key-protected channels to this client.

Joins the channels if already connected.

Parameters:

channelsAndKeys - pairs of channel, key

Throws:

IllegalArgumentException - if null or invalid

commands

@NonNull Client.Commands commands()

Provides access to Commands.

Returns:

commands

getAuthManager

@NonNull AuthManager getAuthManager()

Gets the authentication manager.

Returns:

auth manager

getCapabilityManager

@NonNull CapabilityManager getCapabilityManager()

Gets the capability manager.

Returns:

the capability manager

getChannel

@NonNull Optional<Channel> getChannel(@NonNull String name)

Gets a snapshot of known information about a named channel, if the channel is being tracked by the client. Results should be expected after the client has joined the channel, and will contain as much information as is available to the client at the time of the request.

Parameters:

name - channel name

Returns:

a channel snapshot of the named channel if tracked by the client

Throws:

IllegalArgumentException - if name is null

See Also:

getChannels()

getChannels

@NonNull Set<Channel> getChannels()

Gets the channels in which the client is currently present.

Returns:

the client's current channels

getChannels

@NonNull Set<Channel> getChannels(@NonNull Collection<String> channels)

Gets the channels on the given collection in which the client is currently present.

Parameters:

channels - collection of channel names to get

Returns:

the client's current channels that are named in the collection

getDefaultMessageMap

@NonNull DefaultMessageMap getDefaultMessageMap()

Gets the message manager for default messages to reply with when certain messages are being sent. Like a KICK, PART, or QUIT reason.

Returns:

the DefaultMessageMap

getEventManager

@NonNull EventManager getEventManager()

Gets the client's event manager.

Returns:

the event manager for this client

getExceptionListener

@NonNull Listener<Exception> getExceptionListener()

Gets the exception listener.

Returns:

the exception listener

getIntendedNick

@NonNull String getIntendedNick()

Gets the nickname the client intends to possess. May not reflect the current nickname if it's taken. The client will automatically attempt to take back this nickname.

Use getNick() for the current nick.

Returns:

the nickname the client tries to maintain

getStsMachine

@NonNull Optional<StsMachine> getStsMachine()

Gets the STS machine instance, if one is in use.

Returns:

the machine, may not be present

getISupportManager

@NonNull ISupportManager getISupportManager()

Gets the manager of ISUPPORT info.

Returns:

the ISUPPORT manager

getMessageCutter

@NonNull Cutter getMessageCutter()

Gets the current message cutter for multi-line messages.

Returns:

message cutter

getMessageSendingQueueSupplier

@NonNull Function<Client.WithManagement,? extends MessageSendingQueue> getMessageSendingQueueSupplier()

Gets the message sending queue supplier. Default supplies a SingleDelaySender with a delay of 1200.

Returns:

the supplier

getMessageTagManager

@NonNull MessageTagManager getMessageTagManager()

Gets the message tag manager.

Returns:

message tag manager

getName

@NonNull String getName()

Gets the client name. This name is just an internal name for reference and is not visible from IRC.

Returns:

the client name

getNick

@NonNull String getNick()

Gets the current nickname the client has.

Returns:

the current nick

getServerInfo

@NonNull ServerInfo getServerInfo()

Gets information about the server to which the client is currently connected. As long as the client remains connected the information returned by this object will update according to information received from the server. A new one can be acquired from ClientNegotiationCompleteEvent

Returns:

the server information object

getUser

@NonNull Optional<User> getUser()

Gets the User that the client is represented by. Will return Optional.empty() until the Client is in a Channel for which joining has completed, meaning full user info is available.

Returns:

the user of this client if known

getUserModes

@NonNull Optional<ModeStatusList<UserMode>> getUserModes()

Gets the user's modes. Will return Optional.empty() until the Client has queried this information, which is requested after the connection registration has completed.

Returns:

user modes of this client if known

isUser

default boolean isUser(@Nullable User user)

Checks to see if this client is the same as the given user.

Parameters:

user - user to check this client against

Returns:

true if this client is the user, false if not

knockChannel

void knockChannel(@NonNull String channelName)

KNOCKs on a +i (but not +p) channel, requesting an INVITE.

Parameters:

channelName - the channel to send the KNOCK for.

reconnect

void reconnect()

Triggers a reconnect, quitting with the default DefaultMessageType.RECONNECT message.

reconnect

void reconnect(@Nullable String reason)

Triggers a reconnect, quitting with the given reason.

Parameters:

reason - disconnect reason

removeChannel

void removeChannel(@NonNull String channel)

Removes a channel from the client, leaving as necessary.

Parameters:

channel - channel to leave

Throws:

IllegalArgumentException - if arguments are null

removeChannel

void removeChannel(@NonNull String channel,
                   @Nullable String reason)

Removes a channel from the client, leaving as necessary.

Parameters:

channel - channel to leave

reason - part reason

Throws:

IllegalArgumentException - if channel is null

sendCtcpMessage

void sendCtcpMessage(@NonNull String target,
                     @NonNull String message)

Sends a CTCP message to a target user or channel. Automagically adds the CTCP delimiter around the message and escapes the characters that need escaping when sending a CTCP message.

Note: CTCP replies should not be sent this way. Catch the message with the PrivateCtcpQueryEvent and reply there or use sendCtcpReply(String, String)

Parameters:

target - the destination of the message

message - the message to send

Throws:

IllegalArgumentException - for null parameters

sendCtcpMessage

default void sendCtcpMessage(@NonNull MessageReceiver target,
                             @NonNull String message)

Sends a CTCP message to a target user or channel. Automagically adds the CTCP delimiter around the message and escapes the characters that need escaping when sending a CTCP message.

Note: CTCP replies should not be sent this way. Catch the message with the PrivateCtcpQueryEvent and reply there or use sendCtcpReply(MessageReceiver, String)

Parameters:

target - the destination of the message

message - the message to send

Throws:

IllegalArgumentException - for null parameters

sendCtcpReply

void sendCtcpReply(@NonNull String target,
                   @NonNull String message)

Sends a CTCP reply to a target user or channel. Automagically adds the CTCP delimiter around the message and escapes the characters that need escaping when sending a CTCP message.

Parameters:

target - the destination of the message

message - the message to send

Throws:

IllegalArgumentException - for null parameters

sendCtcpReply

default void sendCtcpReply(@NonNull MessageReceiver target,
                           @NonNull String message)

Sends a CTCP reply to a target user or channel. Automagically adds the CTCP delimiter around the message and escapes the characters that need escaping when sending a CTCP message.

Parameters:

target - the destination of the message

message - the message to send

Throws:

IllegalArgumentException - for null parameters

sendMessage

void sendMessage(@NonNull String target,
                 @NonNull String message)

Sends a message to a target user or channel.

Parameters:

target - the destination of the message

message - the message to send

Throws:

IllegalArgumentException - for null parameters

sendMessage

default void sendMessage(@NonNull MessageReceiver target,
                         @NonNull String message)

Sends a message to a target user or channel.

Parameters:

target - the destination of the message

message - the message to send

Throws:

IllegalArgumentException - for null parameters

sendNotice

void sendNotice(@NonNull String target,
                @NonNull String message)

Sends a notice to a target user or channel.

Parameters:

target - the destination of the message

message - the message to send

Throws:

IllegalArgumentException - for null parameters

sendNotice

default void sendNotice(@NonNull MessageReceiver target,
                        @NonNull String message)

Sends a notice to a target user or channel.

Parameters:

target - the destination of the message

message - the message to send

Throws:

IllegalArgumentException - for null parameters

sendMultiLineMessage

default void sendMultiLineMessage(@NonNull String target,
                                  @NonNull String message)

Sends a potentially multi-line message to a target user or channel using the client's current Cutter.

Note that bots may not react appropriately to a message split across multiple lines.

Parameters:

target - the destination of the message

message - the message to send

Throws:

IllegalArgumentException - for null parameters

sendMultiLineMessage

void sendMultiLineMessage(@NonNull String target,
                          @NonNull String message,
                          @NonNull Cutter cutter)

Sends a potentially multi-line message to a target user or channel using the defined Cutter.

Note that bots may not react appropriately to a message split across multiple lines.

Parameters:

target - the destination of the message

message - the message to send

cutter - cutter to utilize

Throws:

IllegalArgumentException - for null parameters

sendMultiLineMessage

default void sendMultiLineMessage(@NonNull MessageReceiver target,
                                  @NonNull String message)

Sends a potentially multi-line message to a target user or channel using the client's current Cutter.

Note that bots may not react appropriately to a message split across multiple lines.

Parameters:

target - the destination of the message

message - the message to send

Throws:

IllegalArgumentException - for null parameters

sendMultiLineMessage

default void sendMultiLineMessage(@NonNull MessageReceiver target,
                                  @NonNull String message,
                                  @NonNull Cutter cutter)

Sends a potentially multi-line message to a target user or channel using the defined Cutter.

Note that bots may not react appropriately to a message split across multiple lines.

Parameters:

target - the destination of the message

message - the message to send

cutter - cutter to utilize

Throws:

IllegalArgumentException - for null parameters

sendMultiLineNotice

default void sendMultiLineNotice(@NonNull String target,
                                 @NonNull String message)

Sends a potentially multi-line notice to a target user or channel using the client's current Cutter.

Note that bots may not react appropriately to a message split across multiple lines.

Parameters:

target - the destination of the message

message - the message to send

Throws:

IllegalArgumentException - for null parameters

sendMultiLineNotice

void sendMultiLineNotice(@NonNull String target,
                         @NonNull String message,
                         @NonNull Cutter cutter)

Sends a potentially multi-line notice to a target user or channel using the defined Cutter.

Note that bots may not react appropriately to a message split across multiple lines.

Parameters:

target - the destination of the message

message - the message to send

cutter - cutter to utilize

Throws:

IllegalArgumentException - for null parameters

sendMultiLineNotice

default void sendMultiLineNotice(@NonNull MessageReceiver target,
                                 @NonNull String message)

Sends a potentially multi-line notice to a target user or channel using the client's current Cutter.

Note that bots may not react appropriately to a message split across multiple lines.

Parameters:

target - the destination of the message

message - the message to send

Throws:

IllegalArgumentException - for null parameters

sendMultiLineNotice

default void sendMultiLineNotice(@NonNull MessageReceiver target,
                                 @NonNull String message,
                                 @NonNull Cutter cutter)

Sends a potentially multi-line notice to a target user or channel using the defined Cutter.

Note that bots may not react appropriately to a message split across multiple lines.

Parameters:

target - the destination of the message

message - the message to send

cutter - cutter to utilize

Throws:

IllegalArgumentException - for null parameters

sendRawLine

void sendRawLine(@NonNull String message)

Sends a raw IRC message.

Parameters:

message - message to send

Throws:

IllegalArgumentException - if message is null

sendRawLineAvoidingDuplication

void sendRawLineAvoidingDuplication(@NonNull String message)

Sends a raw IRC message, unless the exact same message is already in the queue of messages not yet sent.

Parameters:

message - message to send

Throws:

IllegalArgumentException - if message is null

sendRawLineImmediately

void sendRawLineImmediately(@NonNull String message)

Sends a raw IRC message, disregarding message delays and all sanity. Live life on the wild side with this method designed to ensure you get flood-kicked before you finish dumping your life's work into chat.

Parameters:

message - message to send dangerously, you monster

Throws:

IllegalArgumentException - if message is null

setExceptionListener

void setExceptionListener(@Nullable Consumer<Exception> listener)

Sets a listener for all thrown exceptions on this client.

All exceptions are passed from a single, separate thread.

Parameters:

listener - catcher of throwable objects

setDefaultMessageMap

void setDefaultMessageMap(@NonNull DefaultMessageMap defaults)

Sets the message manager for default messages to reply with when certain messages are being sent. Like a KICK, PART, or QUIT reason.

Parameters:

defaults - DefaultMessageMap to set

setInputListener

void setInputListener(@Nullable Consumer<String> listener)

Sets a listener for all incoming messages from the server.

All messages are passed from a single, separate thread.

Parameters:

listener - input listener

setMessageCutter

void setMessageCutter(@NonNull Cutter cutter)

Sets the default message cutter to use for multi-line messages.

Parameters:

cutter - cutter to set

setMessageSendingQueueSupplier

void setMessageSendingQueueSupplier(@NonNull Function<Client.WithManagement,? extends MessageSendingQueue> supplier)

Sets the message sending queue supplier.

Parameters:

supplier - the supplier

setNick

void setNick(@NonNull String nick)

Sets the nick the client wishes to use.

Parameters:

nick - new nickname

Throws:

IllegalArgumentException - if nick is null

setOutputListener

void setOutputListener(@Nullable Consumer<String> listener)

Sets a listener for all outgoing messages to the server.

All messages are passed from a single, separate thread.

Parameters:

listener - output listener

connect

void connect()

Begin connecting to the server.

Throws:

IllegalStateException - if the client is already connecting

shutdown

void shutdown()

Shuts down the client without a quit message.

shutdown

void shutdown(@Nullable String reason)

Shuts down the client.

Parameters:

reason - quit message to send

getClient

default @NonNull Client getClient()

Description copied from interface: ClientLinked

Gets the Client to which this belongs.

Specified by:

getClient in interface ClientLinked

Returns:

the client