Introduction in 5 Minutes – Put and Get

In order to create a P2P network with TomP2P, all peers need to:

  1. Create an identity
  2. Listen for incoming connections
  3. Bootstrap to a known peer in the P2P network
  4. Start application specific communication

In the following example, the application is a mapping service that maps a name to a value. So, first we create an identity, listen for incoming connections, and bootstrap to a well known peer in our constructor. The bootstrapping in this example is done via broadcasting, so both peers need to be reachable via layer 2. We assume that the well known peer listens on port 4001. The application can store and retrieve key and values. If you have 3 arguments in the main method, then a name and its value are stored, if you have 2 arguments, the key is queried. For simplicity, all operations are blocking.

import net.tomp2p.futures.FutureDHT;
import net.tomp2p.futures.FutureBootstrap; 
import net.tomp2p.p2p.Peer;
import net.tomp2p.p2p.PeerMaker;
import net.tomp2p.peers.Number160;
public class ExampleSimple {

    final private Peer peer;

    public ExampleSimple(int peerId) throws Exception {
        peer = new PeerMaker(Number160.createHash(peerId)).setPorts(4000 + peerId).makeAndListen();
        FutureBootstrap fb = peer.bootstrap().setBroadcast().setPorts(4001).start();
        if (fb.getBootstrapTo() != null) {

    public static void main(String[] args) throws NumberFormatException, Exception {
        ExampleSimple dns = new ExampleSimple(Integer.parseInt(args[0]));
        if (args.length == 3) {
  [1], args[2]);
        if (args.length == 2) {
            System.out.println("Name:" + args[1] + " IP:" + dns.get(args[1]));

    private String get(String name) throws ClassNotFoundException, IOException {
        FutureDHT futureDHT = peer.get(Number160.createHash(name)).start();
        if (futureDHT.isSuccess()) {
            return futureDHT.getData().getObject().toString();
        return "not found";

    private void store(String name, String ip) throws IOException {
        peer.put(Number160.createHash(name)).setData(new Data(ip)).start().awaitUninterruptibly();

To run this example, you first have to start the well known peer on port 4001:

java ExampleSimple 1

Then you can add as many other clients as you want:

java ExampleSimple 2

The output should look something like IP:

Introduction in 30 Minutes – Put and Get Example with Futures

First, a peer with an ID has to be created. You can either set a random peer ID, or you can create the peer with a KeyPair, which takes a public key and generates the ID (SHA-1) out of this key. In addition you can add various parameters and configuration options to the PeerMaker class. The example below shows the creating of a peer with a random ID.

Random rnd = new Random();
Peer peer = new PeerMaker(new Number160(rnd)).setPorts(4001).makeAndListen();

The next example shows the creating of a peer with a public / private key.

KeyPairGenerator gen = KeyPairGenerator.getInstance("DSA");
KeyPair pair1 = gen.generateKeyPair();
Peer peer = new PeerMaker( pair1 ).setPorts(4001).makeAndListen();

Since its a P2P network, we need some more peers. You can either create a new peer and listen to another port, or you can attach a new peer to an existing port. The later is more resource friendly and many thousands of peers can be created.

Peer another = new PeerMaker(new Number160(rnd)).setMasterPeer(peer).makeAndListen();

Before we bootstrap, we need to discover if our peer is behind a NAT and if TomP2P needs to configure NAT via UPNP

FutureDiscover future =;

The next step in a P2P network is to bootstrap. Lets bootstrap another to peer. For now we use awaitUninterruptibly to wait for the result. The future concept is explained in the next section.

FutureBootstrap future = another.bootstrap().setPeerAddress(peer.getPeerAddress()).start();

In order to store data in TomP2P, the object needs to be wrapped with the Data class. The data class offers additional features, such as setting a TTL or signing the object. Then, put or add is called, which starts the routing process, finds the peers close to nr, where the data is stored.

Data data = new Data("test");
Number160 nr = new Number160(rnd);
FutureDHT futureDHT = peer.put(nr).setData(data).start();

A proper shutdown is initiated by calling shutdown() from the master peer.



Since TomP2P uses non-blocking communication, a future object is used to keep track of future results. Thus, a get().start(), put().start(), or add().start() returns immediately and the future object is used to get the results from those operations. Most of the time the following code will not work as expected, since the get().start() returns immediately:

FutureDHT futureDHT = master.get(nr).start();
//you need to call futureDHT.awaitUninterruptibly() to get any data;

There are two options to get the data from the future object. The first is by blocking and waiting for the result to arrive, which can be either await() or awaitUninterruptibly(). The second option is to add a listener, which gets called whenever a result is ready. It is preferred to use this second option and avoid blocking, because in the worst case, you might cause a deadlock if await() is called from a wrong (I/O) thread. If such a listener is used, then the listeners gets called in all cases. If no peer replies, the timeout handler triggers the listener.

futureDHT.addListener(new BaseFutureAdapter<FutureDHT>() {
 public void operationComplete(FutureDHT future) throws Exception
   if(future.isSuccess()) { // this flag indicates if the future was successful
   } else {

Under the hood, TomP2P uses the future concept in many places, for example the routing process is entirely based on futures objects and listeners.

Introduction into getting TomP2P work on the Internet

Most of the examlpes run on the same host to make it easier to test them. Since TomP2P is meant to run on many hosts, the following examples show how to set up TomP2P on multiple hosts. These examples cover the setup of the peers, since the operations such as put() an get() do not change.

Random r = new Random();
Bindings b = new Bindings();
// create a peer with a random peerID, on port 4000, listening to the interface eth0
Peer peer = new PeerMaker(new Number160(r)).setPorts(4000).setBindings(b).makeAndListen();

This snippet creates a peer and listens on the interface eth0. If b.addInterface("eth0"); is ommited, the peer listens to all interfaces. Lets assume this snippet runs on host A with IP address and on host B with IP address, then the following snippet connects host A to host B.

InetAddress address = Inet4Address.getByName("");
FutureDiscover futureDiscover = address ).setPorts( 4000 ).start();
FutureBootstrap futureBootstrap = peer.bootstrap().setInetAddress( address ).setPorts( 4000 ).start();

For more information about setBehindFirewall(true), please read UPNP NAT and Port Forwarding detection in the advanced topics.