content/vysper-project/extending_server.mdtext

Title: Vysper Extending the Server
Notice:    Licensed to the Apache Software Foundation (ASF) under one
           or more contributor license agreements.  See the NOTICE file
           distributed with this work for additional information
           regarding copyright ownership.  The ASF licenses this file
           to you under the Apache License, Version 2.0 (the
           "License"); you may not use this file except in compliance
           with the License.  You may obtain a copy of the License at
           .
             http://www.apache.org/licenses/LICENSE-2.0
           .
           Unless required by applicable law or agreed to in writing,
           software distributed under the License is distributed on an
           "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
           KIND, either express or implied.  See the License for the
           specific language governing permissions and limitations
           under the License.


# How to extend the server functionality

## XMPP support for extensions

[XMPP](http://www.xmpp.org/) provides a bunch of already specified extensions. See <http://www.xmpp.org/extensions> for a complete list.

XMPP also allows for custom extensions of the core stanza types 'message', 'iq' and 'presence'. All XMPP clients and servers should be able to savely ignore them unless they are able to deal with them. See the [relevant specification chapter](http://www.xmpp.org/internet-drafts/draft-saintandre-rfc3920bis-05.html#stanzas-extended).

Most XMPP extensions rely on Disco (Service Discovery, XEP-0030).
It's easy to integrate modules with Vysper's Disco extension.

Most XMPP extensions rely on Disco ([Service Discovery, XEP-0030](http://xmpp.org/extensions/xep-0030.html)).
It's easy to integrate modules with [Vysper's Disco extension](service_discovery.html).

## Modules

Regardless which kind of extension it is (Vysper internal, XMPP standardized or home-brewn) they all can be deployed using the Vysper Modules.

Vysper Modules are implementations of interface org.apache.vysper.xmpp.modules.Module, but it is probably more convenient to extend DefaultModule. Modules supporting disco should extend DefaultDiscoAwareModule.

An example of a Vysper-internal module is org.apache.vysper.xmpp.modules.roster.RosterModule.

## Handlers and Dictionaries

Every incoming stanza is processed by one dedicated StanzaHandler instance. For implementing a new functionality, we'd have to code new StanzaHandlers. They are registered with the server. The server introspects the stanza and decides which handler is tailored for it by basically looking at the stanza name ('message'/'iq'/'presence') and the namespace attributes ('xmlns') on the top and first-child XML elements.

Dictionary objects are used to compile handlers for the same namespace.

## A custom handler

It is highly recommended that custom handlers do subclass

* org.apache.vysper.xmpp.modules.core.base.handler.DefaultIQHandler
* org.apache.vysper.xmpp.modules.core.base.handler.MessageHandler
* org.apache.vysper.xmpp.modules.core.im.handler.PresenceHandler

## Activate a module in the server

Modules are registered with the server calling ServerRuntimeContext.addModule(Module module).

Using spring-config.xml, they are configured in bean 'server'. Simply add a new bean for the module to the config. Then add a bean reference to property 'modules' list in 'server'. On server startup, these modules are loaded and activated.