Title: Vysper Service Discovery
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.


# Using Service Discovery

## Disco quick start

Service Discovery (or 'disco') is a XMPP extensions specified at (Service Discovery, XEP-0030).

Disco resembles Directory services like LDAP, or even file systems.

Disco is a server-side service. It maintains a tree of nodes (branches) and items (leafs). Clients discover child nodes and items of the root node or some other already discovered node by sending info-requests (IQ stanzas).
The server replies with a IQ response containing a list of nodes and items.

## Using disco

In Vysper, Disco is itself implemented as a module (making it easy to swap disco implementations). The disco module must be loaded to link into it.

Any module can publish its own features, nodes and items through disco to become 'discoverable' by clients and other servers and to expose 'stuff', whatever makes sense for that module.

It is highly recommended that modules supporting disco extend DefaultDiscoAwareModule, which provides convenient integration with disco.

Via DefaultDiscoAwareModule overrides, modules can register listeners for disco requests. If applicable, they simply add their part to the response. So, the disco-aware module has full control over the stuff it exposes.

## The most simple form of disco is to advertise a feature. Clients knowing about that feature can then use it, for example by adding special payload to stanzas, by interacting with the module through dedicated stanzas or by using more disco.

This is how a feature is advertised in the XEP-0092 implementation:

	:::java
	public class SoftwareVersionModule extends DefaultDiscoAwareModule implements ServerInfoRequestListener { 
	    @Override 
	    protected void addServerInfoRequestListeners(List<ServerInfoRequestListener> serverInfoRequestListeners) { 
	        serverInfoRequestListeners.add(this); 
	    } 
 
	    public List<InfoElement> getServerInfosFor(InfoRequest request) { 
	        List<InfoElement> infoElements = new ArrayList<InfoElement>(); 
	        infoElements.add(new Feature(NamespaceURIs.JABBER_IQ_VERSION)); 
	        return infoElements; 
	    } 
	} 

At init time, the listener is registered, which is the module class itself ("this").
On every disco request occuring on server level, disco calls the listener via getServerInfosFor(), and the module advertises its support for XEP-0092. Please note that in an advanced scenario, we can make the module's behavior depending on the properties of the InfoRequest parameter.

## Item and Info discovery

They work similar, with similar listeners and callback.
TODO: elaborate!