protocol7 home

Introducing Apache Vysper

Vysper logo This is the first in a series of posts I’m planning to do on Apache Vysper. This first post will mostly deal with what Vysper is, later posts will go into details on various ways of using Vysper.

Vysper is an implementation of an XMPP (aka Jabber) server in Java. Vysper is a subproject of Apache MINA and is licensed under Apache License, Version 2.0. Vysper aims to run both standalone as well as embedded into your application. When running embedded, you can closely integrate your application with Vysper, e.g. to share user management or session state. Vysper is still in the early stages, but is certainly usable for early adopters. The currently released version is 0.6, but the example below is based on SVN trunk, which will in the near future become 0.7.

XMPP is specified as two RFCs (RFC 3920, RFC 3921 for the core protocol and a great number of extensions, called XEP:s. Vysper implements the RFCs as part of it’s server core. For many of the extensions, these are implemented as Vysper modules, meaning as a user, you can choose which modules to have run on your server. For example, some might want to use the publish-subscribe extension while others want to use the multi-user chat and service administration modules. XMPP also supports different network protocols, e.g. the main XML-over-TCP/IP protocol, HTTP long-polling (in XMPP-land called BOSH) or websockets. Vysper implements these as so called Endpoints. And as with modules, the user can pick and choose which protocols are desired.

For the exact details of which specifications Vysper support, please check this link.

Configuring Vysper can either be done using the Java API as in the example below, or by using a dependency injection framework. Vysper currently ships with examples for Spring.

Enough theory, let’s look at an example. The code below shows the basics of running Vysper from a simple Java application. Afterwards, we’ll look into what the code actually does.

To get going, you need to download Vysper, in this case from SVN and build it using Maven (these instructions will be updated when Vysper 0.7 is released). The code below will work on 0.6 with some slight modifications. If building from source sounds intimidating, I’ve set up this example as a project on Github, where you can also find archive downloads of the sample with the required dependencies.

 XMPPServer server = new XMPPServer("");
 StorageProviderRegistry providerRegistry = new MemoryStorageProviderRegistry();

 AccountManagement accountManagement = (AccountManagement) providerRegistry.retrieve(AccountManagement.class);

 Entity user = EntityImpl.parseUnchecked("");
 accountManagement.addUser(user, "password");


 server.addEndpoint(new TCPEndpoint());

 server.setTLSCertificateInfo(new File("keystore.jks"), "sekrit");

 System.out.println("Vysper server is running...");

 server.addModule(new EntityTimeModule());
 server.addModule(new VcardTempModule());
 server.addModule(new XmppPingModule());
 server.addModule(new PrivateDataModule());

Number below refer to code lines in the example above.
1. Create the server and provide the domain it will be running on. Users at this domain will be addressed as “”.
3. Create a storage provide registry. This is a service locator for all the different pieces in Vysper which needs to persist stuff, like users or rosters (the list of friends). In this case, we use the simplest implementation, which stores things in memory.
5-8. From the above service locator, get the storage provider for users in order to add a user for testing. XMPP uses user identifiers in the form username@domain, similar to mail. These are called entities. Here, you can probably imaging AccountManagement instead being an implementation which looks up users in LDAP or similar.
10. Set the storage provide registry on the server.
12. As described above, Vysper uses different types of endpoints for the different network protocols. TCPEndpoint implements the core XMPP protocol as described in RFC 3920. It’s required for regular XMPP clients like Adium or Psi to be able to connect to the server. By default, this uses port 5222.
14. Provide a PKI keystore, this enables the server to use SSL when clients connect and ensures that sensitive stuff (passwords as well as conversations) is kept secret.
16. Start the server. Vysper is now running and clients will be able to connect to it. You can try it out with your favourite IM client.
19-22. Here we add modules for some XMPP extensions. Which to use depends largely on the purpose of the server. These must be added after the server is started as they require the server to be fully initiated.

And, that’s it. You now hopefully got a working XMPP server running and you can go play with the other neat features it supports. Also, if you have any further questions, feel free to ask on our mailing list or comment below.

In the next post, I will describe the architecture of Vysper and how messages, called stanzas in XMPP terms, flow through the server.

Tags: , , , . 7 Comments »

7 Responses

  1. Tweets that mention protocol7 Blog Archive Introducing Apache Vysper -- Says:
    […] This post was mentioned on Twitter by Niklas Gustavsson, Planet Apache. Planet Apache said: Niklas Gustavsson: Introducing Apache Vysper […]
  2. Juergen Weber Says:
    “Vysper aims to run both standalone as well as embedded into your application.”

    Vysper would still better integrate into a JEE landscape if it could run within an application server, preferably in Apache Geronimo.
    But deployment in an app server would require that part of Vysper would be a JCA resource adapter, at thread management would have to be controlled by the appserver.
    But this would require giving Mina a JCA facade. So I can come back to my favorite Mina bug ;-)

  3. Niklas Says:
    I would love to have Vysper as a JCA RA, but I don’t see myself hacking on this anytime soon. If you or anyone else would like to work on it, we would be happy to assist :-)
  4. Charlie Youakim Says:
    I’m glad to see Apache moving into XMPP. Great post.

    I’m commenting because I actually have an observation and a question about XMPP and Vysper. I’m here because I’m new to XMPP. Very new. I’ve been looking and testing with it for the last couple of days. My problem is that I don’t feel like the “Presence” portion of the protocol works all that great, at least on my initial tests with Openfire and ejabberd2. If I work as normal, sure, it works perfectly. But, I was a bit harder on it. First I killed my internet connection by disabling wifi through my OS(I tested it in Linux and Windows). XMPP still worked. That’s GREAT!

    The problem was with my next test. I decided to kill my wifi radio by disabling it through hardware. Here’s where I couldn’t get XMPP’s Presence to work. The user on this machine always stayed online, despite the wifi radio being killed through hardware.

    This is something I’ve noticed in Gmail as well. On a user’s computer crash, or power loss, some users can just hang there online.

    My question to users, and to Vysper: Can XMPP handle this case for Presence detection? It seems to me that it can’t, which worries me.

    Thanks for any input,


  5. Niklas Says:
    Charlie, XMPP supports broken sockets by an XMPP server detecting this and sending unavailability presence stanzas. However, in some conditions, detecting a broken socket can be complicated. XMPP therefore supports different types of protocol-level pings (XMPP Pings being the must well-known). Vysper still lacks somewhat in this area in that we do not support XMPP pings from server to client.

    If you would like to discuss this further, feel free to get in contact with the project on our mailing lists.


  6. Charlie Youakim Says:

    So it’s not really an XMPP problem. It’s really a problem with the underlying tech?

    Ya, I’d love to get on the mailing list.

    Thanks Niklas!

  7. Niklas Says:
    Right. Anyways, let’s continue the discussion on the mailing list :-)

Leave a Comment

Please note: Comment moderation is enabled and may delay your comment. There is no need to resubmit your comment.

Creative Commons Attribution 3.0 licensed unless otherwise specified.