Java Network Discovery API

The network discovery API uses UDP multicast to enable clients to locate servers for specific services on a local network, similar to how game servers are located on a LAN.

This API provides basic network discovery, if you need more advanced features, you should check out JGroups.

Features

Downloads

JAR, source and documentation (54KB)
Contains the JAR file, source code and offline Javadoc documentation.

Sample applications (384KB)
Contains 3 sample Eclipse projects: a Java server, a Java client and an Android client.

Using the API

Announcing Servers/Services

A ServiceAnnouncer is responsible for listening for and responding to requests from clients for services that are registered with it. Services are identified using a unique 32-character ID, the intention being that the ID is the MD5 sum of the server application package.

The announcer can respond via the same UDP multicast group or directly to the requesting client using a TCP socket.

A server can announce it's presence in just a few lines of code:

String serviceId = "e9ababe5872f24caf1a504f1d675470c";
String ip = "192.168.0.10";

ServiceAnnouncer announcer = new ServiceAnnouncer();
ServiceInfo si = 
     new ServiceInfo("My Server", serviceId, ip, 3218, false);
announcer.addService(si);
announcer.startListening();

You should call announcer.stopListening() to shut down the internal listener socket and thread.

Finding Servers/Services

A ServiceFinder is used to locate servers on the network. Matching servers are returned through the listener interface.

private static final String SERVICE_ID = "e9ababe5872f24caf1a504f1d675470c";

private void initFinder() {
    ServiceFinder finder = new ServiceFinder(); 
    finder.addListener(mListener);
    finder.startListening();
    finder.findServers(SERVICE_ID, 0);
} 

private ServiceFinder.Listener mListener = new ServiceFinder.Listener() {
    @Override
    public void serverFound(ServiceInfo si, int requestId,
            ServiceFinder finder) {
        System.out.println("Found service provider named " +
                si.getServerName() + " at " + si.getServiceHost() + ":" +
                + si.getServicePort());
    }

    @Override
    public void listenStateChanged(ServiceFinder finder, boolean listening) {
    }
};

You should call finder.stopListening() to shut down the internal listener socket and thread.

Android Support

This API is compatible with Android. When used with Android, the ServiceFinder should be instantiated in TCP mode to avoid unnecessary battery drain. You will need the INTERNET permission in your manifest.

If you want to run the ServiceAnnouncer on an Android device or insist on running the ServiceFinder in multicast mode, your application will need the CHANGE_WIFI_MULTICAST_STATE permission and must obtain a MulticastLock with WifiManager.createMulticastLock(String). This must be done before calling startListening() on the ServiceAnnouncer/ServiceFinder. If you are using multicast on the ServiceFinder, it is recommended you implement a time-out and call stopListening() as soon as possible.

License

This API has been released under a commercially friendly Apache 2 license.