Link to Martyr resources on SourceForge.

Martyr - A Java IRC Library

Last updated: 2007-12-18.

Subversion is usually more recent than that.

What is martyr?

Martyr is a framework (library) for the IRC Protocol, written entirely in Java, for Java programs. Martyr could be used as the foundation for a bot or a client written in Java. The goal for the Martyr project is to have a complete IRC client framework encompassing all the features of modern IRC, but to be fully separate from any client implementation.

The name, martyr, comes from St. Justin Martyr, the catholic patron saint of speakers.

Instant gratification:

Martyr is being actively developed along side of several other projects that use Martyr. Martyr does not and will not contain any special code to manage bots, however it is already being used to create bots that can take part in a conversation. Special features specific to bots is considered another, as yet unstarted, project.

Martyr is intended for use by Java developers only! Martyr will be of no use whatsoever if you are looking for an IRC client. Martyr is distributed under the LGPL, and is copyright f00f networks, 2001.


Martyr Version 0.4

Martyr uses ant for compilation. You can download the martyr source code and a pre-built jar here. You can download Justin, a simple bot that uses Martyr, here. Justin is mainly a proving ground for Martyr.

Projects that use Martyr


To be useful as a framework, Martyr aims to be well documented. Click here to browse the javadocs. Martyr also includes documentation describing its overall structure, and contains at least one test program showing how to use Martyr.

The Martyr distribution includes the javadocs.

If you have any questions about what Martyr is, how you can use it, or to find out how you can help develop martyr, please send an email to me,


Martyr is designed to be flexible and extendable, rather than fast or small, in terms of number of classes. Information from the server is stored in the ClientState and Commands are parsed and sent out from the IRCConnection class as events. For example, every command that is sent to or from the server is represented as an object. The class of a command is intended to contain all of the knowledge required to deal with that command. Command classes can generate instances of a command and they know how a command affects the client state. Commands are sent as events to command listeners, in a fashion similar to how AWT events work.

A number of classes that provide common functionality are provided. These classes include:

  1. AutoReconnect - Maintains a connection to a server.
  2. AutoJoin - Maintains a presence in a channel.
  3. AutoRegister - Registers on the network, including different nick attempts.
  4. AutoResponder - Provides "reflex" functions, such as responding to pings and asking for a channel's mode upon joining.
  5. AutoDccSetup - Listens for notifications of DCC connections and aids in setting them up.


The Future

Martyr "the next generation" is currently in the early design stages. Focus will be on simplification, testability, and better support of diverse feature sets (ie server hinting). The current martyr framework works well for stand alone applications, but problems emerge when using martyr based clients in a services context. Also the current architecture is overcomplicated, leading to difficulties maintaining a clean threading model. Finally, martyr is showing its age with an outdated package hierachy, use of JDK 1.1 features, a custom logging solution, etc, and this needs to be modernized.

The new martyr will require Java 5 as a base platform. This will allow a wealth of features to be included, such as built-in SSL support, use of generics and atomic operations, and better IO handling with fewer threads (simplifying the threading model).


Perhaps martyr isn't quite what you are looking for. Here are some other IRC libraries.

Please let me know if I've left your project off the list!


Ben Damm