Distributed Storage

The P2P infrastructure of las2peer provides a distributed data storage architecture. To ensure data consistency when nodes add or leave the network, all data are reproduced and stored redundantly on multiple nodes.

To keep data across node restarts, a node must not change its id! This is guaranteed by setting the node id launch paramter --node-id-seed . Otherwise, a node will generate a random node id per start. See L2pNodeLauncher Commands

Any Java object with the Serializable interface can be stored inside the network. Each object (called Envelope) is identified by a unique id. The developer is free to use any String as identifier. A good practice is to start with the service or application name and attach a finer grained application internal id.

The content of envelopes is encrypted with its readers' (any Agent object) keys. In most cases the acting UserAgent or main agent should be used as only reader.

Fetching data from the network

To fetch an object from the network you have to fetch its covering Envelope object first by calling:

Envelope env = getContext().fetchEnvelope(YourIdentifier);

Then you can extract your Serializable data object with:

YourSerializable data = (YourSerializable) env.getContent(SomeReaderAgent);

or using the contexts main agent with:

YourSerializable data = (YourSerializable) env.getContent();

Persisting data inside the network

The following code shows how the usual storage procedure works. This code uses the context's main agent as only reader and author (recommended). If you want to use some other agents than that, see below.

Envelope env = null;
try {
	// first check if a previous version for the given identifier exists
	env = getContext().fetchEnvelope(YourIdentifier);
	// create a subsequent envelope with the new content
	env = getContext().createEnvelope(env, YourNewContent);
} catch (ArtifactNotFoundException e) {
	env = getContext().createEnvelope(YourIdentifier, YourNewContent);
}
// store the new version in the network
getContext().storeEnvelope(env);

Group access

multiple readers

If you want multiple agents to have read access on an envelope, you have to use one of the following methods:

Either providing a list of agents:

env = getContext().createEnvelope(env, YourNewContent, YourAgentList);

or listing them as arguments:

env = getContext().createEnvelope(env, YourNewContent, YourFirstReader, YourSecondReader, ...);

multiple authors

If you want several Agents to write to an Envelope object, you can use a GroupAgent as author of an Envelope.

First you create a GroupAgent with:

GroupAgent group = GroupAgent.createGroupAgent(Agent[] members);

Unlock it using an unlocked member:

group.unlockPrivateKey(Agent member);

Store it in the node:

getContext().getLocalNode().storeAgent(group);

Then you can use this Agent as author for storing like shown above.

The GroupAgent has to be unlocked to read content from an Envelope!

Unencrypted Content Envelopes

An envelope can be created as unencrypted entity. This means the content is readable to everyone. However the content is still signed by an author agent and changes are only permitted to this author.

The content of an unencrypted envelope is readable to everyone with:

YourSerializable data = (YourSerializable) env.getContent();