org.kitteh.irc.client.library

Interface Client

All Known Subinterfaces:

Client.WithManagement

All Known Implementing Classes:

DefaultClient

public interface Client

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

Method Detail

builder

@Nonnull
static Client.Builder builder()

Creates a Client.Builder to build clients.

Returns:

a client builder

addChannel

void addChannel(@Nonnull
                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(@Nonnull
                            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 the named channel.

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