Getting Started

Christian Lüthold edited this page Mar 9, 2015 · 9 revisions

Getting the Binaries

There are three easy ways to get and include the Hive2Hive library into your project.

If you just want to use the library, either refer to option 1 or 2.
If you want to contribute to the project, please refer to option 3.

Option 1: Add Maven Dependency

You can add the latest stable release as an Apache Maven dependency and fetch it from our repository. Add the following to your pom.xml and make sure to select the most recent version.


Option 2: Add JAR-file directly

In case you don't want to use Maven, you can just download the latest stable release that comes directly with all necessary sources. All required .jar-files are packed and delivered to you as a .zip.

Option 3: Clone from GitHub

If you want to contribute to the Hive2Hive library project, this is what you should do. Cloning from GitHub gets the bleeding edge of development and thus some sources might not be stable. So this option is not recommended if you just want to use the library.

API Demonstration

The Hive2Hive library provides a simple API that is straightforward to use. (View Source) A short demonstration of the API and its basic usage are given here.

Network Management

Creating a P2P Network

Configuring and setting up a new P2P network is very easy. Just specify the configurations and setup an initial node.

  1. The NetworkConfiguration and FileConfiguration factory classes may help to specify your configurations.
  2. Create an initial peer node and connect it.
INetworkConfiguration netConfig = NetworkConfiguration.create("first");
IFileConfiguration fileConfig = FileConfiguration.createDefault();

IH2HNode peerNode = H2HNode.createNode(netConfig, fileConfig);

Joining an Existing P2P Network

You may want to add other peer nodes to the created network. Any node can join by bootstrapping to another node that is already part of the network.

  1. Specify the network configuration for the joining node (i.e., provide the bootstrap address of another node).
  2. Create the new node and connect it. It will bootstrap according to its network configuration.
INetworkConfiguration netConfig2 = NetworkConfiguration.create("second", InetAddress.getByName(""));
IH2HNode peerNode2 = H2HNode.createNode(netConfig2, fileConfig);

User Management

Once a peer node is connected to a network, users can interact with it. For this, each node provides a user management interface.

  1. The user has to provide her credentials.
  2. Login the user to the network. If it's the first login, she has to register herself, one-time.
  3. Then, the user can interact with the network (i.e., file management is enabled).
IUserManager userManager = peerNode.getUserManager();

UserCredentials credentials = new UserCredentials("userId", "password", "pin");
Path rootDirectory = Paths.get("sample/path/to/rootDirectory");

if (!userManager.isRegistered(credentials.getUserId())) {
userManager.login(credentials, rootDirectory).await();

File Management

As soon as a user is logged in to the network, her files are automatically synchronized with the current node. Many further file operations are available. For this, each node provides a file management interface.

  • add / delete file
  • update / recover file
  • share file with another user
  • move file
IFileManager fileManager = peerNode.getFileManager();

File folder = new File("folderpath");
File file = new File(folder, "filepath");



fileManager.share(folder, "other-userId", PermissionType.WRITE);

IVersionSelector versionSelector = new IVersionSelector() {
	public IFileVersion selectVersion(List<IFileVersion> availableVersions) {
		return availableVersions.get(0);
fileManager.recover(file, versionSelector);

fileManager.move(folder, new File("other-folder"));


File Watchdog

In order to keep track of changes in the local file system, a file observer is needed. This observer notifies its attached listeners about all file system events. Either use the provided H2HFileObserver and H2HFileObserverListener or implement your own observer adhering to the IFileObserver and IFileObserverListener interfaces.
The H2HFileObserverListener automatically synchronizes the Hive2Hive root folder with the network.

IFileObserverListener listener = new H2HFileObserverListener(fileManager);

IFileObserver observer = new H2HFileObserver(rootDirectory.toFile());

Project Structure

The Hive2Hive library comprises multiple projects. The intention of this section is to give an abstracted overview of these projects and their corresponding package structure.


As the name describes, this project contains the core functionality of the library. In particular, different aspects are placed in different packages:

org.hive2hive.X Description
.api Contains the interfaces and default implementations used for the library’s API. (i.e., configurations, network creation, user and file managers, etc.)
.exceptions Consists of specific exception classes of the library. (e.g., network exceptions, DHT exceptions, encryption exceptions)
.file Contains some utility classes concerning file synchronization and internal file operations, such as read/write from the local hard disk, etc.
.log Comprises classes for the logger and its configuration.
.model Holds the [[Hive2Hive Model
.network Contains the interaction logic with the network and the DHT. This includes basic operations like bootsrapping, connection and DHT operations. Also, many types of diverse messages are defined here.
.processes Defines all process steps for the library’s functionalities.
.security Contains the security modules of the library. This includes encryption implementations, password generation, etc.


This project contains some runnables for testing purposes:

Runnable Description A console-based client that is used to test the library API, the configurations and the underlying core functionalities. A sample implementation of a file observer that automatically interacts with the library API on any file system events.
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.