public interface Command
This interface defines the format for the implementation of commands that can be called for via the messaging input field.
A new command object is instantiated for each encounter. Then
execute(java.lang.String, java.lang.String)
is called to execute the command.
Instantiation will be done by the CommandFactory. The CommandFactory expects to find a constructor with the following types as arguments (in order):
If no suitable constructor is found, an BadCommandException
will be
thrown.
For more advanced IRC commands, one can register listeners with the underlying IRC client. This way you can intercept IRC messages as they are received. Using this method you can send messages, receive replies and act on (other) events.
In the case of more advanced commands that register message listeners, please base your listeners on the AbstractIrcMessageListener or ensure by yourself that listeners get unregistered upon ERROR or QUIT events. It is expected that a listener that gets registered can determine for themselves when to unregister itself in order to properly dispose of it.
Modifier and Type | Method and Description |
---|---|
void |
execute(java.lang.String source,
java.lang.String line)
Execute the command using the full line.
|
java.lang.String |
help()
Return help information to output.
|
void execute(java.lang.String source, java.lang.String line)
source
- the source channel/user from which the message is sent.
(Note that for a normal message this would then be the
target/receiver of the message too.)line
- the command message linejava.lang.IllegalArgumentException
- Special meaning has been given to
IllegalArgumentException: it signals bad usage of a command.
Jitsi will consequently call help()
to query a help
message that will be passed on as a system message to the
user.java.lang.IllegalStateException
- IllegalStateException signals bad usage of
a command given the current state, i.e. called at the wrong
time. Jitsi will consequently call help()
to query a
help message that will be passed on as a system message to
the user.java.lang.String help()
help()
is called whenever a command execution fails with
IllegalArgumentException
or an IllegalStateException
.
IllegalArgumentException suggests that the command was called
incorrectly. IllegalStateException suggests that the command was called
at the wrong time, when it is not appropriate to call this command. The
help information will then be displayed to explain the user how to use
the command.
Since a new command instance is constructed for each command message, the
help message can be adapted to reflect the earlier call to
execute(java.lang.String, java.lang.String)
, if any.
Jitsi, the OpenSource Java VoIP and Instant Messaging client.
Distributable under Apache license.